メインコンテンツへスキップ
X Ads API の endpoint にアクセスするには、アプリケーションが 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 で endpoint にアクセスしようとするとエラーメッセージが返されます。 X Ads API は JSON を返します。すべての識別子は文字列で、すべての文字列は UTF-8 です。Advertising API はバージョニングされており、バージョンはあらゆるリソース URL の先頭のパス要素として指定されます。 https://ads-api.x.com/<version>/accounts

​
HTTP メソッドと一般的なレスポンスコード

X Ads API で使用される HTTP メソッドは 4 つあります:
  • GET は data を取得します
  • POST はキャンペーンなどの新規 data を作成します
  • PUT はラインアイテムなど既存の data を更新します
  • DELETE は data を削除します。
削除は不可逆ですが、リソースを取得する際に with_deleted=true パラメータを明示的に指定すれば、GET ベースの多くのメソッドで削除済みの data も表示できます。指定しない場合、削除済みレコードは HTTP 404 を返します。 リソースの作成・削除・更新が成功すると、対象オブジェクトを表す JSON とともに HTTP 200 番台のレスポンスが返されます。 HTTP PUT で data を更新する場合、指定した fields のみが更新されます。任意項目の値を未設定にするには、空文字列でパラメータを指定します。例: 次のパラメータ群は、既に指定されている end_time を未設定にします: &end_time=&paused=false。 エラーレスポンスの詳細は Error Codes & Responses を参照してください。

​
インラインパラメータ

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

​
Access Tokens の使用

X Ads API は、署名付き HTTPS リクエストを用いてアプリケーションの身元を検証し、さらにアプリケーションが代理で API リクエストを行うエンドユーザーに付与された権限を、ユーザーの access token によって表された形で取得します。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 Key は App 管理コンソール から取得できます。Access Token も「現在のユーザー」を表すために使用する必要があります。ここでの「現在のユーザー」とは、広告機能を有する X アカウントを指します。 パートナーの皆様には、独自実装ではなく OAuth ライブラリの利用を強く推奨します。既知のライブラリを使用している場合はデバッグ支援が可能ですが、自前の OAuth 実装についてはサポートできません。利用可能な ライブラリ をご確認ください。 この API は HTTP/1.1 と OAuth の要件に厳格です。OAuth 署名ベース文字列を作成する前に、URL や POST ボディ内で 予約文字のエンコード が適切に行われていることを確認してください。特に Advertising API では、時刻の指定に「:」、オプション集合の指定に「,」を使用します。これらはいずれも次の予約文字に含まれます:
SymbolURL Encoded
!%21
#%23
$%24
&%26
’%27
(%28
)%29
*%2A
+%2B
,%2C
/%2F
:%3A
;%3B
=%3D
?%3F
@%40
[%5B
]%5D

​
Twurl を使って最初の API リクエストを行う

X では、Twurl というコマンドラインツールを提供しており、cURL の代替として OAuth 1.0a の認可ヘッダーをサポートします。Twurl は、アプリケーションに認証を実装する前に、認証付きの API リクエストを行い、X Ads API を試すための簡便な方法を提供します。 Twurl をインストールして認可した後、access token をすばやく生成し、X Ads API への認証付きリクエストを実行できます。 
twurl -H "ads-api.x.com" "/5/accounts/"
このステップバイステップチュートリアルに従って API 経由でキャンペーンを作成しながら、Twurl と API の使い方に慣れていきましょう。

​
Postman でのテスト

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

​
認証リクエストに対応するようアプリケーションを拡張する

Twurl を使って X Ads API へのリクエストに慣れたら、次はアプリケーションで OAuth 1.0a の認証ヘッダーを生成できるように対応しましょう。 OAuth 1.0a の認証ヘッダーには、アプリケーションとユーザー双方の本人性を検証し、リクエストの改ざんを防ぐための情報が含まれます。アプリケーションは API リクエストごとに新しい Authorization ヘッダーを作成する必要があります。多くの言語には、この認証ヘッダーを生成して X に対する API リクエストを行えるようにするオープンソースのライブラリがあります。 C#、PHP、Ruby、Python の例については次を参照してください — コードサンプル。

​
カスタム実装

オープンソースのライブラリに頼らずに OAuth 1.0a 認証を実装する必要がある場合があります。リクエストの認可では、Authorization ヘッダーを作成できるようにする実装手順を詳しく説明しています。コミュニティがサポートするライブラリの利用を強く推奨します。 概要:
  1. ヘッダー用に、先頭が oauth_ のキー/値ペアを7個集める
  2. それらのキー/値ペアを用いて OAuth 1.0a HMAC-SHA1 署名を生成する
  3. 上記の値を用いて Authorization ヘッダーを構成する
⌘I