跳转到主要内容
请注意 我们已为 X API v2 推出名为批量合规的新合规工具。该工具支持你上传包含大量 Post 或用户 id 的数据集，以获取其合规状态，从而确定需要采取哪些操作，使你的数据集达到合规要求。
此外，批量合规和合规 Firehose 均已更新以支持 Post 编辑。对于合规 Firehose，新增了“tweet_edit”事件。有关更多详情，请参阅合规数据对象文档。前往编辑 Post 基础页面了解 Edit Post 元数据的工作方式。

​
概览

Enterprise X 的核心价值之一是捍卫并尊重用户的声音。这包括在用户删除、修改或编辑其在 X 上分享的内容时，尊重其期望和意图。我们认为，这对于作为全球最大公共、实时信息平台之一的长期健康至关重要。X 将控制权交到用户手中，使个人能够掌控自己的 X 使用体验。我们认为，接收 X 数据的商业用户有责任尊重终端用户的期望和意图。 有关 X 平台上可能发生的合规事件类型的更多信息，请参阅我们的文章：在 X 上尊重用户意图。 任何通过 API 使用 X 数据的开发者或公司都有义务尽一切合理努力来遵循用户内容的变更。该义务同样适用于删除、修改以及共享选项的更改（例如，内容变为受保护或被限制）等用户事件。这也包括当用户编辑其 Post 时。请参考开发者政策和/或您的 X 数据协议中的具体措辞，以了解该义务如何影响您对 X 数据的使用。 X 提供以下解决方案，用于提供这些用户合规事件的信息，以及某条特定 Post 或 User 是否对公众可见。以下是这些解决方案及其通用集成模式的简要概述：

​
GET statuses/lookup 和 GET users/lookup

  • 格式：REST API。请参见：GET statuses/lookup 和 GET users/lookup。
  • 这些端点始终返回任意 Post 编辑的最新版本。所有在编辑功能推出后创建的 Post 对象都会包含 Post 编辑元数据，即便该 Post 实际上未被编辑。
  • 对于所有 Post，创建后超过 30 分钟再发起的请求将表示其最终状态。
  • 按调用方在 API 请求中的定义，提供特定 Post 或 User 的可用性信息。
  • 可用于对特定一组 Post/User 的当前可用性状态进行临时抽检。
  • 适用于需要在特定时间点检查某个 Post 或 User 当前状态的客户。
  • 这些 API 为需要检查某段内容可用性的客户提供了实用机制，例如在以下情况下：
    1. 展示 Post
    2. 以 1:1 方式与 Post 或 User 互动
    3. 通过许可的文件下载向第三方分发 X 内容
    4. 长期存储 Post

​
合规 Firehose（仅企业版）

  • 格式：流式 API。参见：Compliance Firehose。
  • 提供 X 上合规活动的实时流。这些活动包括对 Posts 的编辑等。
  • 可用于在平台出现新的合规事件时，维护一组已存储 data 的合规状态。
  • 适合长期获取并存储大量 X data 的客户。

​
使用指南

​
合规性最佳实践

​
建议与最佳实践

  • 构建存储数值型 Post ID 和 User ID 的数据存储 Schemas：用户层面的消息要求对该用户的所有 Posts 采取相应操作。鉴于所有合规消息仅通过数值型 ID 投递，设计能够基于数值型 ID 维护 Post 与 User 关系的存储 schemas 至关重要。数据使用方需要同时按 Post ID 和 User ID 监控合规事件，并能够相应更新本地数据存储。
  • 构建涵盖所有合规状态的 Schemas：根据各类应用处理合规活动的方式，可能需要向数据存储添加其他元数据。例如，数据使用方可能会向现有数据库添加元数据，以便在受到 status_withheld 消息影响的国家/地区限制内容展示。
  • 处理 Retweet 删除：Retweet 是一种特殊的 Post，其中原始消息作为对象嵌套在 Retweet 内部。在这种情况下，Retweet 中会引用两个 Post ID——Retweet 自身的 ID，以及原始消息的 ID（包含在嵌套对象中）。当原始消息被删除时，会针对原始 ID 发出 Post 删除消息。Post 删除事件通常会触发所有相关 Retweet 的删除事件。但在某些情况下可能不会全部发送，客户端系统应能容忍不完整的 Retweet 删除。删除原始 ID 通常足以删除所有后续 Retweet。最佳实践是在存储 Retweet 时引用原始 Post ID，并在收到 Post 删除事件时删除所有被引用的 Retweet。

