跳转到主要内容

​
开始使用过滤的流 webhook（回调接口）API

v2 过滤的流 webhook（回调接口）API 在设置筛选规则方面与 v2 过滤的流 endpoint 类似。不同之处在于传递匹配你规则的 Posts 的机制。
  • 对于 v2 过滤的流 endpoint，你需要建立持久连接并监听匹配你规则的 Posts。
  • 对于本过滤的流 webhook endpoint，你需要注册你的 webhook，X 会将匹配你规则的 Posts 发送到你的 webhook。
本指南介绍如何使用过滤的流 webhook endpoints 设置筛选并接收 Posts。共涉及 3 个步骤：
  1. 设置你的过滤的流规则
  2. 创建你的 webhook
  3. 将你的 Filtered Stream 实例关联到你的 webhook
一旦你将 Filtered Stream 实例关联到你的 webhook，X 会把匹配你规则的 Posts 发送到你的 webhook。

​
设置你的过滤流规则

过滤流规则由一个或多个运算符组成，这些运算符通过布尔逻辑和括号组合，用于定义哪些 Post 将被传递到你的 webhook（回调接口）。过滤流 webhook（回调接口）API 使用与 v2 过滤流 endpoint 相同的一组 endpoint 来创建和管理规则。请参阅这篇详细指南，了解如何构建过滤条件。

​
创建你的 webhook（回调接口）

在 X API 中注册一个可公开访问的 HTTPS URL，即可创建 webhook 以接收事件。Webhooks 必须能够处理用于 CRC 验证的 GET 请求，以及用于事件负载的 POST 请求。有关创建和管理 webhooks 的详细步骤，请参阅Webhooks 入门文档。 注意： 如果你已经在 Account Activity API (AAA) 中使用了 webhooks，那么那里设置的 webhooks 在这里完全通用。实际上，只要带宽充足并能区分不同事件，你可以将 AAA 所使用的同一 webhook endpoint 用于此 API。

​
将你的过滤的流实例链接到你的 webhook（回调接口）

在设置好规则并创建 webhook 后，将该 webhook 链接到你的过滤的流实例。这会将匹配到的 Post 事件路由到你的 webhook URL。 使用 endpoint：POST /2/tweets/search/webhooks/:webhook_id 你可以包含与 streaming endpoint /2/tweets/search/stream 中使用的相同 query 参数，例如 expansions、fields 和媒体选项。这样可自定义事件负载中包含的 data。 示例： 
curl --request POST \ 
  --url 
'https://api.x.com/2/tweets/search/webhooks/123456789012345678?ex
pansions=author_id&user.fields=username,name,id' \ 
  --header 'Authorization: Bearer $BEARER_TOKEN'
成功的响应示例： 
{ 
  "data": { 
    "provisioned": true
  } 
}
提示： 你可以将多个 webhook（回调接口）关联到同一个 stream，用于冗余或接收不同的字段集。每个关联都可以指定独立的参数。 一旦将 Filtered Stream 实例关联到 webhook（回调接口），即可开始接收与规则匹配的 Posts，如下所示： 
{
    "data": {
        "id": "1346889436626259968",
        "text": "了解如何使用 X API v2 中的用户 Post 时间线和用户提及时间线 endpoint 来探索 Post… https://t.co/56a0vZUx7i",
        "created_at": "2021-01-06T18:40:40.000Z",
        "author_id": "2244994945"
    },
    "includes": {
        "users": [
            {
                "id": "2244994945",
                "name": "开发者",
                "username": "Xdevelopers",
                "created_at": "2013-12-14T04:35:55Z",
                "protected": false
            }
        ]
    },
    "matching_rules": [
        {
            "id": "120897978112909812",
            "tag": "api-posts"
        }
    ]
}

​
检索与过滤的流关联的 webhook（回调接口）

检索当前与过滤的流关联的所有 webhook（回调接口）列表： 
GET /2/tweets/search/stream/webhooks
示例响应： 
{
    "data": {
        "links": [
            {
                "application_id": "29893711",
                "business_user_id": "1877374016438091776",
                "fields": [
                    "user.fields=username",
                    "name",
                    "id",
                    "expansions=author_id"
                ],
                "instance_id": "1877375130462289920",
                "webhook_id": "1952390923729424384"
            }
        ]
    }
}

​
取消将你的 webhook（回调接口）与过滤的流的关联

要停止在特定 webhook（回调接口）上接收事件，请使用以下方式取消关联： 
DELETE /2/tweets/search/webhooks/:webhook_id
响应结果如下： 
{
    "data": {
        "deleted": true
    }
}
⌘I