連携ガイド

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

• 役立つツール
• 主要な概念
• 認証
• developer portal、Project、App
• レートリミット
• 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 ユーザーコンテキストでは、API Key、ユーザーの Access Tokens、その他いくつかのパラメータを用いて認可ヘッダーを作成し、それをリクエストに付与する必要があります。Access Tokens は、あなたが代理でリクエストを行う対象ユーザーに関連付けられていなければなりません。別のユーザーのために一式の Access Tokens を生成したい場合は、そのユーザーが3-legged OAuth フローを使用してあなたの App を承認する必要があります。 

OAuth 1.0a は扱いが難しい場合があります。この認証方式に不慣れな場合は、ライブラリを使用する、Postman のようなツールを利用する、または OAuth 2.0 でリクエストを認証することを推奨します。これらの endpoint から Post や非公開の metrics を取得する場合は、OAuth 1.0a ユーザーコンテキストまたは OAuth 2.0 Authorization Code（PKCE 付き）のいずれかを使用する必要があります。これにより、そのコンテンツの所有ユーザーから適切な権限が付与されていることを確保できます。  

App onlyでは、リクエストにApp only Access Tokenを付与するだけで構いません。App only Access Token は、developer App 内から直接生成するか、POST oauth2/token endpoint を使用して生成できます。

OAuth 2.0 Authorization Code（PKCE 付き）は、アプリケーションのスコープや複数デバイス間の認可フローをより細かく制御できます。OAuth 2.0 では、ユーザーに代わって特定の権限を付与する細分化されたスコープを選択できます。 

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

注意

次の fields をリクエストする場合は、OAuth 1.0a ユーザーコンテキストまたは OAuth 2.0 Authorization Code が必要です。 

• tweet.fields.non_public_metrics
• tweet.fields.promoted_metrics
• tweet.fields.organic_metrics

​

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

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

​

レートリミット

毎日、数多くの開発者が X API にリクエストを送信しています。これらの大量のリクエストを管理するため、各 endpoint にはレートリミットが設定されており、App の代理または認証済みユーザーの代理として行えるリクエスト数が制限されています。

ユーザー参照用の endpoint には、App レベルとユーザーレベルの両方のレートリミットが適用されます。一方、認証済みユーザー参照用の endpoint にはユーザーレベルのレートリミットが適用されます。

App レベルのレートリミットは、（使用しているキーおよびトークンで識別される）任意の App から、所定の期間内にこの endpoint へ送信できるリクエスト数が開発者単位で制限されることを意味します。ユーザーレベルのレートリミットは、あなたが代理でリクエストを送信する認証済みユーザーについて、どの開発者用 App を用いる場合でも、所定の回数までしか実行できないことを意味します。

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

Endpoint	HTTP メソッド	レートリミット / レベル
/2/users	GET	15分あたり900リクエスト / App および User
/2/users/:id	GET	15分あたり900リクエスト / App および User
/2/users/by	GET	15分あたり900リクエスト / App および User
/2/users/by/username/:username	GET	15分あたり900リクエスト / App および User
/2/users/me	GET	15分あたり75リクエスト / User

​

fields と expansions

X API v2 では、fields と expansions と呼ばれるツール群を使い、API から返す data を厳密に指定できます。expansions パラメータを使うと、ペイロード内で参照されているオブジェクトを展開できます。たとえば、この endpoint では pinned_tweet_id の expansions を使用できます。

fields パラメータを使うと、受け取りたい各種データオブジェクト内のfieldsを正確に指定できます。これらの endpoints は主にユーザーオブジェクトを返します。デフォルトでは、ユーザーオブジェクトは id、name、username の fields を返します。user.created_at や user.location などの追加の fields を受け取るには、fields パラメータで明示的にリクエストする必要があります。統合での利用を検討すべき重要な fields として、Post の投票データ、metrics、annotations、会話 ID などがあります。

X API v2 data dictionaryに、fields と expansions の使い方のガイドを追加しました。

​

例外ケース

• リツイートでは Post のテキストが省略されます。短期的な回避策として、参照先の Post を展開し、その展開から全文を取得してください。これは不具合であり、今後修正予定です。