メインコンテンツへスキップこのページでは、List lookup エンドポイントをシステムに統合する際に把握しておくべきツールと重要な概念をまとめています。内容は次のセクションに分かれています。
このエンドポイントの統合に役立つ主要な概念に入る前に、まず次の内容に慣れておくことをおすすめします。
Postmanは、エンドポイントのテストに最適なツールです。各Postmanリクエストには、利用可能な項目をすばやく把握できるよう、すべてのパスおよびボディパラメータが含まれています。Postmanコレクションの詳細については、“Postmanの使い方”ページをご覧ください。
お好みのプログラミング言語で、このエンドポイントのセットアップに使えるコードをお探しですか？出発点として活用できる各種コードサンプルを、GitHub ページで提供しています。
コミュニティのサードパーティ製ライブラリを活用して、スムーズに始めましょう。適切なバージョンタグを確認すれば、v2 エンドポイントに対応するライブラリを見つけられます。
すべての X API v2 エンドポイントでは、キーやトークンとも呼ばれる一連の認証情報を用いてリクエストを認証する必要があります。これらのエンドポイントへのリクエスト認証には、OAuth 1.0a ユーザーコンテキスト、App only、または OAuth 2.0 認可コード（PKCE 対応）のいずれかを使用できます。
OAuth 1.0a ユーザーコンテキスト では、リクエストを成功させるために API Keys とユーザー Access Tokens のセットを使用する必要があります。Access Tokens は、あなたが代理でリクエストを行うユーザーにひも付いている必要があります。別のユーザーの Access Tokens セットを生成したい場合は、そのユーザーが 3-legged OAuth フロー を使ってあなたのアプリを認可する必要があります。
OAuth 1.0a は扱いが難しい場合があります。この認証方式に不慣れな場合は、ライブラリ を利用するか、Postman のようなツールを使うか、または OAuth 2.0 でリクエストを認証することを推奨します。
OAuth 2.0 認可コード（PKCE 対応） は、アプリケーションのスコープをより細かく制御でき、複数デバイス間での認可フローにも対応します。OAuth 2.0 では、ユーザーに代わって特定の権限を付与する粒度の細かいスコープを選択できます。
アプリで OAuth 2.0 を有効にするには、開発者ポータルの App 設定セクションにあるアプリの認証設定で有効化してください。
App only では、リクエストに App only Access Token を付与するだけで済みます。開発者ポータルのアプリ内で直接 App only トークンを生成するか、POST oauth2/token エンドポイントを使って生成できます。
X API v2 のエンドポイントで使用できる認証情報一式を取得するには、開発者アカウントに登録し、そのアカウント内でプロジェクトを作成し、そのプロジェクト内に開発者アプリを作成する必要があります。キーとトークンは、開発者アプリ内で確認できます。
毎日、何千人もの開発者が X API にリクエストを送信しています。これらの大量のリクエストを管理するため、各エンドポイントにはレート制限が設けられており、あなたのアプリや認証済みユーザーの代理で行えるリクエスト数に上限があります。
これらのエンドポイントには、アプリレベルとユーザーレベルの両方でレート制限が適用されます。アプリのレート制限は、開発者であるあなたが、特定の期間内に任意のアプリ（API Key と API Secret Key、または App only Access Token のいずれかを使用する想定）から当該エンドポイントに送信できるリクエスト数に上限があることを意味します。ユーザーのレート制限は、あなたが代理でリクエストしている認証済みユーザーが、どの開発者アプリからであっても一定回数までしか List のルックアップを実行できないことを意味します。
以下の表は、各エンドポイントのレート制限を示しています。
| | |
|---|
| エンドポイント | HTTP メソッド | レート制限 |
| /2/lists/:id | GET | 15 分あたり 75 リクエスト |
| /2/users/:id/owned_lists | GET | 15 分あたり 15 リクエスト |
fields と expansions と呼ばれるツールを使って、API から返すデータを正確に指定できます。expansions パラメータは、ペイロード内で参照されているオブジェクトを展開します。例えば、ID で List をルックアップすると、次のようなexpansionsを取得できます。
fields パラメータは、受け取りたい各種データオブジェクト内でどのfieldsを返すかを正確に指定します。これらのエンドポイントは主に List オブジェクトを返します。デフォルトでは、List オブジェクトは id と name を返します。list.created_at や list.follower_count などの追加フィールドを受け取るには、list.fields パラメータを使用して明示的にリクエストする必要があります。
X API v2 データ辞書に、fields と expansionsを組み合わせて使用するためのガイドを追加しました。
以下の表は、このエンドポイントグループで利用可能な fields と expansions を示しています。
| | |
|---|
| エンドポイント | Fields | Expansions |
| /2/lists/:id | list.fields
user.fields | owner_id |
| /2/users/:id/owned_lists | list.fields
user.fields | owner_id |
