跳转到主要内容
此端点已更新，现包含 Post 编辑元数据。请在“编辑 Posts”基础知识页面了解这些元数据的详细信息。

​
Decahose 流

企业版 这是仅在我们的托管访问层级中提供的企业版 API。要使用此 API，您必须先与我们的企业销售团队开通账户。 了解更多 Decahose 通过流式连接提供 X Firehose 实时流的 10% 随机样本。这是通过实时采样算法实现的：该算法随机选择数据，同时在 X 通过 Firehose 发送数据时，仍可按预期以低延迟交付。 以下是 Decahose 的部分功能：
  • 扩展与增强的 URL： - 完整展开短链接，并提供额外的元数据（页面标题和描述）
  • 流分区 - 2 个分区，每个分区包含 Decahose 流量的 50%
  • 更高的可靠性 - 后端系统具备地域多样性
注意：此数据以批量形式交付，不支持额外的过滤（例如按关键字）。 ENTERPRISE

​
流式传输点赞

这是仅在我们的托管访问级别中提供的企业版 API。要使用此 API，您必须先与我们的企业销售团队开设账户。 了解更多 点赞可用于了解哪些用户为 Post 点赞，并提供准确的点赞计数。Gnip 的 Firehose 和 Decahose 可以传送与通过 Gnip 分发的 Post 相关的公开点赞，从而生成与某条 Post 相关的实时公开互动与受众指标。   开始使用点赞 在准备消费点赞数据时，您应了解：
  • 点赞通过独立的、单独的流进行传送
  • 点赞历史上被称为“Favorites”。增强的原生格式负载保留此命名
  • 流仅包含公开点赞
    • 公开指点赞用户、Post 创建者以及 Post 本身在平台上均为公开
  • 点赞与转发非常相似，代表一种公开的互动信号
  • 负载元素包括：
    • 原始 Post 对象
    • 创建原始 Post 的参与者（Actor）对象
    • 执行点赞操作的参与者（Actor）对象
  • 只能为原始内容点赞
    • 转发不能被点赞。对转发的点赞将应用于原始 Post
    • 引用的 Tweets 可以 被点赞
  • 点赞活动包含适用的 Gnip 增强（如已购买/应用）
  • 支持的产品 / 功能
    • 点赞流支持回填（如已购买/应用）
    • 点赞流不支持回放
    • 点赞不支持搜索或历史
    • 目前暂无将点赞支持添加到 PowerTrack 的计划