​
合规性数据对象

​
Compliance Firehose API

可能的合规事件类型包括 Post（或“status”）事件和 User 事件，具体类型如下所述。   请注意：
  • 关于 User 状态请参见此处，关于已删除 Post 的开发者政策请参见此处。
  • Compliance Firehose 现已支持 ‘tweet_edit’ 事件。 
  • 多种 User 的删除、保护和停用事件不一定是永久状态，且可能在不同状态之间无限切换。这些包括：user_delete、user_undelete、user_protect、user_unprotect，以及 user_suspend、user_unsuspend。
  • 仅当用户未选择对其账户执行 user_undelete 时，user_delete 发生后 30 天才会出现相应的 status_delete。用户可能会撤销一次 user_delete，从而在 30 天后不会对其所有 Post 触发删除。
  • user_suspend 在发生后将持续有效，除非随后发生 user_unsuspend 事件。该状态不受 30 天期限内的任何更改影响。
请参阅“Recommended Action”列，了解如何处理各类事件，以尊重终端用户的隐私与意图。
Original Message TypeObjectPermanent (Yes/No)Recommended Action
deleteStatusYes删除关联的 Post。
status_withheldStatusYes在 status_withheld 消息中列明的特定国家/地区屏蔽关联的 Post。
dropStatusNo将该 Post 从公开视图中移除。
undropStatusNo可再次显示该 Status，并视为公开。
tweet_editStatusYes遵从并在适用时显示新的编辑内容。
user_deleteUserNo隐藏或删除关联用户的所有 Post。
user_undeleteUserNo关联用户的所有 Post 可再次显示并视为公开。
user_protectUserNo隐藏或删除关联用户的所有 Post。
user_unprotectUserNo关联用户的所有 Post 可再次显示并视为公开。
user_suspendUserNo隐藏或删除关联用户的所有 Post。
user_unsuspendUserNo关联用户的所有 Post 可再次显示并视为公开。
scrub_geoUserYes删除 X 为该用户在 scrub_geo 消息中指定的 Post 之前提供的所有地理数据。请注意，该用户后续的 Post 可能包含可使用的地理数据。
user_withheldUserYes在 user_withheld 消息中列明的特定国家/地区屏蔽关联用户的 Post。
deleteFavoriteYes删除关联的点赞/收藏。

​
有效载荷示例

请参阅下方针对上表所述各类合规事件的有效载荷示例。 Post 编辑 
{"tweet_edit":
   {
     "id": "1557445923210514432"
     "initial_tweet_id": "1557433858676740098",
     "edit_tweet_ids": ["1557433858676740098", "1557445923210514432"],
     "timestamp_ms": "1660155761384"
   }
 }
删除 Post
{
  "delete": {
    "status": {
      "id": 601430178305220600,
      "id_str": "601430178305220608",
      "user_id": 3198576760,
      "user_id_str": "3198576760"
    },
    "timestamp_ms": "1432228155593"
  }
}
被限制显示的 Post
{
  "status_withheld": {
    "status": {
      "id": 601430178305220600,
      "id_str": "601430178305220608",
      "user_id": 3198576760,
      "user_id_str": "3198576760"
    },
    "withheld_in_countries": [
      "XY"
    ],
    "timestamp_ms": "1432228155593"
  }
}
丢弃
{
  "drop": {
    "status": {
      "id": 601430178305220600,
      "id_str": "601430178305220600",
      "user_id": 3198576760,
      "user_id_str": "3198576760"
    },
    "timestamp_ms": "1432228155593"
  }
}
取消丢弃
{
  "undrop": {
    "status": {
      "id": 601430178305220600,
      "id_str": "601430178305220600",
      "user_id": 3198576760,
      "user_id_str": "3198576760"
    },
    "timestamp_ms": "1432228155593"
  }
}

​
清除地理信息

