連携ガイド

このページでは、users lookup エンドポイントをシステムに統合する際に把握しておくべき、いくつかのツールと重要な概念について説明します。ページは次のセクションで構成されています。

• 便利なツール
• 重要な概念
• 認証
• 開発者ポータル、プロジェクト、アプリ
• レート制限
• fields と expansions
• エッジケース

​

便利なツール

このエンドポイントの統合に役立つ主要な概念に入る前に、以下に挙げる内容に一通り目を通しておくことをおすすめします。

​

Postman

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 flowを使用してあなたのアプリを認可する必要があります。 

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

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

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

アプリで OAuth 2.0 を有効にするには、開発者ポータルの App 設定セクションにあるアプリの認証設定で有効化してください。

ご留意事項

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

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

​

開発者ポータル、Project、開発者アプリ

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

​

レート制限

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

ユーザー参照エンドポイントには、アプリレベルとユーザーレベルの両方のレート制限が適用されます。ただし、認証済みユーザー参照エンドポイントはユーザーレベルでのみ制限されます。

アプリレベルのレート制限は、（使用しているキーやトークンで識別される）任意のアプリから、一定期間内に当該エンドポイントへ送信できるリクエスト数に上限があることを意味します。ユーザーレベルのレート制限は、あなたが代行してリクエストを行う認証済みユーザーが、開発者のアプリをまたいで一定回数までしか操作できないことを意味します。

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

Endpoint	HTTP method	Rate limit / Level
/2/users	GET	15分あたり900リクエスト / アプリおよびユーザー
/2/users/:id	GET	15分あたり900リクエスト / アプリおよびユーザー
/2/users/by	GET	15分あたり900リクエスト / アプリおよびユーザー
/2/users/by/username/:username	GET	15分あたり900リクエスト / アプリおよびユーザー
/2/users/me	GET	15分あたり75リクエスト / ユーザー

​

fields と expansions

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

fields パラメータを使うと、受け取りたい各種 data オブジェクト内の正確なfieldsを選択できます。これらのエンドポイントは主にユーザーオブジェクトを返します。デフォルトでは、ユーザーオブジェクトは id、name、username の fields を返します。user.created_at や user.location のような追加の fields を受け取るには、fields パラメータで明示的にリクエストする必要があります。統合時に検討すべき重要な fields としては、Post の投票データ、メトリクス、アノテーション、conversation ID などがあります。

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

​

エッジケース

• Retweet では Post のテキストが切り捨てられます。短期的な回避策としては、参照されている Post をエクスパンションで展開し、その展開から全文を取得してください。これは不具合であり、今後修正します。