Decahose 原生增强格式负载 
{
   "id":"43560406e0ad9f68374445f5f30c33fc",
   "created_at":"Thu Dec 01 22:27:39 +0000 2016",
   "timestamp_ms":1480631259353,
   "favorited_status":{
      "created_at":"Thu Dec 01 22:27:16 +0000 2016",
      "id":804451830033948672,
      "id_str":"804451830033948672",
      "text":"@kafammheppduman",
      "source":"\u003ca href=\"http:\/\/x.com\/download\/android\" rel=\"nofollow\"\u003eX for Android\u003c\/a\u003e",
      "truncated":false,
      "in_reply_to_status_id":803694205163814912,
      "in_reply_to_status_id_str":"803694205163814912",
      "in_reply_to_user_id":2855759795,
      "in_reply_to_user_id_str":"2855759795",
      "in_reply_to_screen_name":"kafammheppduman",
      "user":{
         "id":2855759795,
         "id_str":"2855759795",
         "name":"delirdim kanka",
         "screen_name":"kafammheppduman",
         "location":"sanane",
         "url":"http:\/\/instagram.com\/kafammheppduman",
         "description":"Manit @GalatasaraySk \ud83d\udc9e",
         "translator_type":"none",
         "protected":false,
         "verified":false,
         "followers_count":3702,
         "friends_count":607,
         "listed_count":1,
         "favourites_count":113338,
         "statuses_count":389,
         "created_at":"Sat Nov 01 22:38:25 +0000 2014",
         "utc_offset":null,
         "time_zone":null,
         "geo_enabled":true,
         "lang":"tr",
         "contributors_enabled":false,
         "is_translator":false,
         "profile_background_color":"C0DEED",
         "profile_background_image_url":"",
         "profile_background_image_url_https":"",
         "profile_background_tile":false,
         "profile_link_color":"1DA1F2",
         "profile_sidebar_border_color":"C0DEED",
         "profile_sidebar_fill_color":"DDEEF6",
         "profile_text_color":"333333",
         "profile_use_background_image":true,
       "Profile_image_url": "http:\/\/pbs.twimg.com\/profile_images\/804421763945861121\/v3bp9pnq_normal.jpg",
         "Profile_image_url_https": "https:\/\/pbs.twimg.com\/profile_images\/804421763945861121\/v3bp9pnq_normal.jpg",
         "profile_banner_url":"https:\/\/pbs.twimg.com\/profile_banners\/2855759795\/1480630085",
         "default_profile":true,
         "default_profile_image":false,
         "following":null,
         "follow_request_sent":null,
         "notifications":null
      },
      "geo":null,
      "coordinates":null,
      "place":null,
      "contributors":null,
      "is_quote_status":false,
      "retweet_count":0,
      "favorite_count":0,
      "entities":{
         "hashtags":[],
         "urls":[],
         "user_mentions":[
            {
               "screen_name":"kafammheppduman",
               "name":"delirdim kanka",
               "id":2855759795,
               "id_str":"2855759795",
               "indices":[
                  0,
                  16
               ]
            }
         ],
         "symbols":[]
      },
      "favorited":false,
      "retweeted":false,
      "filter_level":"low",
      "lang":"und"
   },
   "user":{
      "id":774146932365070336,
      "id_str":"774146932365070336",
      "name":"Uyuyan Adam",
      "screen_name":"saykoMenn",
      "location":"Tarsus, T\u00fcrkiye",
      "url":"http:\/\/connected2.me\/pmc1i",
      "description":null,
      "translator_type":"none",
      "protected":false,
      "verified":false,
      "followers_count":414,
      "friends_count":393,
      "listed_count":0,
      "favourites_count":9868,
      "statuses_count":370,
      "created_at":"Fri Sep 09 07:26:26 +0000 2016",
      "utc_offset":null,
      "time_zone":null,
      "geo_enabled":false,
      "lang":"tr",
      "contributors_enabled":false,
      "is_translator":false,
      "profile_background_color":"F5F8FA",
      "profile_background_image_url":"",
      "profile_background_image_url_https":"",
      "profile_background_tile":false,
      "profile_link_color":"1DA1F2",
      "profile_sidebar_border_color":"C0DEED",
      "profile_sidebar_fill_color":"DDEEF6",
      "profile_text_color":"333333",
      "profile_use_background_image":true,
      "Profile_image_url": "http:\/\/pbs.twimg.com\/profile_images\/802992813424201728\/VMzcTL3x_normal.jpg",
      "Profile_image_url_https": "https:\/\/pbs.twimg.com\/profile_images\/802992813424201728\/VMzcTL3x_normal.jpg",
      "profile_banner_url":"https:\/\/pbs.twimg.com\/profile_banners\/774146932365070336\/1480283382",
      "default_profile":true,
      "default_profile_image":false,
      "following":null,
      "follow_request_sent":null,
      "notifications":null
   }
}
点赞删除/“取消点赞”有效负载 
{
   "delete":{
      "favorite":{
         "tweet_id":696615514970279937,
         "tweet_id_str":"696615514970279937",
         "user_id":2510287578,
         "user_id_str":"2510287578"
      },
      "timestamp_ms":"1480437031205"
   }
}

​
使用指南

​
恢复与冗余

