コンプライアンス Firehose API

ご注意

X API v2 向けの新しいコンプライアンスツールである batch compliance をリリースしました。この新ツールでは、Post またはユーザーの id を含む大規模なデータセットをアップロードし、それらのコンプライアンスステータスを取得して、データセットを準拠させるために対応が必要なデータを判断できます。

さらに、batch compliance と compliance firehose の両方が Post の編集をサポートするように更新されました。compliance firehose には新しい「tweet_edit」イベントが追加されています。詳細は Compliance Data Objects のドキュメントをご参照ください。Edit Posts fundamentals ページで Edit Post の metadata の仕組みについて詳しく学べます。

​

概要

Enterprise

X の中核的価値の一つは、ユーザーの声を守り、尊重することです。これには、ユーザーが X 上で共有するコンテンツを削除・変更・編集する際の期待や意図を尊重することが含まれます。これは、世界最大級の公開リアルタイム情報プラットフォームの長期的な健全性にとって極めて重要であると私たちは考えています。X はコントロールをユーザーに委ね、個々人が自らの X 体験を管理できるようにしています。X のデータを受領するビジネス利用者には、エンドユーザーの期待と意図を尊重する責任があると考えています。

X プラットフォームで発生し得るコンプライアンスイベントの種類についての詳細は、記事 Honoring User Intent on X を参照してください。

API を介して X のデータを利用する開発者または企業は、ユーザーコンテンツへの変更を尊重するために、合理的に可能なあらゆる努力を払う義務を負います。この義務は、削除、変更、共有オプションの変更（例：コンテンツが保護対象になる、または提供が制限される）といったユーザーイベントにも及びます。これは、ユーザーが自分の Posts を編集した場合も含みます。この義務が X データの利用にどのように影響するかを理解するために、Developer Policy および/またはご利用の X Data Agreement に記載された具体的な文言を参照してください。

X は、これらのユーザーコンプライアンスイベントに関する情報や、特定の Post または User が公開されているか否かを提供する次のソリューションを用意しています。各ソリューションの概要と一般的な統合パターンを以下に示します。

​

GET statuses/lookup および GET users/lookup

• フォーマット: REST API。参照: GET statuses/lookup および GET users/lookup。

• これらの endpoint は、Post の編集に対して常に最新バージョンを返します。編集機能の導入以降に作成された Post を記述するすべての Post オブジェクトには、Post 編集の metadata が含まれます。これは編集されていない Post に対しても当てはまります。

• すべての Post について、作成から30分を過ぎて行われたリクエストは、その Post の最終状態を表します。

• 呼び出し元が API リクエスト内で指定した特定の Post または User の可用性情報を返します。

• 特定の Post / User の現在の可用性状態をアドホックにスポットチェックする用途に利用できます。

• 特定の時点における特定の Post または User の現在の状態を確認する必要があるお客様に最適です。

• これらの API は、たとえば次のような場面でコンテンツの可用性を確認する必要があるお客様に有用な手段を提供します:

  1. Post を表示する場合
  2. 1対1で Post や User とエンゲージする場合
  3. 許可されたファイルダウンロードを通じて X コンテンツを第三者に配信する場合
  4. Post を長期間保存する場合

​

Compliance Firehose（Enterprise のみ）

• 形式: Streaming API。参照: Compliance Firehose。
• X 上のコンプライアンス活動をリアルタイムの stream で配信します。これらの活動には、Post の編集などが含まれます。
• プラットフォームで新たなコンプライアンスイベントが発生した際に、保存済みの data 一式にわたってコンプライアンス状態を維持するために使用できます。
• 長期間に大量の X の data を取得・保存するお客様に最適です。

​

ガイド

​

コンプライアンスに関するベストプラクティス

​

推奨事項とベストプラクティス

• 数値の Post ID と User ID を保存するデータストレージスキーマを設計する: ユーザーのメッセージに対しては、そのユーザーのすべての Posts に対してアクションが必要です。したがって、すべてのコンプライアンスメッセージは数値の ID のみで配信されるため、数値 ID に基づいて Post と User の関係を保持できるストレージスキーマを設計することが重要です。データ利用者は、Post ID と User ID の両方でコンプライアンスイベントを監視し、ローカルデータストアを適切に更新できる必要があります。

• すべてのコンプライアンス statuses に対応するスキーマを構築する: 各アプリケーションでコンプライアンス対応をどのように行うかによっては、データストアに他の metadata を追加する必要がある場合があります。たとえば、データ利用者は、status_withheld メッセージの影響を受ける国でコンテンツの表示を制限しやすくするために、既存のデータベースに metadata を追加することを検討する場合があります。

