教程

账号动态 API 入门指南

本教程的目的在于帮助你开始使用 Twitter 基于 Webhook 的账号动态 API。你可以在此观看本教程,也可以继续阅读下文。

账号动态 API 可实时发送与 Twitter 用户的账号动态相关的事件。例如,每当订阅用户创建或删除推文、转推、接收或发送私信、关注新用户或喜欢某条推文时,账号动态 API 都会传送 JSON 事件有效负荷。你可以通过我们的开发者文档(高级和企业)找到由账号动态 API 传送的动态类型的完整列表。

基于 Webhook 的 API

账号动态 API 与 Twitter 的 REST API 和流式 API 有所不同,因为它使用 REST 端点组合进行设置和管理,并使用 Webhook 传送数据。Webhook 通过将事件“推送”(又称 POSTing)到已注册 Web 应用程序的 Webhook URL 来传送数据。当 Twitter 中发生特定事件(又称账号动态)时,这一过程便通过 HTTP 实时调用来实现。

Twitter 更为常见的 API 基于客户端服务器方法,即开发者创建一个客户端应用程序与 Twitter 的服务器建立连接,从而接收某些信息。这可以基于流式模型,即客户端与 Twitter 服务器的连接始终保持打开状态以实时接收数据;这也可以是客户端触发的请求,例如开发者要检索特定推文对象的情况。

对于账号动态 API,此模式会发生反转。客户端应用程序不会向 Twitter 的服务器发出连接请求,而是 Twitter 的服务器向开发者 Web 应用程序用于侦听数据的 Webhook 建立连接。在这种情况下,Twitter 会充当客户端并打开与开发者服务器的连接,每当事件发生时,便将动态发布到该 Webhook。

使用基于 Webhook 的 API 有许多优势:

  • 从计算资源的角度来看,与持续对流式 API 打开的连接相比,Webhook 所需的资源更少。
  • 每个 POST 都会在两端返回 HTTP 200 响应代码以进行确认。
  • 如果未成功传送动态,内置的重试过程会重新执行 POST,从而降低数据丢失的概率。
  • 凭借 Webhook,应用程序无需再定期向 API 发出轮询请求来检查是否有新数据可用。
  • 新数据可用后将会立即自动发送到你的服务器。因此,接收到的数据几乎总是最新的。

入门必备条件

要开始使用账号动态 API,需要以下元素:

  • 必须具有开发者账号才能使用任何 Twitter API。如果还没有账号,可以申请一个
  • 拥有 Twitter 开发者应用,且设置了正确的权限。选择开发者门户的“应用”部分下的“Create an app”按钮即可创建新应用。
    • 请务必在应用页面的“permissions”选项卡上启用“Read, Write and Access direct messages”。请注意,这些权限设置不会影响之前权限设置较低的授权用户。
    • 在“Keys and Access token”选项卡上,记下应用的使用者 API 密钥和 API 机密。这些信息可帮助你生成不记名令牌
    • 此外,还必须生成应用的访问令牌和访问令牌机密。注册 Webhook URL 时将需要用到这些。 
  • 开发者环境,你可以在开发者门户的“Dev environments”部分中进行设置。选择你的应用,然后选择环境名称。在开始使用另外的账号动态 API 端点时,你选择的名称将替换 :env_name 令牌。
  • 受保护的特定 Web 应用程序(具有 URL),用于通过 WebHook 接收数据。一款类似 ngrok 的工具,用于创建本地 Web 地址以测试开发中的 Webhook。

保护 Webhook

为通过 Webhook 接收来自 Twitter 的动态,你需要创建一个可在所选 URL 上接收 HTTP(POST 和 GET)请求的 Web 应用程序并对其进行保护。请务必使用你在开发者环境中为账号动态 API 设置的同一 Twitter 应用凭据保护此 Web 应用程序的安全,并使用这些凭据对其进行编码,以便创建 crc_token。Twitter 会频繁发送 Webhook 质询响应检查(称为 CRC)GET 请求,Web 应用程序必须针对该请求返回使用 Twitter 应用程序凭据(应与获批开发者环境应用的凭据匹配)生成的 crc_token

你可以使用 POST account_activity/all/:env_name/webhooks 端点为账号动态 API 注册一个 Webhook URL。

账号动态 API 的所有设置均通过 API 请求完成。开发者门户网站未内置任何用户界面。但是,为方便测试,TwitterDev GitHub 页面上提供了一个面板工具示例:https://github.com/twitterdev/account-activity-dashboard

账号动态 API 将以包含事件数据的 HTTP POST 请求的形式将账号动态发送到你所选的已注册 Webhook URL。

身份验证

向账号动态 API 进行验证可能比较麻烦,因为 API 的功能不同,身份验证方法也不同。Webook 的大多数设置均通过仅限应用程序身份验证(使用不记名令牌)完成。请查看我们的文档,详细了解如何生成必需的不记名令牌