简介  在以流式方式传输大量实时 Post 时，有一套最佳实践可同时提升数据可靠性与数据完整性。在消费实时数据时，尽可能延长连接时长是基本目标。一旦发生断连，务必自动检测并立即重连。重连后，需要评估是否存在需要回补数据的时间段。负责处理这些细节并消费实时 Post 的组件只是整个系统的一部分，系统还涉及网络、数据存储、服务器与持久化等方面。鉴于系统的复杂性，另一项最佳实践是划分不同的流式环境，至少应为开发/测试与生产分别提供独立的流。 Decahose 提供了一组功能以支持这些实践。
  1. 为支持多环境，我们可以为你的账户部署附加流。这些流彼此独立，并具有不同的 stream_label 以便区分。
  2. 为帮助保持稳定连接，每个 Decahose 流都支持冗余连接。最常见的架构是一个流配有两个连接，客户端侧有两个相互独立的消费进程——理想情况下位于不同网络。通过这种设计，可在客户端侧的网络、服务器与数据存储链路上实现冗余。请注意，每个连接都会提供完整的数据副本，客户端必须具备容忍并去重的能力。
  3. 系统每 10 秒会发送一次“心跳”；然而，对于 Decahose 流而言，数据量足够大，即便是短时间（例如几秒钟）没有 Post 也可能表明连接异常。因此，“数据静默”以及缺少心跳都可用于检测断连。
鉴于断连不可避免，Decahose 流提供专门的恢复与回补功能，帮助找回因断连或其他运维问题而遗漏的数据。

​
额外流

增加额外的 Decahose 流是提升解决方案可靠性的另一种方式。每条额外流彼此完全独立，并拥有各自唯一的端点。每条流都会分配一个专属的 stream_label，该标签会与您的账户名称一起出现在该流的 URL 中。示例如下： https://gnip-stream.x.com/stream/sample10/accounts/:account_name/publishers/twitter/:stream_label.json 最常见的做法是：为生产系统保留一条专用的实时流，同时再提供一条用于开发和测试的流。拥有测试/开发流使 Decahose 客户能够在不影响生产的情况下验证客户端消费者的更新。虽然可以为流分配任何（唯一）标签，但常见约定是生产流使用“prod”，开发流使用“dev”或“sandbox”。 流的数量及其唯一标签可由您的客户代表进行配置。 冗余连接 冗余连接允许您对同一数据流建立多个并发连接。这样可以通过两个独立的消费者连接到同一条流，并通过两条连接接收相同的数据，从而提供冗余。因此，您的应用在多种情况下可实现热切换，例如某条流断开或应用的主服务器发生故障时。 任一流允许的连接数可由您的客户代表进行配置。要使用冗余连接，只需连接到与主连接相同的 URL。该流的数据将通过两条连接同时发送，且这两条连接都会在流仪表板中显示。 请注意，就计费而言，我们会对您通过多个连接收到的活动计数进行去重，确保每个唯一活动仅计费一次。鉴于 Decahose 有两个分区，以下示例说明连接计数的方式： Connect to decahose partition=1 Connect to decahose partition=1 Connect to decahose partition=2 上述情况合计三条连接——两条连接到 partition=1，一条连接到 partition=2。通常，您应确保每个分区的连接数一致；该示例表明 partition=2 的冗余连接已掉线，需进一步排查。 恢复

​
概述 

Recovery 是一款数据恢复工具（不用于主数据采集），可提供对最近 X 历史数据的滚动 5 天窗口的流式访问。它适用于在以下情况下进行数据补采：当你的消费端应用在实时流中漏数时——无论是因短时断开连接，还是任何其他导致一段时间内未能摄取实时数据的情况。

​
使用 Recovery

