連携ガイド

このページでは、システムにListのルックアップendpointを統合する際に把握しておくべき、いくつかのツールと重要な概念について説明します。ページは次のセクションに分かれています。

• 役立つツール
• 重要な概念
• 認証
• developer portal、Projects、Apps
• レートリミット
• fieldsとexpansions
• ページネーション

​

役立つツール

このendpointを統合するうえで重要となるいくつかの概念に入る前に、次の内容に慣れておくことをおすすめします：

​

Postman

Postman は、endpoint のテストに最適なツールです。各 Postman リクエストには、利用可能な項目をすばやく把握できるよう、すべてのパスパラメータとボディパラメータが含まれています。Postman コレクションの詳細は、“Using Postman” ページをご覧ください。 

​

コードサンプル

この endpoint をお好みのプログラミング言語で使い始めたい方のために、出発点として利用できるコードサンプルをいくつかGitHub ページで提供しています。

​

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

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

​

重要な概念

​

認証

すべての X API v2 の endpoint では、リクエストを認証するために、一般にキーおよびトークンと呼ばれる一連の認証情報が必要です。これらの endpoint へのリクエスト認証には、OAuth 1.0a ユーザーコンテキスト、App only、または OAuth 2.0 Authorization Code（PKCE 付き）のいずれかを使用できます。 

OAuth 1.0a User Context では、成功するリクエストを行うために API Key とユーザーの Access Tokens のセットを使用する必要があります。access token は、あなたが代理でリクエストを行うユーザーに紐づいていなければなりません。別のユーザーの Access Tokens を生成したい場合は、そのユーザーが 3-legged OAuth フロー を使用してあなたの App を承認する必要があります。

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

OAuth 2.0 Authorization Code with PKCE は、アプリケーションのスコープや複数デバイスにまたがる認可フローを、より細かく制御できます。OAuth 2.0 では、ユーザーの代理で特定の権限を付与する細粒度のスコープを選択できます。 

App で OAuth 2.0 を有効にするには、developer portal の App 設定セクションにある App の認証設定で有効化してください。

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

​

developer portal、Projects、および開発者用 App

X API v2 の endpoint に対応する認証情報一式を取得するには、まずデベロッパーアカウントに登録し、そのアカウント内にProjectを作成し、さらにその Project 内に開発者用 Appを作成する必要があります。キーおよびトークンは、開発者用 App 内で確認できます。  

​

レートリミット

毎日、何千人もの開発者が X API にリクエストを送っています。これらのリクエストの膨大な量を管理するため、各 endpoint には、あなたの App または認証済みユーザーに代わって行えるリクエスト数を制限するレートリミットが設定されています。

これらの endpoint には App レベルとユーザーレベルの両方のレートリミットがあります。App のレートリミットは、開発者であるあなたが、特定の期間内に任意の App（API Key と API Secret Key、または App only Access Token を使用）からこの endpoint に送信できるリクエスト数が制限されることを意味します。ユーザーのレートリミットは、あなたが代行してリクエストを行う認証済みユーザーが、任意の開発者用 App をまたいで一定回数のみ List のルックアップを実行できることを意味します。

以下の表は、各 endpoint のレートリミットを示しています。

Endpoint	HTTP method	Rate limit
/2/lists/:id	GET	15 分あたり 75 リクエスト
/2/users/:id/owned_lists	GET	15 分あたり 15 リクエスト

Fields と expansions

X API v2 の GET endpoint では、fields と expansions と呼ばれるツール群を使って、API から返す data を正確に指定できます。expansions パラメータを使用すると、ペイロード内で id のみで参照されるオブジェクトを展開できます。たとえば、ID で List をルックアップすると、次のexpansionsを取得できます。

• owner_id

fields パラメータを使用すると、受け取りたい各データオブジェクト内でどのfieldsを返すかを正確に選択できます。これらの endpoint は主に List オブジェクトを返します。既定では、List オブジェクトは id と name fields を返します。list.created_at や list.follower_count のような追加フィールドを受け取るには、list.fields パラメータを使用して明示的にリクエストする必要があります。

X API v2 data dictionaryに、fields と expansionsを組み合わせて使用するためのガイドを追加しました。

以下の表は、この endpoint グループで利用可能な field と expansions を示しています。

Endpoint	Fields	Expansions
/2/lists/:id	list.fields user.fields	owner_id
/2/users/:id/owned_lists	list.fields user.fields	owner_id

​

ページネーション

ユーザーが所有するListを参照すると、大量のdataが返されることがあります。常に一貫して高いパフォーマンスで結果を返すために、ページネーションを使用しています。ページネーションは、1回のレスポンスで返せる件数を超える結果を返すX API v2のendpointに備わった機能です。その場合、dataは複数の「ページ」に分割されて返されます。結果のページネーション方法について詳しくはこちらをご覧ください。