• リツイートの delete の取り扱い: リツイートは特別な種類の Post で、元のメッセージがリツイート内のオブジェクトにネストされています。この場合、リツイートには 2 つの Post ID が参照されます—リツイート自体の ID と、ネストされたオブジェクトに含まれる元のメッセージの ID です。元のメッセージが削除されると、元の ID に対して Post delete メッセージが発行されます。Post の削除イベントは通常、すべてのリツイートに対して delete イベントをトリガーします。ただし、場合によってはすべてが送信されないことがあり、クライアントシステムは不完全なリツイート削除に対して許容できる設計であるべきです。元の ID の削除だけで、後続のすべてのリツイートを削除するには十分です。ベストプラクティスとして、リツイートを保存する際は元の Post ID を参照し、Post の delete イベントを受信したら参照されているリツイートをすべて削除してください。

​

コンプライアンス data オブジェクト

​

Compliance Firehose API

発生しうるコンプライアンスイベントには、Post（または「status」）イベントとユーザーイベントがあり、以下に複数の種類を説明します。  

ご留意ください：

• ユーザーのstatusについての詳細はこちら、削除されたPostsに関する当社の開発者ポリシーはこちらをご覧ください。
• Compliance Firehose は ‘tweet_edit’ イベントを提供するように更新されました。 
• 一部のユーザーの delete、protect、suspend イベントは必ずしも恒久的ではなく、状態が無期限に切り替わる可能性があります。これには user_delete、user_undelete、user_protect、user_unprotect、user_suspend、user_unsuspend が含まれます。
• user_delete の後には、ユーザーがアカウントの user_undelete を選択していない場合に限り、30日後に status_delete が発生します。user_delete がユーザーによって取り消され、そのユーザーのすべてのPostsに対する削除が30日後に行われない可能性があります。
• user_suspend は、ユーザーが user_unsuspend イベントの対象とならない限り有効のままです。これらは30日間の猶予や変更の対象ではありません。

エンドユーザーのプライバシーと意図を尊重するため、各イベントタイプの処理方法は「推奨アクション」欄をご参照ください。

元のメッセージタイプ	オブジェクト	恒久的（はい/いいえ）	推奨アクション
delete	Status	はい	関連するPostを削除します。
status_withheld	Status	はい	status_withheld メッセージに記載された特定の国で、関連するPostを非表示にします。
drop	Status	いいえ	Postを公開表示から外します。
undrop	Status	いいえ	Statusは再び表示でき、公開として扱います。
tweet_edit	Status	はい	新しい編集内容を反映し、該当する場合は表示します。
user_delete	User	いいえ	関連するユーザーのすべてのPostsを非表示または削除します。
user_undelete	User	いいえ	関連するユーザーのすべてのPostsを再び表示でき、公開として扱います。
user_protect	User	いいえ	関連するユーザーのすべてのPostsを非表示または削除します。
user_unprotect	User	いいえ	関連するユーザーのすべてのPostsを再び表示でき、公開として扱います。
user_suspend	User	いいえ	関連するユーザーのすべてのPostsを非表示または削除します。
user_unsuspend	User	いいえ	関連するユーザーのすべてのPostsを再び表示でき、公開として扱います。
scrub_geo	User	はい	scrub_geo メッセージで指定されたPost以前の、そのユーザーのすべてのPostsに対し、Xが提供したジオデータを削除します。なお、その後のユーザーのPostsには利用可能なジオデータが含まれる場合があります。
user_withheld	User	はい	user_withheld メッセージに記載された特定の国で、関連するユーザーのPostsを非表示にします。
delete	Favorite	はい	関連するlike/お気に入りを削除します。

​

ペイロードの例

上の表で説明した各コンプライアンスイベントについて、以下のペイロード例を参照してください。

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）

{
  "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"
  }
}

ユーザーのdelete