{
  "scrub_geo": {
    "user_id": 519761961,
    "up_to_status_id": 411552403083628540,
    "up_to_status_id_str": "411552403083628544",
    "user_id_str": "519761961",
    "timestamp_ms": "1432228180345"
  }
}
用户删除
{
  "user_delete": {
    "id": 771136850,
    "timestamp_ms": "1432228153548"
  }
}
恢复用户
{
  "user_undelete": {
    "id": 796250066,
    "timestamp_ms": "1432228149062"
  }
}
用户被隐藏
{
  "user_withheld": {
    "user": {
      "id": 1375036644,
      "id_str": "1375036644"
    },
    "withheld_in_countries": [
      "XY"
    ],
    "timestampMs": "2014-08-27T23:49:41.839+00:00"
  }
}
用户保护
{
  "user_protect": {
    "id": 3182003550,
    "timestamp_ms": "1432228177137"
  }
}
取消取消保护的用户
{
  "user_unprotect": {
    "id": 2911076065,
    "timestamp_ms": "1432228180113"
  }
}
用户暂停
{
  "user_suspend": {
    "id": 3120539094,
    "timestamp_ms": "1432228194217"
  }
}
解除用户停权
{
  "user_unsuspend": {
    "id": 3293130873,
    "timestamp_ms": "1432228193828"
  }
}

​
集成 Compliance Firehose

Compliance Firehose 是一个实时流式 API，用于传送在 X 平台上发生的合规事件。若要了解合规事件及其在 X 上的生成方式，请参考我们的文章：尊重 X 上的用户意图。 需要注意，Post 和 User 事件是独立传送的，且应分别处理（即，删除某条 Post 并不意味着会产生 User 事件，反之亦然）。某些 User 事件不一定是永久性的，可能在不同状态之间无限切换。包括：user_delete、user_undelete、user_protect、user_unprotect，以及 user_suspend、user_unsuspend。 仅当用户未选择对其账户执行 user_undelete 时，user_delete 发生后的第 30 天才会随之产生 status_deletes。用户也可能撤销一次 user_delete，从而在 30 天后不会对其所有 Post 触发删除。 user_suspend 会一直有效，除非发生 user_unsuspend 事件。其不受 30 天期限内任何变更的影响。 绝不应将合规事件直接展示给你软件的用户，或以其他方式将其整合进你的产品或客户体验中。它们仅用于维护合规并尊重 X 用户的操作。

​
集成 Compliance Firehose

要将 Compliance Firehose 集成到你的系统中，你需要构建一套集成以实现以下功能：
  1. 与 Compliance Firehose 的每个流式 API 分区建立流式连接
  2. 处理高数据量——通过异步流程将流式摄取与后续处理解耦
  3. 在因任何原因断开时，自动重新连接到各流分区
  4. 按照上述指南，处理与你已存储的 Post 和 User 数据相关的合规事件

​
尊重在 X 上的用户意图

我们相信，尊重 X 用户的隐私和意图对这一全球最大、公开且实时的信息平台之一的长期健康至关重要。X 将隐私控制权交到用户手中，使个人能够掌控自己的 X 使用体验。作为 X 数据的商业使用者，我们共同有责任尊重终端用户的隐私与行为，从而维护这种信任与尊重的环境。 平台上的 Post 和用户帐户可能发生多种情况，影响其在平台上的展示方式。影响隐私与意图的操作在状态（Post）层级和用户层级均有定义。这些操作包括：

​
用户

操作说明
保护账户X 用户可随时将其账户设为受保护或取消保护。受保护账户需要用户逐一手动批准获准查看其账户 Post 的每位用户。
更多信息，请参见关于公开和受保护的 Post。
删除账户X 用户可随时选择删除其账户及所有关联的状态消息。X 会在删除后保留账户信息 30 天，以便用户决定撤销删除并重新激活其账户。
清除地理信息X 用户可随时从以往的 Post 中移除所有位置信息，这称为“scrub geo（清除地理信息）”。
暂停账户X 保留暂停违反 X 规则的账户，或在怀疑账户遭入侵或被攻破时暂停账户的权利。账户暂停仅可由 X 撤销（解除暂停）。
限制账户X 保留按需在特定国家/地区限制访问某些内容的权利。被限制的账户只能由 X 解除限制。
更多信息，请参见按国家/地区限制的内容。

​
状态

