メインコンテンツへスキップ
X Ads API のエンドポイントにアクセスするには、アプリケーションから TLS を使用して https://ads-api.x.com に対して認証付きの Web リクエストを安全に送信する必要があります。 以下のセクションでは、認証済み API リクエストの概要、API とやり取りするための Twurl のセットアップ方法、そしてアプリケーションを拡張して OAuth 1.0a をサポートし、Ads アカウントに対してリクエストを送信できるようにする方法について説明します。

前提条件

X Ads API への認証付きリクエストを行う前に、次のものが必要です。

API の使用

Advertising API には https://ads-api.x.com からアクセスします。標準 REST API と Advertising API は、同じ App (クライアントアプリケーション) で併用できます。Advertising API は HTTPS を必須としているため、HTTP 経由でエンドポイントにアクセスしようとするとエラーメッセージが返されます。 Ads API は JSON を出力します。すべての識別子は文字列で、すべての文字列は UTF-8 でエンコードされています。Advertising API はバージョン管理されており、バージョンはすべてのリソース URL の最初のパス要素として指定されます。 https://ads-api.x.com/<version>/accounts

HTTP メソッドと代表的なレスポンスコード

Ads API では 4 つの HTTP メソッドが使用されます。
  • GET はデータを取得します
  • POST はキャンペーンなどの新しいデータを作成します
  • PUT はラインアイテムのような既存データを更新します
  • DELETE はデータを削除します。
一度削除すると元に戻せませんが、リソースを取得する際に明示的に with_deleted=true パラメータを含めることで、ほとんどの GET ベースのメソッドから削除済みデータを閲覧できます。指定しない場合、削除済みレコードは HTTP 404 を返します。 リソースの作成、削除、更新が成功すると、オブジェクトを表す JSON レスポンスとともに HTTP 200 番台のレスポンスが返されます。 HTTP PUT でデータを更新する場合、指定されたフィールドのみが更新されます。任意指定のパラメータ値を未設定状態に戻したい場合は、そのパラメータに空文字列を指定します。例として、次のパラメータ群は、すでに指定されている end_time を未設定にします: &end_time=&paused=false。 エラーレスポンスの詳細については、エラーコードとレスポンス を参照してください。

インラインパラメーター

ほとんどのリソース URL には 1 つ以上のインラインパラメーターが含まれます。多くの URL は、クエリ文字列で明示的に指定されたパラメーターや、POST または PUT リクエストの場合はボディ内のパラメーターも受け取ります。 インラインパラメーターは、各リソースの Resource Path セクション内で、先頭にコロン (”:”) を付けて表記されます。たとえば、操作対象のアカウントの識別子が "abc1" で、そのアカウントに関連付けられているキャンペーンを取得する場合、そのリストには https://ads-api.x.com/6/accounts/abc1/campaigns という URL でアクセスします。リソース URL (https://ads-api.x.com/6/accounts/:account_id/campaigns) で示されているインラインの account_id パラメーターを指定することで、そのアカウントにのみ関連付けられたオブジェクトにリクエストのスコープを限定できます。

アクセストークンの使用

X Ads API は署名付き HTTPS リクエストを使用してアプリケーションの ID を検証し、アプリケーションが代理で API リクエストを行うエンドユーザーに付与されている権限を取得します。これらの権限はユーザーのアクセストークンによって表されます。Ads API へのすべての HTTP 呼び出しは、HTTPS プロトコル上で Authorization リクエストヘッダー (OAuth 1.0a を使用) を含める必要があります。 X Ads API と統合するには、アプリケーション側で OAuth 1.0a Authorization リクエストヘッダーを生成する機能を実装する必要があります。ただし、署名付きリクエストの生成は複雑であるため、X API をサポートしている、または OAuth 1.0a リクエスト処理を実装している既存のライブラリをパートナーの皆様にご利用いただくことを強く推奨します。こちらに 推奨 OAuth ライブラリ および 認証コードサンプル の一覧があります。 既知のライブラリを使用していて認証エラーが発生したパートナーに対しては支援できますが、カスタム OAuth 実装についてはサポートできない点にご注意ください。

HTTP と OAuth

X REST API v1.1 と同様に、Advertising API では OAuth 1.0A と HTTPS の両方の使用が必須です。API キーは App 管理コンソール から取得できます。アクセストークンも「現在のユーザー」を表すために使用する必要があります。現在のユーザーとは、広告機能を持つ X アカウントのことです。 パートナーには、独自実装を書くのではなく、OAuth ライブラリを使用することを強く推奨します。一般的なライブラリを使用している場合はデバッグを支援できますが、独自の OAuth 実装についてはサポートできません。利用可能な ライブラリ を参照してください。 この API は HTTP/1.1 および OAuth の仕様に厳格です。OAuth signature base string を作成する前に、URL や POST ボディ内で 予約文字を適切にエンコードしている ことを確認してください。特に Advertising API では、時間を指定する際に「:」文字を、オプションの集合を指定する際に「,」文字を使用します。これら 2 つの文字はいずれも次の予約文字セットに含まれます。

Twurl を使って最初の API リクエストを送信する

X は、OAuth 1.0a の Authorization ヘッダーをサポートし、cURL の代替として利用できるコマンドラインツール Twurl を提供・保守しています。Twurl を使うと、アプリケーションに認証機能を組み込む前に、認証付きの API リクエストを簡単に送信し、Ads API を試してみることができます。 Twurl をインストールして認可したあと、アクセストークンをすばやく生成し、Ads API への認証付きリクエストを送信できます。
Twurl と API に慣れるために、API を通じてキャンペーンを作成するためのこのステップバイステップチュートリアルに従ってみてください。

Postman を使ったテスト

コマンドラインツールに慣れていない方のために、X Ads API のエンドポイント向けの Postman コレクションも提供しています。 Postman は、現在業界で最も広く利用されている API 開発ツールの 1 つです。優れたユーザーインターフェースを備えた HTTP クライアントであり、複雑な API リクエストの送信を簡単にし、生産性を高めます。 Postman をインストールして Ads API 用 Postman コレクションの利用を開始するには、セットアップガイド を参照してください。

認証付きリクエストを行うようにアプリケーションを拡張する

Twurl を使って Ads API へのリクエストに慣れてきたら、次はアプリケーションに OAuth 1.0a 認証ヘッダーを作成する機能を追加します。 OAuth 1.0a 認証ヘッダーには、アプリケーションおよびユーザーの両方の ID を検証し、リクエストの改ざんを防ぐための情報が含まれます。アプリケーションは、各 API リクエストごとに新しい Authorization ヘッダーを作成する必要があります。多くの言語で、この認証ヘッダーを作成して X に API リクエストを送るためのオープンソースライブラリが提供されています。 C#、PHP、Ruby、Python を用いた例をいくつか用意しています。コードサンプル を参照してください。

カスタム実装

一部のケースでは、オープンソースライブラリを使用せずに OAuth 1.0a 認証を実装する必要があります。リクエストの認可では、Authorization ヘッダーを作成するための実装手順を詳細に説明しています。X では、コミュニティによってサポートされているライブラリの使用を強く推奨します。 全体的な手順は次のとおりです。
  1. ヘッダー用に、oauth_ で始まるキー／値のペアを 7 個収集する
  2. それらのキー／値のペアを使用して OAuth 1.0a HMAC-SHA1 署名を生成する
  3. 上記の値を使用して Authorization ヘッダーを構築する