{
  "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 は、X プラットフォーム上で発生するコンプライアンス関連のイベントをリアルタイムに配信する stream 型の API です。X におけるコンプライアンスイベントの概要と生成方法については、Honoring User Intent on X を参照してください。

Post および User のイベントはそれぞれ独立して配信され、各々を独立して処理する必要がある点に留意してください（つまり、ある Post の delete が User イベントを意味するわけではなく、その逆も同様です）。いくつかの User イベントは必ずしも恒久的ではなく、状態が無期限に切り替わる可能性があります。これには user_delete、user_undelete、user_protect、user_unprotect、user_suspend、user_unsuspend が含まれます。

user_delete の後、ユーザーがアカウントの user_undelete を選択していない場合に限り、30 日後に status_delete が発生します。ユーザーが user_delete を取り消し、その後 30 日後に当該ユーザーのすべての Posts に対する delete が発生しない可能性もあります。

user_suspend は、ユーザーが user_unsuspend イベントの対象とならない限り有効なまま維持されるアクションです。これらは 30 日間の猶予期間などの変更には該当しません。

コンプライアンスイベントをソフトウェアのユーザーに直接表示したり、製品や顧客体験に組み込んだりすることは適切ではありません。これらはコンプライアンスの維持と、X のユーザーの行為を尊重することのみを目的としています。

​

Compliance Firehose との統合

Compliance Firehose をシステムに統合するには、以下を実行できるインテグレーションを構築する必要があります。

1. Compliance Firehose の各 streaming API パーティションに対して streaming 接続を確立する
2. 大量データに対応する — 非同期処理を用いて、stream の取り込みを後続の処理から分離する
3. いかなる理由で切断された場合でも、stream パーティションへ自動的に再接続する
4. 上記のガイダンスに従い、保持している Post および User データに関連するコンプライアンスイベントを処理する

​

X におけるユーザーの意図を尊重する

私たちは、X のユーザーのプライバシーと意図を尊重することが、世界最大級の公開・リアルタイム情報プラットフォームの長期的な健全性に極めて重要であると考えています。X はプライバシー管理をユーザーに委ね、各個人が自らの X 体験をコントロールできるようにしています。X の data を事業目的で利用する立場として、この信頼と敬意の環境を維持するために、エンドユーザーのプライバシーと行動を尊重する共同責任があります。

プラットフォーム上での表示に影響を及ぼし得る、Posts やユーザーアカウントに関するさまざまな事象があります。プライバシーと意図に影響するアクションは、Status（Post）レベルとユーザーレベルの双方で定義されています。これらのアクションには次のようなものが含まれます。

​

ユーザー

アクション	説明
アカウントを保護	X のユーザーは、いつでも自分のアカウントを保護または解除できます。保護されたアカウントでは、そのアカウントの Posts を閲覧できるユーザーを1人ずつ手動で承認する必要があります。  詳細は、Public と Protected の Posts についてを参照してください。
アカウントを削除	X のユーザーは、いつでも自分のアカウントと関連するすべてのステータスメッセージを削除できます。X は、ユーザーが削除を取り消してアカウントを再有効化できるよう、削除後30日間アカウント情報を保持します。
位置情報のスクラブ	X のユーザーは、いつでも過去の Posts からすべての位置情報データを削除できます。これは「scrub geo」と呼ばれます。
アカウントを凍結	X は、X Rules に違反しているアカウント、またはハッキングや不正アクセスの疑いがあるアカウントを凍結する権利を有します。アカウントの凍結解除（unsuspend）は X のみが行うことができます。
アカウントの提供停止	X は、特定の国において、必要に応じて特定のコンテンツへのアクセスを制限（提供停止）する権利を有します。提供停止されたアカウントの解除は X のみが行うことができます。  詳細は、Country Withheld Contentを参照してください。

​

ステータス

アクション	説明
ステータスの削除	X のユーザーは任意のタイミングでステータスを削除できます。削除されたステータスは元に戻せず、恒久的に削除されます。
ステータスの制限	X は、必要に応じて特定の国において一部コンテンツへのアクセスを制限する権利を有します。制限されたステータスの解除は X のみが行えます。 詳細は、Country Withheld Contentをご覧ください。

​

ユーザーおよびステータスの変更の追跡

ユーザーまたはステータスの状態は、上記のいずれかのアクションによっていつでも変化し得ます。これは、X の data を利用する側が関連コンテンツの可用性やプライバシーをどのように取り扱うべきかに影響します。これらのアクションが発生すると、ステータスまたはユーザーの状態が変更されたことを示す、対応するコンプライアンスメッセージが送信されます。

​

API リファレンス

​

GET compliance/firehose

​

メソッド

メソッド	説明
GET /compliance/:stream	データストリームに接続

​

認証

Compliance Firehose API へのすべてのリクエストは、console.gnip.com のアカウントへのログインに使用する有効なメールアドレスとパスワードの組み合わせで構成された HTTP Basic 認証を使用する必要があります。認証情報は各リクエストの Authorization ヘッダーに渡す必要があります。

​

GET /compliance/:stream

Compliance のファイアホース stream への永続接続を確立し、その stream を通じてコンプライアンスイベントが配信されます。

Request Method	HTTP GET
Connection Type	Keep-Alive
URL	ダッシュボードの stream の API Help ページに記載されており、次の構造に類似します。 https://gnip-stream.x.com/stream/compliance/accounts/:account_name/publishers/twitter/:stream_label.json?partition=1 Note: 「partition」パラメータは必須です。全体ボリュームの各 12.5% を含む 8 つのパーティションすべてに接続して、完全な stream を取得してください。
Compression	Gzip。Gzip 圧縮で stream に接続するには、接続リクエストで Accept-Encoding ヘッダーを送信します。ヘッダーは次のとおりです。 Accept-Encoding: gzip
Character Encoding	UTF-8
Response Format	JSON。リクエストヘッダーでレスポンスの JSON 形式を指定してください。
Rate Limit	60 秒あたり 10 リクエスト。
Read Timeout	クライアントに読み取りタイムアウトを設定し、30 秒を超える値にしてください。
Support for Tweet edits	すべての Tweet の編集は「tweet_edit」コンプライアンスイベントをトリガーします。詳細は Compliance Data Objects を参照してください。

Example Curl Request

次の例のリクエストは、コマンドラインで cURL を使用して実行します。

curl --compressed -v [e-mail] "https://gnip-stream.x.com/stream/compliance/accounts/:account_name/publishers/twitter/:stream_label.json?partition=1"

注: 上記のリクエストは Compliance firehose の partition=1 のみに接続しています。この stream 全体を取得するには、8 つすべてのパーティションに接続する必要があります。

​

レスポンスコード

これらのリクエストに対して、API からは次のレスポンスが返される可能性があります。ほとんどのエラーコードには、本文に詳細を示す文字列が含まれます。200 以外のレスポンスの場合、クライアントは再接続を試みてください。

Status	Text	Definition
200	Success	接続は正常に確立され、新しいアクティビティは到着し次第送信されます。
401	Unauthorized	無効な認証情報により HTTP 認証に失敗しました。認証情報を使用して console.gnip.com にログインし、リクエストで正しく使用できているか確認してください。
406	Not Acceptable	一般的には、クライアントが stream からの gzip エンコーディングを受け入れるためのヘッダーを正しく含めていない場合に発生しますが、他の状況でも発生することがあります。本文には次のような JSON メッセージが含まれます: 「この接続では圧縮が必要です。圧縮を有効にするには、リクエストに ‘Accept-Encoding: gzip’ ヘッダーを送信し、クライアント側で読み取り時に stream を解凍できるようにしてください。」
429	Rate Limited	App が接続リクエストの制限を超過しました。
503	Service Unavailable	X サーバー側の問題です。指数バックオフ方式で再接続してください。この問題に関する告知が X API Status Page に掲載されていない場合は、サポートに連絡してください。

​

その他の推奨事項とベストプラクティス

• 数値のTweet IDおよびUser IDを保存するデータストレージスキーマを構築する: ユーザーに関するメッセージでは、そのユーザーのすべてのTweetに対してアクションを実行する必要があります。したがって、すべてのコンプライアンスメッセージは数値IDでのみ配信されるため、数値IDに基づいてTweetとUserの関係を保持できるようストレージスキーマを設計することが重要です。データ消費者はTweet IDとUser IDの両方でコンプライアンスイベントを監視し、ローカルのデータストアを適切に更新できる必要があります。

• すべてのコンプライアンスstatusesに対応するスキーマを構築する: 各アプリケーションにおけるコンプライアンス対応の方法によっては、データストアに他のmetadataを追加する必要が生じる場合があります。たとえば、データ消費者は、status_withheldメッセージの影響を受ける国におけるコンテンツ表示の制限を容易にするため、既存のデータベースにmetadataを追加することを検討するかもしれません。

• リツイートのdeleteの処理: リツイートは、元のメッセージがリツイート内のオブジェクトにネストされる特殊な種類のTweetです。この場合、リツイートでは2つのTweet IDが参照されます—リツイートのIDと（ネストされたオブジェクトに含まれる）元のメッセージのIDです。元のメッセージが削除されると、元のIDに対してTweetのdeleteメッセージが発行されます。その後、すべてのリツイートに対して個別のdeleteメッセージが発行されることはありません。元のIDの削除だけで、後続のすべてのリツイートの削除として扱われます。