メインコンテンツへスキップ

​
ユーザーアカウントと広告アカウントの違い

Ads API の利用には、広告アカウントと X ユーザーアカウントという 2 種類のアカウントが関与します。Ads API のドキュメント全体では、通常「アカウント」は広告アカウントを指します。
  • 広告アカウントは business.x.com で登録され、API 上では account_id で識別されます。広告アカウントは資金源に直接紐づき、1 つ以上の X ユーザーアカウントのコンテンツを「プロモーション対象ユーザー」として活用します。各広告アカウントは、1 つ以上の X ユーザーアカウントに権限を付与できます。広告アカウント、すなわち「現在のアカウント」は、実行されるほぼすべての URL においてインラインの :account_id パラメータで表されます。
  • X ユーザーアカウント（例: @AdsAPI）は、Ads API では user_id で識別されます。これらのアカウントを 1 つ以上、広告アカウントに関連付けることができます。API にリクエストを送信する認証済みの X ユーザーアカウントは「現在のユーザー」と呼ばれます。現在のユーザーがアクセスできる広告アカウントの一覧は GET accounts で取得できます。「プロモーション対象ユーザー」とは、特定の広告アカウントがプロモーション可能な X のハンドルを指します。詳細は Obtaining Ads Account Access を参照してください。

​
広告アカウントへのアクセス方法

広告主のアカウントに対して Ads API リクエストを行う方法は次の2通りです。
  1. 広告主に代わってリクエストを行う（推奨）
  2. 広告主のアカウントへのアクセス権が付与されている自分のアカウントを使用してリクエストを行う（例：複数アカウントをサポートするAgency）。
本ドキュメントは、これらの方法の違いを簡潔にまとめた概要であり、multi-user login FAQ などの他のリソースと併せて参照してください。 Authorizing a request で説明しているとおり、Ads API へのすべてのリクエストには、OAuth 1.0a による Authorization ヘッダーと、3-leggedOAuth フローで取得したアクセス トークンが必要です。アプリケーションでは、アクセス トークンの取得 のために Web ベースの OAuth フローを実装する必要があります。Ads API 開発者は、X の広告主にログイン認証情報の共有を決して求めないでください。 デフォルトでは、各 X developer application には、アプリケーションの所有アカウントに対して Ads API リクエストを行うために使用できる静的なアクセス トークンが含まれています。これらの認証情報は、3-legged や PIN-based OAuth フローを必要としない単一アカウントのユースケースに最適です。別の X Ads アカウントにアクセスしない場合は、以下の手順ではなく、これらのシングルユーザー認証情報を使用してください。

​
アクセスのレベル

​
アプリレベルの権限

各ユーザーには、Ads API の申請時にリクエストしたアクセスレベルが付与されます。 注: 2023年7月以前にアクセスを申請した Ads API 開発者は、アクセスレベルや権限が異なる場合があり、OAuth トークンが 5 個に制限されている可能性があります。既存のアプリで追加のエンドポイントへのアクセスを有効化する、またはトークン上限を解除するには、アクセス拡張 ガイドをご覧ください。

​
広告アカウントレベルの権限

Ads アカウントにアクセスできる各ユーザーには、特定のアカウントレベルの権限が付与されます：Account administrator、Ad manager、Campaign analyst、Organic analyst、Creative Manager。アカウントレベルの権限に関する最新のドキュメントは business.x.com を参照してください。アプリは、現在認証済みのユーザーの権限を Authenticated User Access API エンドポイントで取得し、そのユーザーが利用可能な API エンドポイントおよび Ads 機能を判定してください。 注: Conversion API を使用するユーザートークンは、Account administrator または Ad manager のアカウントレベル権限を持つユーザーのものである必要があります。                                                                                                                                              

​
アクセストークンの取得方法

​
1. 広告主（ユーザー）のアクセス トークンを取得する

広告主のアクセス トークンを取得する方法は2つあります。最も一般的なのは、ウェブUIから直接実行する3-legged OAuth フローです。広告主向けに公開可能なUIを持たないアプリケーションは、PIN ベースの OAuth プロセスを実装できます。ユーザーが 3-legged フローを完了すると、アプリケーションは API 経由でそのユーザーの Ads アカウントにリクエストを行うための認証情報を取得します。 OAuth フローでユーザーの認証情報を取得する方法は、広告主アカウントへのアクセスが必要な大多数の Ads API 開発者に対して強く推奨します。これにより、ユーザーに代わって API を呼び出し、そのユーザーとして操作を実行できます。これらのトークンに有効期限はありませんが、ユーザーがいつでも取り消すことができます。

​
2. （Developer）アクセス トークンを取得する

この方法では、広告主が business.x.com の X UI からあなたの @username（または複数の @username）に、自身の X Ads アカウントへのアクセス権を付与する必要があります。あなたのアカウントに対して 3-legged OAuth フローで取得したアクセス トークンは、広告主の X Ads アカウントにアクセスできます。 これにより、広告主の OAuth トークンではなく、あなた自身の @username の OAuth トークンを使って API を呼び出せます。この選択肢での重要なポイントは、Post の委任／コンポーザー権限があなたの @username に付与されている場合にのみ、Promoted-Only Posts を作成できることです。 アカウントの FULL プロモート可能ユーザーの代理で Promoted-Only Posts を作成できるようにするには、このフローで Post を作成する権限も付与されている必要があります。これにより、GET accounts/:account_id/authenticated_user_access エンドポイントでの TWEET_COMPOSER 権限を通じてアクセスできるようになります。

​
これらの方法の違い

広告主（ユーザー）OAuthトークン（開発者）OAuthトークン
 （別アカウントに @username を追加）
広告アカウントへのアクセス✔✔
ユーザーに代わってPostを作成✔✔*
キャンペーンの管理✔✔
アナリティクスへのアクセス✔✔
ユーザーに代わってカードを作成✔✔
開発者による
X Ads UI 経由でのアクセス		✔
Rate Limits広告主ごとに個別広告主アカウントごとに個別
注: 詳細は上記の**（開発者）アクセス トークンの取得**セクションを参照してください。

​
サンプルのユースケース

​
広告主のアクセス トークン（OAuth 3-legged Web フロー）

標準のフローは Web ベースで、3-legged authorization の OAuth フローを使用します。ここに示すスクリーンショットは、https://github.com/xdevplatform/twauth-web でソースを参照できるサンプルの一部です。 アプリケーションのフローの中で、アプリを認可するために X にリダイレクトする必要があります。
image0
リクエストトークンを付与して X にリダイレクトすると、ユーザーにアプリの認可を求める画面が表示されます。
image1
ユーザーがアプリを認可すると、リクエストトークンの生成時に指定したコールバック URL にリダイレクトされます。これを用いてこのユーザーの永続的なアクセス トークンを取得し、ローカルに保存します。
image