メインコンテンツへスキップ
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 は、同じクライアントアプリで併用できます。Advertising API は HTTPS を必須としているため、HTTP でエンドポイントにアクセスするとエラーメッセージが返されます。 Ads API は JSON を出力します。すべての識別子は文字列で、すべての文字列は UTF-8 です。Advertising API はバージョニングされており、バージョンは各リソース URL の先頭のパス要素として指定されます。 https://ads-api.x.com/<version>/accounts

​
HTTP 動詞と一般的なレスポンスコード

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”というidで識別されており、アカウントに関連付けられたキャンペーンを取得する場合は、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 リクエストを用いてアプリケーションの正当性を検証し、さらにアプリケーションが代理で API リクエストを行うエンドユーザーに付与された権限を、ユーザーのアクセス トークンで取得します。Ads API へのすべての HTTP 呼び出しには、HTTPS 上で OAuth 1.0a を使用した Authorization リクエストヘッダーを含める必要があります。 X Ads API と統合するには、アプリケーションで OAuth 1.0a の Authorization リクエストヘッダーを生成できるように実装する必要があります。ただし、署名付きリクエストの生成は複雑なため、X API をサポートしている、または OAuth 1.0a のリクエスト処理を実装している既存のライブラリの利用を強く推奨します。以下に推奨 OAuth ライブラリと認証コードサンプルの一覧があります。 既知のライブラリ使用時に発生する認証 errors については支援可能ですが、独自の OAuth 実装はサポート対象外です。

​
HTTP と OAuth

X REST API v1.1 と同様に、Advertising API では OAuth 1.0A と HTTPS の両方の使用が必要です。API キーは アプリ管理コンソール から取得できます。アクセストークンは「現在のユーザー」を表すためにも使用する必要があります。現在のユーザーとは、広告機能を持つ X アカウントのことです。 パートナーの皆様には、独自実装ではなく OAuth ライブラリの使用を強く推奨します。既知のライブラリをご利用の場合はデバッグを支援できますが、独自の OAuth 実装を行った場合は支援できません。利用可能な ライブラリ を参照してください。 この API は HTTP/1.1 と OAuth に対して厳格です。OAuth 署名ベース文字列を作成する前に、URL と POST 本文内の 予約文字を適切にエンコード していることを確認してください。特に Advertising API では、時間の指定に「:」文字、オプションの集合の指定に「,」文字を使用します。これらはいずれも次の予約集合に含まれます:
記号URL エンコード
!%21
#%23
$%24
&%26
’%27
(%28
)%29
*%2A
+%2B
,%2C
/%2F
:%3A
;%3B
=%3D
?%3F
@%40
[%5B
]%5D

​
Twurl で初めての API リクエストを行う

X は、cURL の代替として OAuth 1.0a 認証ヘッダーに対応したコマンドラインツール Twurl を提供しています。Twurl は、アプリに認証を実装する前に、認証付きの API リクエストを実行し、Ads API を試せる簡便な方法です。 Twurl をインストールして認証を設定 すると、アクセストークンをすばやく生成し、Ads API へ認証付きリクエストを送信できます。 
twurl -H "ads-api.x.com" "/5/accounts/"
API を使ってキャンペーンを作成するためのステップバイステップチュートリアルに沿って進め、Twurl と API に慣れていきましょう。

​
Postman でのテスト

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

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

Twurl を使って 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 ヘッダーを組み立てる