通过 Recovery 流，您的应用可以以与实时流相同的方式向其发起请求。不过，您的应用必须在 URL 中指定参数以表明所请求的时间窗口。换言之，Recovery 请求会向 API 要求“从时间 A 到时间 B 的 Post”。这些 Post 将通过您的流式连接传送，方式仿照实时流，但速率会略慢于实时。请参见以下示例： “https://stream-data-api.x.com/stream/powertrack/accounts/someAccountName/publishers/twitter/powertrack.json?startTime=2023-07-05T17:09:12.070Z” Post 的传送将从指定时间段的第一个（最早的）整分钟开始，按时间顺序持续，直到最后一个整分钟传送完成。届时，会通过连接发送一条 Recovery Request Completed 消息，随后服务器将关闭该连接。如果您的请求起始于匹配结果很少或几乎没有的时段，在首条结果传送前可能会有一段等待时间——当 Recovery 在当时正在处理的归档部分遇到匹配项时，才会传送 data。当没有可传送的结果时，流会继续通过连接发送回车（即“心跳”）以防止连接超时。 Recovery 旨在作为一种便捷工具，用于恢复因短暂断连而错过的 data，并非用于非常长的时间段（例如整天）。如果需要在较长时间段内恢复 data，建议将长请求拆分为较短的时间窗口（例如两小时），以降低因网络波动或其他原因导致请求中途断开连接的可能性，并提升对长请求进度的可观测性。

​
数据可用性

如果无法在 5 分钟回填窗口内重新连接，您可以使用 Recovery 功能在过去 24 小时内恢复遗漏的数据。 流式恢复功能允许您将回填窗口扩展至 24 小时。Recovery 使您能够“恢复”遗漏数据对应的时间段。当您使用 ‘start_time’ 和 ‘end_time’ 请求参数发起连接请求时，会启动一次恢复流。连接建立后，Recovery 会重新流式传输所指定的时间段，然后断开连接。   您可以同时发起 2 个并发的恢复请求，即“两个恢复作业”。Recovery 在技术上与回填的工作方式相同，只是需要定义开始时间和结束时间。每次恢复仅对应一个时间范围。

​
回填

要请求回填，你需要在连接请求中添加参数 backfillMinutes=N，其中 N 为建立连接时要回填的分钟数（1-5，仅限整数）。例如，如果你断开了 90 秒，应在连接请求中添加 backfillMinutes=2。由于该请求会提供 2 分钟的回填，其中包含断开前的 30 秒，你的_消费者应用必须能够容忍重复的 data_。 一个 Decahose 连接请求 URL 示例，请求对分区 1 进行 5 分钟回填，如下所示： https://gnip-stream.x.com/stream/sample10/accounts/:account_name/publishers/twitter/:stream_label.json?partition=1&backfillMinutes=5 注意：
  • 你可以在每次连接时始终使用“backfillMinutes=5”，然后在客户端处理可能出现的重复 data。
  • 如果断开超过 5 分钟，你可以使用 Recovery 来恢复 data。
从断开连接中恢复 重新启动并从断开连接中恢复包括以下步骤：
  • 确定断开持续时间。
    • 5 分钟或更短？
      • 如果你的流启用了 Backfill，准备包含合适“backfillMinutes”参数的连接请求。
    • 超过 5 分钟？
      • 如果你有 Recovery 流，请针对断开时段发起 Recovery 请求（理想情况下使用你当前的实时规则集，必要时可使用 Rules API）。
  • 发起新的连接请求。
当你遇到断开或停机时，以下策略可用于缓解并进行恢复：
  1. 实施回填 回填允许你从断开前的时间点重新连接，覆盖最长 5 分钟的断开。通过在连接请求中包含一个参数来实现。
  2. 从其他位置消费冗余流 如果冗余流可以导入同一在线环境并进行去重，你将无需恢复，除非主流和冗余流同时发生停机或断开。如果冗余流无法实时导入生产环境，可将其写入单独的“应急”数据存储。这样，当主流连接发生断开或停机时，你的系统可以用该数据填补主数据库在缺失时段的空白。
  3. 实施 Recovery 当断开或停机同时影响主流和冗余流时，使用 Decahose Recovery 恢复任何遗漏的数据。该 API 提供覆盖 5 天归档的滚动窗口，最佳做法是每次请求不超过 1 小时的窗口并以流式方式导入。这与实时流并行进行。请注意，我们无法提供超出 Recovery 所提供 5 天窗口之外的 Decahose 数据恢复方案，因此，使用冗余流十分重要，以确保在你方出现重大停机时，你方拥有完整的数据副本。