订阅设置通过每个用户订阅的应用程序用户身份验证完成。如果要接收你自己的 Twitter 账号的事件,则可以使用通过开发者门户网站中的 API ​​密钥和 API 机密密钥生成的访问令牌,这是实现入门和测试 API 的绝佳方式。但是,为了接收与另一个 Twitter 账号相关的事件,该账号所有者必须通过三方 OAuth 流程向你授予权限。在服务器端代码中仍需要实现此流程,因为这样才能接收用户的访问令牌。

事件

用户订阅你的 Webhook URL 后,你将开始接收事件了。那事件到底是什么?在本例中,事件对应于与订阅用户的 Twitter 账号相关的动态。每个事件都以应用可使用的 JSON 有效负载的形式传送。如以下示例所示,当用户收到“私信”时,将传送“创建私信”事件。其中有一个包含私信和其他信息的“文本”字段。

      {
"for_user_id": "1102321381",
"direct_message_events": [
{
"type": "message_create",
"id": "1133674120380657669",
"created_timestamp": "1559123947602",
"message_create": {
"target": {
"recipient_id": "1102321381"
},
"sender_id": "1029741837916012544",
"message_data": {
"text": "Good morning ☀️☕",
"entities": {
"hashtags": [],
"symbols": [],
"user_mentions": [],
"urls": []
}
}
}
}
],
"users": {
"1102321381": {
"id": "1102321381",
"created_timestamp": "1358552743000",
"name": "Aurelia Specker",
"screen_name": "AureliaSpecker",
"location": "London, England",
"description": "partner engineer @TwitterUK 👩‍💻 • instructor @CodeFirstGirls • alumni @UniofOxford 🎓 • outdoor enthusiast 🌄 • bookworm 📚 • from switzerland 🇨🇭",
"protected": false,
"verified": false,
"followers_count": 589,
"friends_count": 745,
"statuses_count": 521,
"profile_image_url": "http://pbs.twimg.com/profile_images/1025560966434443264/vsVPbXiT_normal.jpg",
"profile_image_url_https": "https://pbs.twimg.com/profile_images/1025560966434443264/vsVPbXiT_normal.jpg"
},
"1029741837916012544": {
"id": "1029741837916012544",
"created_timestamp": "1534344560624",
"name": "Aurelia",
"screen_name": "re_testing",
"location": "London, England",
"description": "I like travelling 🐪🌴☀️",
"protected": false,
"verified": false,
"followers_count": 4,
"friends_count": 10,
"statuses_count": 52,
"profile_image_url": "http://pbs.twimg.com/profile_images/1029742489090121728/-83RqB5N_normal.jpg",
"profile_image_url_https": "https://pbs.twimg.com/profile_images/1029742489090121728/-83RqB5N_normal.jpg"
}
}
}
{
"for_user_id": "1102321381",
"direct_message_indicate_typing_events": [
{
"created_timestamp": "1559123947551",
"sender_id": "1029741837916012544",
"target": {
"recipient_id": "1102321381"
}
}
],
"users": {
"1102321381": {
"id": "1102321381",
"created_timestamp": "1358552743000",
"name": "Aurelia Specker",
"screen_name": "AureliaSpecker",
"location": "London, England",
"description": "partner engineer @TwitterUK 👩‍💻 • instructor @CodeFirstGirls • alumni @UniofOxford 🎓 • outdoor enthusiast 🌄 • bookworm 📚 • from switzerland 🇨🇭",
"protected": false,
"verified": false,
"followers_count": 589,
"friends_count": 745,
"statuses_count": 521,
"profile_image_url": "http://pbs.twimg.com/profile_images/1025560966434443264/vsVPbXiT_normal.jpg",
"profile_image_url_https": "https://pbs.twimg.com/profile_images/1025560966434443264/vsVPbXiT_normal.jpg"
},
"1029741837916012544": {
"id": "1029741837916012544",
"created_timestamp": "1534344560624",
"name": "Aurelia",
"screen_name": "re_testing",
"location": "London, England",
"description": "I like travelling 🐪🌴☀️",
"protected": false,
"verified": false,
"followers_count": 4,
"friends_count": 10,
"statuses_count": 52,
"profile_image_url": "http://pbs.twimg.com/profile_images/1029742489090121728/-83RqB5N_normal.jpg",
"profile_image_url_https": "https://pbs.twimg.com/profile_images/1029742489090121728/-83RqB5N_normal.jpg"
}
}
}
    

请注意,你无法选择接收某些类型的事件而不接收其他事件。你将始终收到与订阅用户有关的所有事件。可在我们的文档中查看所有事件类型。

如果你是付费客户,则可以启用重试,这样一来,若未收到动态并且 Webhook 未返回成功响应,Twitter 服务器便会尝试再次发送动态。企业账号动态 API 客户的账号动态重播 API 还支持其他冗余和恢复功能,可用于重新发送前五天请求的动态。
订阅数量越多,容量规划就越为重要,规划容量可确保系统能够接收大量事件。

准备好构建你的解决方案了吗?

申请开发者访问权限即可开始构建