認証されたリクエストの実行

Twitter広告APIエンドポイントにアクセスするには、TLSを使用し、認証されたWebリクエストをアプリケーションからhttps://ads-api.x.comに安全に送信する必要があります。

次のセクションでは、認証されたAPIリクエストの実行、APIとやり取りするためのTwurlの設定、OAuth 1.0aをサポートして広告アカウントにリクエストを実行するためのアプリケーションの拡張について説明します。

要件

Twitter広告APIに認証されたリクエストを行うには、事前に次のものを用意する必要があります。

承認された開発者アカウント
広告APIへのアクセスが承認されたアプリケーション
アプリ管理UIを通じて取得したAPIキーとシークレット
Twitter広告アカウントへのアクセス権を持つユーザーのアクセストークン

APIの使用

広告APIにはhttps://ads-api.x.comでアクセスします。標準のREST APIと広告APIは、同じクライアントアプリで一緒に使用できます。広告APIではHTTPSを強制するため、HTTPでエンドポイントへのアクセスを試みると、エラーメッセージが表示されます。

広告APIはJSONを出力します。すべての識別子は文字列で、すべての文字列はUTF-8になります。広告APIはバージョン化されており、バージョンはリソースURLの最初のパスエレメントとして指定されます。

https://ads-api.x.com/<version>/accounts

HTTP動詞と一般的な応答コード

広告APIでは4つのHTTP動詞が使用されます。

GETはデータを取得します
POSTはキャンペーンなどの新しいデータを作成します
PUTは行項目などの既存のデータを更新します
DELETEはデータを削除します。

データは完全に削除されますが、削除されたデータはGETベースのほとんどのメソッドから確認できます。リソースを要求する際に、明示的にwith_deleted=trueパラメーターを含めてください。含めない場合、削除したレコードはHTTP 404を返します。

正常なリクエストは、リソースを作成、削除または更新する際のオブジェクトを示すJSON応答とともに、HTTP 200シリーズの応答を返します。

HTTP PUTでデータを更新する場合、指定したフィールドのみが更新されます。空の文字列でパラメーターを指定すると、任意の値の設定を解除できます。たとえば、次のパラメーターグループは、すでに指定したend_time: &end_time=&paused=falseの設定を解除します。

エラー応答の詳細については、「エラーコードと応答」を参照してください。

インラインパラメーター

ほとんどのリソースURLでは1つ以上のインラインパラメーターを使用できます。また、多くのURLでは、クエリ文字列またはPOSTやPUTリクエストの本文で、明示的に宣言されたパラメーターを使用します。

インラインパラメーターは、各リソースのリソースパスセクションでプリペンドコロン（「:」）と一緒に表示されます。たとえば、作業しているアカウントが"abc1"と識別され、アカウントに関連付けられるキャンペーンを取得している場合、そのリストにはURL https://ads-api.x.com/6/accounts/abc1/campaignsを使用するとアクセスできます。リソースURL（https://ads-api.x.com/6/accounts/:account_id/campaigns）で説明されるインラインaccount_idパラメーターを指定することで、リクエストの範囲はそのアカウントにのみ関連付けられるオブジェクトになります。

アクセストークンの使用

Twitter広告APIは、署名付きHTTPSリクエストを使用してアプリケーションのIDを検証するとともに、アプリケーションがAPIリクエストを代行するエンドユーザーに付与されている権限を取得します。これはユーザーのアクセストークンで表されます。広告APIへのすべてのHTTP呼び出しには、HTTPSプロトコルによる認証リクエストヘッダー（OAuth 1.0aを使用）を含める必要があります。

Twitter広告APIと統合するには、OAuth 1.0a認証リクエストヘッダーを生成するためのサポートをアプリケーションに追加する必要があります。ただし、署名付きリクエストの生成は複雑であるため、Twitter APIをサポートするか、OAuth 1.0aリクエスト処理を実装する既存のライブラリをパートナーで使用することを強くお勧めします。推奨されるOAuthライブラリと認証コードのサンプルのリストをご確認ください。

既知のライブラリを使用する際に認証エラーが発生したパートナーにはサポートが提供されますが、OAuthのカスタム実装はサポートできません。

HTTPとOAuth

Twitter REST API v1.1などの広告APIではOAuth 1.0AとHTTPSの両方が必要になります。APIキーはアプリ管理コンソールを通じて取得できます。また、「現在のユーザー」を示すのにアクセストークンも使用できます。現在のユーザーは広告機能の付いたTwitterアカウントになります。

