Skip to main content
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 でアクセスします。standard REST API と Advertising API は、同じクライアントアプリで併用できます。Advertising API は HTTPS を必須とするため、HTTP でエンドポイントにアクセスしようとするとエラーメッセージが返されます。 Ads API は JSON を出力します。すべての識別子は文字列であり、すべての文字列は UTF-8 です。Advertising API はバージョン管理されており、バージョンは任意のリソース URL の最初のパス要素として指定します。 https://ads-api.x.com/<version>/accounts

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

Ads API では 4 つの HTTP verb が使用されます。
  • GET はデータを取得します
  • POST は新しいデータ(キャンペーンなど)を作成します
  • PUT は既存のデータ(line item など)を更新します
  • DELETE はデータを削除します。
削除は恒久的ですが、削除されたデータは、リソースをリクエストする際に明示的に with_deleted=true パラメーターを含めることで、ほとんどの GET ベースのメソッドから引き続き閲覧できます。それ以外の場合、削除されたレコードは HTTP 404 を返します。 成功したリクエストでは、リソースを作成、削除、または更新した際に、そのオブジェクトを表す JSON レスポンスとともに HTTP 200 系のレスポンスが返されます。 HTTP PUT でデータを更新する場合、指定されたフィールドのみが更新されます。任意の値を解除するには、そのパラメーターに空文字列を指定します。たとえば、以下のパラメーター群は、指定済みの 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 パラメーターを指定することで、リクエストのスコープをそのアカウントに関連するオブジェクトのみに絞り込んでいます。

​
アクセストークンの使用

X Ads API は、署名付き HTTPS リクエストを使用してアプリケーションの ID を検証し、さらに、アプリケーションが API リクエストを代行するエンドユーザーに付与された権限(ユーザーのアクセストークンで表現)を取得します。Ads API へのすべての HTTP 呼び出しは、HTTPS プロトコル上で(OAuth 1.0a を使用した)Authorization リクエストヘッダーを含む必要があります。 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 キーはアプリ管理コンソールから取得できます。「current user」を表すためにアクセストークンも使用する必要があります。current user とは、広告機能を持つ X アカウントのことです。 パートナーは独自に実装するのではなく、OAuth ライブラリを使用することを強く推奨します。既知のライブラリの使用時にはデバッグをサポートできますが、独自の OAuth 実装を用いる場合はサポートできません。使用できるライブラリをご覧ください。 API は HTTP 1.1 と OAuth に対して厳密です。OAuth 署名ベース文字列を準備する前に、URL や POST ボディ内の予約文字を適切にエンコードしていることを確認してください。特に Advertising API では、時間指定時に「:」文字を、複数オプションのコレクションを提供する際に「,」文字を使用します。これら両方は、次の予約セットに含まれます。

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

X は、cURL の代替として OAuth 1.0a の Authorization ヘッダーをサポートするコマンドラインツール Twurl の維持を支援しています。Twurl は、認証付き API リクエストを行うシンプルな方法を提供し、アプリケーションに認証を追加する前に Ads API を試すのに役立ちます。 Twurl のインストールと認可を行うと、素早くアクセストークンを生成し、Ads API に対して認証付きリクエストを行えます。
API 経由でキャンペーンを作成するステップバイステップ チュートリアルに沿って、Twurl と 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 リクエストを行うためのこの authorization ヘッダー作成をサポートするオープンソースライブラリがあります。 以下は、C#、PHP、Ruby、Python の例です — コードサンプル。

​
カスタム実装

一部のシナリオでは、オープンソースライブラリのサポートなしで OAuth 1.0a 認証を実装する必要があります。Authorizing a request には、Authorization ヘッダー作成のサポートを実装する詳細な手順が記載されています。コミュニティサポートされたライブラリを使用することを強くおすすめします。 一般的な手順:
  1. ヘッダー用の 7 つのキー/値ペアを収集する — oauth_ で始まるもの
  2. それらのキー/値ペアを用いて OAuth 1.0a HMAC-SHA1 署名を生成する
  3. 上記の値を用いて Authorization ヘッダーを構築する