当你检测到异常的已存储数据量时— 在未发生断开或停机的情况下，可能的缺失数据检测方式包括……
  1. 统计入站 Post 数量 你的系统应在摄取应用的最初阶段统计接收到的原始 Post 数量，并提供方式将这些数字与你最终数据存储中到达的 Post 数量进行对比。任何差异都可以被监控，并提醒你的团队关注接收后导致数据丢失的问题。
  2. 分析异常的存储量 你也可以分析最终数据库中的存储数据量，查找异常下降。这同样可能表明存在问题，尽管在某些情况下，量的下降是正常的（例如，当 X 平台不可用，用户在一段时间内无法创建 Post）。

​
API 参考文档

​
Decahose 流

跳转到本页 方法 认证 GET /{stream-type}/:stream 重放 API

​
方法

方法描述
GET /{stream-type}/:stream连接到流式数据

​
认证

对 Volume Stream API 的所有请求都必须使用 HTTP 基础认证（Basic Authentication），由用于登录 console.gnip.com 账户的有效电子邮件地址与密码组合构成。每个请求都必须在 Authorization 头中携带凭据。因此，请确认你的客户端在所有 API 请求中添加了 “Authorization: Basic” HTTP 头（通过 HTTPS 传输的编码凭据）。

​
GET :stream

建立到 Firehose 流的持久连接，通过该连接传输实时 data。

​
请求规范

请求方法HTTP GET
连接类型Keep-Alive

应在请求的请求头中指定。
URL可在你的控制面板中该流的 API Help 页面找到，结构如下：

Decahose：

https://gnip-stream.x.com/stream/sample10/accounts/:account_name/publishers/twitter/:stream_label.json?partition=1
分区（必填）partition=\{#} - 为获取完整流，现在必须使用分区。连接到流时需要指定 partition 参数。以下是每个流的分区数量：

* Decahose：2 个分区
压缩Gzip。若要使用 Gzip 压缩连接到流，只需在连接请求中发送 Accept-Encoding 请求头。该请求头应如下所示：

Accept-Encoding: gzip
字符编码UTF-8
响应格式JSON。你的请求头应指定响应为 JSON 格式。
速率限制每 60 秒最多 10 个请求。
回填参数如果你购买了启用 Backfill 的流，需要在 GET 请求中添加 “backfillMinutes” 参数以启用它。
读取超时在客户端设置读取超时，并确保其值大于 30 秒。
对 Tweet 编辑的支持所有 Tweet 对象都会包含描述该 Tweet 编辑历史的 Tweet 编辑元数据。详情参见 “Edit Tweets” 基础页面。

​
响应

对于这些请求，API 可能返回以下响应。大多数错误代码会在响应体中包含带有更多详细信息的字符串。对于非 200 响应，客户端应尝试重新连接。
StatusTextDescription
200Success连接已成功建立，新的活动将在产生时通过连接推送。
401Unauthorized由于凭据无效导致 HTTP 认证失败。使用你的凭据登录 console.gnip.com，确认你在请求中正确使用了它们。
406Not Acceptable通常发生在客户端未正确包含用于从流中接受 gzip 编码的请求头时，但也可能由其他情况导致。

将包含类似于 “This connection requires compression. To enable compression, send an ‘Accept-Encoding: gzip’ header in your request and be ready to uncompress the stream as it is read on the client end.” 的 JSON 消息。
429Rate Limited你的应用已超出连接请求的配额。
503Service UnavailableX 服务器问题。请使用指数退避策略重新连接。若 X API 状态页 未发布相关通知，且在 10 分钟后仍无法连接，请联系支持或紧急渠道。

​
示例 cURL 请求

以下示例请求通过命令行使用 cURL 完成。请注意，也可以使用你所选择的编程语言发送这些请求： 
curl --compressed -v -uexample@customer.com "https://gnip-stream.x.com/stream/firehose/accounts/:account\_name/publishers/twitter/:stream\_label.json?partition={#}"

​
Replay API

Replay API 是对实时 Volume 流的重要补充。Replay 是一款数据恢复工具，可对 X 近期历史数据的滚动时间窗提供流式访问。