操作说明
删除状态X 用户可在任何时间删除状态。删除后无法恢复，且会被永久移除。
限制状态X 保留不时在特定国家/地区对某些内容采取被动限制访问措施的权利。被限制的状态仅可由 X 取消限制。 
更多信息，请参见 按国家/地区限制的内容。

​
跟踪用户与状态变更

由于上述操作之一，用户或状态的状态可能随时发生变化，这会影响 X data 消费方应如何处理所有相关内容的可用性和隐私性。发生这些操作时，系统会发送相应的合规消息，指示某个状态或用户的状态已变更。

​
API 参考文档

​
GET compliance/firehose

​
方法

方法说明
GET /compliance/:stream连接到数据流

​
认证

对 Compliance Firehose API 的所有请求都必须使用基于 HTTP 的 Basic 认证（Basic Authentication），其凭据由用于登录 console.gnip.com 账户的有效电子邮件地址和密码组成。每个请求都必须通过 Authorization 头部传递凭据。

​
GET /compliance/:stream

建立到 Compliance firehose 数据流的持久连接，合规事件将通过该连接传递。
Request MethodHTTP GET
Connection TypeKeep-Alive
URL可在你的仪表板中该流的 API Help 页面找到，结构类似如下：


https://gnip-stream.x.com/stream/compliance/accounts/:account_name/publishers/twitter/:stream_label.json?partition=1

**注意：**必须包含 “partition” 参数。要获取完整数据流，你需要连接全部 8 个分区，每个分区包含总量的 12.5%。
CompressionGzip。要使用 Gzip 压缩连接到数据流，只需在连接请求中携带 Accept-Encoding 头。该头应如下所示：

Accept-Encoding: gzip
Character EncodingUTF-8
Response FormatJSON。你的请求头应指定响应采用 JSON 格式。
Rate Limit每 60 秒 10 次请求。
Read Timeout在客户端上设置读超时，并确保其值大于 30 秒。
Support for Tweet edits所有 Tweet 编辑都会触发 “tweet_edit” 合规事件。更多详情请参见Compliance Data Objects 文档。
示例 Curl 请求 以下示例请求使用 cURL 在命令行中完成： 
curl --compressed -v -uexample@customer.com "https://gnip-stream.x.com/stream/compliance/accounts/:account_name/publishers/twitter/:stream_label.json?partition=1"
注意： 上述请求只连接到了 Compliance firehose 的 partition=1，要完整消费该数据流，你需要连接所有 8 个分区。

​
响应代码

API 在这些请求中可能返回以下响应。大多数错误代码会在响应正文中包含带有更多详细信息的字符串。对于非 200 响应，客户端应尝试重新连接。
状态文本定义
200成功连接已成功建立，新的活动会在到达时发送。
401未经授权凭据无效导致 HTTP 认证失败。请使用你的凭据登录 console.gnip.com，确保在请求中正确使用它们。
406不可接受通常发生在你的客户端未正确在请求头中声明可接受来自流的 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 消息。
429频率限制你的应用已超出连接请求的限制。
503服务不可用X 服务器问题。请使用指数退避策略重新连接。若 X API Status Page 未发布有关该问题的公告，请联系支持。

​
其他建议与最佳实践

  • 设计数据存储模式以保存数值型 Tweet ID 和 User ID：合规消息要求对该用户的所有 Tweet 采取相应处理。鉴于所有合规消息仅通过数值型 ID 传递，务必设计能基于数值型 ID 维护 Tweet 与 User 关联关系的存储模式。数据使用方需要同时按 Tweet ID 和 User ID 监控合规事件，并能够相应更新本地数据存储。
  • 构建覆盖所有合规状态的模式：根据各应用中处理合规活动的方式，可能需要在数据存储中添加其他元数据。例如，数据使用方可能会在现有数据库中添加元数据，以便在受 status_withheld 消息影响的国家/地区限制内容展示。
  • 处理 Retweet 删除：Retweet 是一种特殊的 Tweet，原始消息以嵌套对象的形式包含在 Retweet 中。在这种情况下，Retweet 中会引用两个 Tweet ID——一个是 Retweet 的 ID，另一个是原始消息的 ID（包含在嵌套对象中）。当原始消息被删除时，会针对原始 ID 发出 Tweet 删除消息；不会针对所有 Retweet 再次发出后续删除消息。删除原始 ID 即可足以删除所有后续 Retweet。