独自のOAuthは作成せず、OAuthライブラリを使用することを強くお勧めします。既知のライブラリを使用する場合はデバッグをサポートできますが、独自のOAuth実装を使用する場合はサポートできません。使用できるライブラリを確認してください。

APIではHTTP 1.1とOAuthは厳密に扱われます。OAuth署名ベースの文字列を準備する前に、URLとPOSTボディで適切に予約文字をエンコードしていることを確認します。特に広告APIでは、時間を指定する場合は「:」文字、オプションを複数提供する場合は「;」文字を使用します。どちらの文字も次の予約セットにあります。

‘

(

)

;

[

]

%21

%23

%24

%26

%27

%28

%29

%2A

%2B

%2C

%2F

%3A

%3B

%3D

%3F

%40

%5B

%5D

Twurlを使用した最初のAPIリクエストの実行

Twitterは、cURLの代替としてOAuth 1.0a認証ヘッダーをサポートするコマンドラインツールTwurlの維持に協力しています。Twurlは、アプリケーションに認証を追加する前に、認証されたAPIリクエストを実行し、広告APIを探すための簡単な方法を提供します。

Twurlをインストールして認証したら、すぐにアクセストークンを生成して、広告APIに認証されたリクエストを送信できるようになります。

twurl -H "ads-api.x.com" "/5/accounts/"

TwurlとAPIの詳細については、こちらのAPIを使用してキャンペーンを作成するステップバイステップチュートリアルでご確認ください。

Postmanでテストを実施

Twitterでは、コマンドラインツールに関する知識が浅いユーザーのために、Twitter広告APIエンドポイント向けのPostmanコレクションも提供しています。

Postmanは現在業界でよく利用されているAPI開発ツールです。このHTTPクライアントは、複雑なAPIリクエストを簡素化し、生産性を向上する優れたユーザーインターフェイスを備えています。

Postmanをインストールして広告APIのPostmanコレクションの使用を始めるには、セットアップガイドを参照してください。

Postmanで実行

認証済みリクエストを実行するためのアプリケーションの拡張

Twurlを使用して広告APIへのリクエストを実行する方法を理解したら、次はOAuth 1.0a認証ヘッダーを作成するためのサポートをアプリケーションに追加します。

OAuth 1.0a認証ヘッダーには、アプリケーションとユーザーの両方のIDを確認し、リクエストの改ざんを防ぐための情報が含まれます。アプリケーションには、APIリクエストごとに新しいAuthorizationヘッダーを作成する必要があります。多くの言語には、TwitterにAPIリクエストを行うための認証ヘッダーの作成をサポートするオープンソースライブラリが用意されています。

C#、PHP、Ruby、Pythonの使用例については、こちらのコードサンプルを参照してください。

カスタム実装

シナリオによっては、オープンソースライブラリのサポートなしに、OAuth 1.0a認証の実装が必要な場合があります。「リクエストの認証」には、認証ヘッダーの作成サポートを実装するための詳細な手順が記載されています。コミュニティでサポートされているライブラリを使用することを強くお勧めします。

一般的な概要:

ヘッダーの7つのキーと値のペア（oauth_から始まるもの）を収集します
これらのキーと値のペアを使用して、OAuth 1.0a HMAC-SHA1署名を生成します
上の値を使用して認証ヘッダーを作成します

次の手順

認証ヘッダーのサポートを追加したら、認証されたリクエストをTwitter広告APIに正しく送信できるシンプルなアプリケーションを使用できるようになります。

アプリケーションが別のユーザーのTwitter広告アカウントにアクセスするには、3レッグ認証のOAuthフローを介してアクセストークンを取得する必要があります。

アプリケーションが自分のTwitter広告アカウントにのみアクセスする場合は、動画のアップロードおよびツイートのプロモーションのガイドに進み、キャンペーンで使用するクリエイティブをアップロードします。

リソース

開発ツール

Twurl - Twitter APIとやり取りするためのコマンドラインツール
Postman - サードパーティのAPIを手動で調べるための開発ツール

広告APIをサポートするTwitterライブラリ

Python - Twitterサポート済み
Ruby - Twitterサポート済み
Java - Twitter推奨

OAuth 1.0aをサポートするリクエストヘッダー認証ライブラリ