インテグレーションガイド

​

統合ガイド

このページでは、List メンバー関連のエンドポイントをシステムに統合する際に押さえておくべきツールと重要な概念を紹介します。内容は次のセクションに分かれています。

• 便利なツール
• 重要な概念
• 認証
• 開発者ポータル、プロジェクト、アプリ
• レート制限
• fields と expansions
• ページネーション

​

便利なツール

このエンドポイントの統合に役立つ重要な概念に入る前に、以下に挙げる点に事前に慣れておくことをおすすめします。

​

Postman

Postman は、エンドポイントのテストに役立つ優れたツールです。各 Postman リクエストには、利用可能な内容を素早く把握できるよう、すべてのパスおよびボディパラメータが含まれています。Postman コレクションの詳細は、“Postman の使用” ページをご覧ください。 

​

コードサンプル

お好みのプログラミング言語でこのエンドポイントをセットアップするためのコードをお探しですか？当社の GitHub ページに、出発点として利用できるコードサンプルを複数用意しています。

​

サードパーティ製ライブラリ

コミュニティが提供するサードパーティ製ライブラリを活用して、スムーズに導入を始めましょう。適切なバージョンタグを確認すれば、v2 エンドポイントに対応するライブラリを見つけられます。

​

重要な概念

​

認証

すべての X API v2 エンドポイントでは、キーやトークンとも呼ばれる一連の資格情報を用いてリクエストを認証する必要があります。Lists のlookupエンドポイントに対するリクエストの認証には、OAuth 1.0a ユーザーコンテキスト、OAuth 2.0 認可コード（PKCE 対応）、または App only のいずれかを使用できます。ただし、manage Lists エンドポイントには、OAuth 1.0a ユーザーコンテキストまたは OAuth 2.0 による認証が必須です。

OAuth 1.0a ユーザーコンテキスト では、成功するリクエストを行うために API Keys と user Access Tokens のセットを使用する必要があります。Access Token は、あなたが代理でリクエストを行うユーザーに紐づいていなければなりません。別のユーザーの Access Tokens セットを生成したい場合は、そのユーザーが 3-legged OAuth flow を使用してあなたのアプリを認可する必要があります。

OAuth 1.0a の利用は難しい場合があります。この認証方式に不慣れであれば、library の利用、Postman のようなツールの使用、または OAuth 2.0 もしくは App only を使用してリクエストを認証することをおすすめします。

OAuth 2.0 認可コード（PKCE 対応） は、アプリケーションのスコープに対するより細かな制御や、複数デバイスにまたがる認可フローを可能にします。OAuth 2.0 では、ユーザーに代わって特定の権限を付与する細粒度のスコープを選択できます。

アプリで OAuth 2.0 を有効にするには、開発者ポータルのアプリ設定セクションにあるアプリの認証設定で有効化する必要があります。

App only では、リクエストに App only Access Token を付与するだけで済みます。開発者アプリ内で直接 App only Access Token を生成するか、POST oauth2/token エンドポイントを使用して生成できます。

App only では、リクエストに App only Access Token を付与するだけで済みます。開発者アプリ内で直接 App only Access Token を生成するか、POST oauth2/token エンドポイントを使用して生成できます。

​

開発者ポータル、プロジェクト、開発者アプリ

X API v2 のエンドポイントで動作する認証情報を取得するには、まず開発者アカウントに登録し、そのアカウント内にプロジェクトを作成し、そのプロジェクト内に開発者アプリを作成する必要があります。キーとトークンは開発者アプリで確認できます。  

​

レート制限

毎日、何万人もの開発者が X API にリクエストを送信しています。これらの膨大なリクエストを適切に管理するため、各エンドポイントにはレート制限が設定されており、アプリまたは認証済みユーザーに代わって行えるリクエスト数に上限があります。 

Lookup（GET）エンドポイントにはアプリレベルとユーザーレベルの両方の制限があり、管理系（POST/DELETE）エンドポイントにはユーザーレベルの制限があります。アプリのレート制限は、開発者であるあなたが、特定の期間内に任意のアプリ（API Key と API Secret Key、または App only Access Token のいずれかを使用することを想定）から当該エンドポイントへ送れるリクエスト数に上限があることを意味します。ユーザーのレート制限は、あなたが代わってリクエストを送る認証済みユーザーが、どの開発者アプリを使う場合でも、List のルックアップを実行できる回数に上限があることを意味します。

以下の表は、各エンドポイントのレート制限を示しています。

エンドポイント	HTTP メソッド	レート制限
/2/lists/:id/members	GET	15 分あたり 900 リクエスト
/2/users/:id/list_memberships	GET	15 分あたり 75 リクエスト
/2/lists/:id/members	POST	15 分あたり 300 リクエスト
/2/lists/:id/members/:user_id	DELETE	15 分あたり 300 リクエスト

​

Fields と expansions

X API v2 の GET エンドポイントでは、fields と expansions と呼ばれる機能を使って、API から返したい data を正確に指定できます。expansions パラメータを使用すると、ペイロード内で参照されているオブジェクトを展開できます。たとえば、List のメンバーを取得する場合、次の expansions を引き出せます。

• pinned_tweet_id

fields パラメータを使用すると、受け取りたい各種 data オブジェクト内で、どの fields を返すかを正確に指定できます。List members lookup は主に user オブジェクトを返します。デフォルトでは、user オブジェクトは id、name、username の各フィールドを返します。user.created_at や user.description などの追加フィールドを受け取るには、user.fields パラメータで明示的にリクエストする必要があります。 

fields と expansions の使用方法に関するガイドを追加しました。

以下の表は、各 lookup エンドポイントで利用可能な field と expansions を示しています。

エンドポイント	Fields	Expansions
/2/lists/:id/members	user.fields tweet.fields	pinned_tweet_id
/2/users/:id/list_memberships	list.fields user.fields	owner_id

​

ページネーション

membership/members の検索では、大量の data が返される場合があります。常に一貫性があり高いパフォーマンスの結果を返すため、ページネーションを使用します。ページネーションは、単一のレスポンスで返せる量を超える結果を返す X API v2 のエンドポイントに備わった機能です。その場合、data は一連の「ページ」に分割されて返されます。結果をページングする方法の詳細をご確認ください。