跳转到主要内容

​
开始使用 filtered stream webhooks API

在设置过滤规则方面，v2 filtered stream webhooks API 与 v2 filtered stream endpoint 类似。不同之处在于向符合你规则的 Post 的投递机制。
  • 使用 v2 filtered stream endpoint 时，你需要建立持久连接并监听符合你规则的 Post。
  • 使用本 filtered stream webhook endpoint 时，你需要注册你的 webhook，X 会将符合你规则的 Post 投递到你的 webhook。
本指南说明如何使用 filtered stream webhooks endpoints 进行过滤并接收 Post。共分为 3 个步骤：
  1. 设置你的 filtered stream 规则
  2. 创建你的 webhook
  3. 将你的 Filtered Stream 实例关联到你的 webhook
将你的 Filtered Stream 实例关联到你的 webhook 后，X 会把符合你规则的 Post 发送到你的 webhook。

​
设置你的过滤流规则

过滤流规则由一个或多个运算符组成，并通过布尔逻辑与括号组合，以定义哪些 Post 将被送达你的 webhook。过滤流 webhook API 使用与 v2 过滤流端点 相同的一组端点来创建和管理规则。参阅这篇详细指南，了解如何构建筛选器。

​
创建你的 webhook

在 X API 中注册一个可公开访问的 HTTPS URL 来创建 webhook，以接收事件。Webhooks 必须能够处理用于 CRC 验证的 GET 请求，以及用于事件载荷的 POST 请求。请参阅Webhooks 介绍文档，了解创建和管理 webhooks 的详细步骤。 注意： 如果你已经在使用 Account Activity API（AAA） 的 webhooks，这里的设置与其完全相同。事实上，只要带宽允许且你能够区分事件，你可以在此 API 中复用你用于 AAA 的同一 webhook 端点。

​
将你的 Filtered Stream 实例链接到 webhook

在设置好规则并创建 webhook 之后，将该 webhook 链接到你的 Filtered Stream 实例。这会将匹配到的 Post 事件路由至你的 webhook URL。 使用端点：POST /2/tweets/search/webhooks/:webhook_id 你可以包含与流式端点 /2/tweets/search/stream 相同的查询参数，例如 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 连接到同一个流，用于冗余或接收不同的字段集。每个连接都可以指定独立的参数。 将你的 Filtered Stream 实例连接到 webhook 后，你将开始接收符合你规则的 Post，如下所示： 
{
    "data": {
        "id": "1346889436626259968",
        "text": "了解如何使用 X API v2 中的用户 Post 时间线和用户提及时间线端点来探索 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"
        }
    ]
}

​
检索与 Filtered Stream 关联的 Webhook

检索当前与您的 Filtered Stream 关联的全部 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 与 Filtered Stream 的关联

若要停止在特定 webhook 上接收事件，请使用以下方式取消关联： 
DELETE /2/tweets/search/webhooks/:webhook_id
响应如下所示： 
{
    "data": {
        "deleted": true
    }
}