v1 から v2 へ

Standard v1.1 と X API v2 の比較

これまで Standard v1.1 の GET users/show や GET users/lookup を利用していた場合、本ガイドは Standard v1.1 と X API v2 の users lookup エンドポイントの共通点と相違点を理解するのに役立ちます。

• 類似点
  • OAuth 1.0a ユーザーコンテキスト
  • リクエストごとのユーザー数の上限
• 相違点
  • エンドポイント URL
  • App と Project の要件
  • レスポンスデータの形式
  • リクエストパラメータ

類似点

OAuth 1.0a ユーザーコンテキスト認証方式

標準エンドポイントは OAuth 1.0a User Context をサポートしており、新しい X API v2 の users lookup エンドポイントは OAuth 1.0a User Context と App only の両方をサポートしています。したがって、以前に標準 v1.1 の users lookup エンドポイントのいずれかを使用していた場合、X API v2 のバージョンに移行しても、同じ認証方式を引き続き使用できます。

利用する認証ライブラリ／パッケージによっては、App only 認証が最も手軽な方法で、簡単なリクエストヘッダーの設定だけで利用できます。App only Access Token の生成方法については、この App only ガイド を参照してください。

1 リクエストあたりのユーザー数の制限

標準 v1.1 の GET users/lookup エンドポイントでは、1 リクエストあたり最大 100 ユーザーまで指定できます。これは GET /users および GET /users/by エンドポイントについても同様です。最大 100 ユーザーを指定するには、ids (GET /users) パラメータ、または username (GET /users/by) パラメータをクエリパラメータとして渡し、ユーザー ID／ユーザー名の一覧をカンマ区切りのリストとして含める必要があります。

違い

エンドポイント URL

• 標準 v1.1 エンドポイント:
  • https://api.x.com/1.1/users/show (単一の id または username のルックアップ)
  • https://api.x.com/1.1/users/lookup (複数の id または username のルックアップ)
• X API v2 エンドポイント:
  • https://api.x.com/2/users (複数の id のルックアップ)
  • https://api.x.com/2/users/:id (単一の id のルックアップ)
  • https://api.x.com/2/users/by (複数の username のルックアップ)
  • https://api.x.com/2/users/by/username/:username (単一の username のルックアップ)

App および Project の要件

X API v2 のエンドポイントでは、リクエストを認証する際に、developer App と、それに関連付けられている Project の資格情報を使用する必要があります。すべての X API v1.1 エンドポイントでは、単体の App、または Project に関連付けられた App の資格情報を使用できます。

レスポンスデータ形式

標準 v1.1 と X API v2 のエンドポイントバージョンの最大の違いの 1 つは、ペイロードにどのフィールドを返すかの選択方法です。

標準エンドポイントでは、多くのレスポンスフィールドがデフォルトで返され、そのうえで、どのフィールドやフィールドセットをペイロードに含めるかをパラメータで指定できます。

X API v2 では、デフォルトで返されるのは user id、name、username フィールドのみです。追加のフィールドやオブジェクトを要求するには、fields パラメータと expansions パラメータを使用する必要があります。このエンドポイントから要求した任意の user フィールドは、プライマリの user オブジェクト内に返されます。展開されたポストオブジェクトおよびそのフィールドは、レスポンス内の includes オブジェクトに返されます。その後、user と展開されたポストオブジェクトの両方に含まれる id を照合することで、任意の展開オブジェクトを user オブジェクトに対応付けることができます。

これらの新しいパラメータの詳細については、それぞれのガイド、またはfields と expansions の使用方法 に関するガイドを参照することをおすすめします。

また、標準 v1.1 のフィールドを新しい v2 のフィールドにマッピングする際に役立つ データ形式の移行ガイド も用意しています。このガイドでは、特定のフィールドを返すために v2 リクエストに付与する必要がある、具体的な expansion パラメータと field パラメータも確認できます。

特定のフィールドの要求方法の変更に加えて、X API v2 では、API が返すオブジェクトの新しい JSON 設計も導入しています。これには、Post オブジェクトと user オブジェクトが含まれます。

• JSON ルートレベルでは、標準エンドポイントは Post オブジェクトを statuses 配列で返しますが、X API v2 は data 配列で返します。
• Retweeted および Quoted の「statuses」を参照する代わりに、X API v2 の JSON では Retweeted および Quoted のツイートを参照します。contributors や user.translator_type など、多くのレガシーおよび非推奨フィールドは削除されます。
• Post オブジェクトでの favorites と user オブジェクトでの favourites のように 2 つの表記を使い分ける代わりに、X API v2 では like という用語を使用します。
• X では、値を持たない JSON 値 (たとえば null) はペイロードに書き出さないという規約を採用しています。Post と user の属性は、null 以外の値を持つ場合にのみ含まれます。

さらに、Post オブジェクト に、次のような新しいフィールドセットも導入しました。

• conversation_id フィールド
• context と entities を含む、2 つの新しい annotations フィールド
• 複数の新しい metrics フィールド
• 特定のポストに誰が返信できるかを示す、新しい reply_setting フィールド

リクエストパラメータ

次の標準 v1.1 リクエストパラメータには、X API v2 における同等のものがあります。

Standard	X API v2
user_id	ids
screen_name	username

また、X API v2 ではサポートされていない標準 users lookup リクエストパラメータもあります。

Standard	コメント
include_entities	このパラメータは、ポストのペイロードから entities ノードを削除するために使用されます。これは、追加的な fields および expansions 機能に置き換えられています。

---

コード例

次の例では、標準的な v1.1 エンドポイントと、それに対応する v2 エンドポイントを示します。

単一ユーザーの取得: v1.1 GET users/show → v2 GET /users/by/username/:username

cURL (v1.1)

shellscript

curl --request GET \
  --url 'https://api.x.com/1.1/users/show.json?screen_name=XDevelopers' \
  --header 'Authorization: Bearer $ACCESS_TOKEN'

複数ユーザーの取得: v1.1 GET users/lookup → v2 GET /users/by

cURL (v1.1)

shellscript

curl --request GET \
  --url 'https://api.x.com/1.1/users/lookup.json?screen_name=XDevelopers,X,XAPI' \
  --header 'Authorization: Bearer $ACCESS_TOKEN'