Documentation Index
Fetch the complete documentation index at: https://generaltranslation.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
X Ads API のエンドポイントにアクセスするには、アプリケーションから TLS を使用して https://ads-api.x.com に対して認証付きの Web リクエストを安全に送信する必要があります。
以下のセクションでは、認証済み API リクエストの概要、API とやり取りするための Twurl のセットアップ方法、そしてアプリケーションを拡張して OAuth 1.0a をサポートし、Ads アカウントに対してリクエストを送信できるようにする方法について説明します。
X Ads 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
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 実装についてはサポートできない点にご注意ください。
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 つの文字はいずれも次の予約文字セットに含まれます。
| 記号 | URL エンコード |
|---|
| ! | %21 |
| # | %23 |
| $ | %24 |
| & | %26 |
| ’ | %27 |
| ( | %28 |
| ) | %29 |
| * | %2A |
| + | %2B |
| , | %2C |
| / | %2F |
| : | %3A |
| ; | %3B |
| = | %3D |
| ? | %3F |
| @ | %40 |
| [ | %5B |
| ] | %5D |
Twurl を使って最初の API リクエストを送信する
twurl -H "ads-api.x.com" "/5/accounts/"
認証付きリクエストを行うようにアプリケーションを拡張する
- ヘッダー用に、
oauth_ で始まるキー／値のペアを 7 個収集する
- それらのキー／値のペアを使用して OAuth 1.0a HMAC-SHA1 署名を生成する
- 上記の値を使用して Authorization ヘッダーを構築する
