ユーザーアカウントと広告アカウント

広告APIの使用に関係するアカウントには広告アカウントとTwitterユーザーアカウントの2種類があります。広告APIドキュメントでは、「アカウント」とは通常広告アカウントを指します。

• 広告アカウントはads.twitter.comで登録され、APIではaccount_idで識別されます。広告アカウントは資金源に直接リンクし、「プロモーション可能ユーザー」として、1つ以上のTwitterユーザーアカウントからのコンテンツを活用します。各広告アカウントでは、1つ以上のTwitterユーザーアカウントに権限を付与できます。広告アカウントまたは「現在のアカウント」はインラインのaccount_idパラメーターとして実行されるほとんどすべてのURLで示されます。
• Twitterユーザーアカウント（@AdsAPIなど）は広告APIでuser_idによって特定されます。広告アカウントにはこれらのアカウントを1つ以上関連付けることができます。APIでリクエストを行う認証済みTwitterユーザーアカウントは、「現在のアカウント」として参照されます。 現在のユーザーがアクセス権を持つ広告アカウントのリストは、GET accountsで取得できます。「プロモーション可能なユーザー」は特定の広告アカウントによってプロモーションできるTwitterのユーザー名です。この詳細については、「広告アカウントアクセスの取得」を参照してください。

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

広告主のアカウント用に広告APIリクエストをするには、以下の2つの方法があります。

1. 広告主の代わりにリクエストする（推奨）
2. 広告主のアカウントへのアクセス権が付与されているアカウント（複数のアカウントをサポートしている代理業者など）を使用してリクエストする

このドキュメントは、これらのオプションの違いを簡単に説明したものです。複数ユーザーのログインに関するよくある質問などの他のリソースと併用してください。 

「リクエストの認証」で説明されるように、広告APIへのすべてのリクエストには、3レッグ認証OAuthフローを通じて取得したアクセストークンでOAuth 1.0aを使用したAuthorizationヘッダーが必要になります。アクセストークンを取得するには、アプリケーションでウェブベースのOAuthフローを実装する必要があります。広告API開発者は決して、Twitter広告主にログイン認証情報を共有するよう要求してはなりません。

各Twitter開発者アプリケーションにはデフォルトで統計アクセストークンが含まれています。これを使用してアプリケーションを所有するアカウントに広告APIリクエストを作成できます。こうした認証情報は、3レッグ認証やPINベースOAuthフローが不要のシングルアカウントのユースケースに最適です。別のTwitter広告アカウントにアクセスしない場合は、次の手順の代わりにシングルユーザー認証情報を使用してください。

アクセスレベル

アプリレベル権限

広告APIへの申請内容に応じて、各ユーザーがそれぞれのレベルのアクセスを持つことになります:

• コンバージョンのみ: ユーザーはモバイルとウェブコンバージョンのエンドポイントへのRead and writeのアクセスが可能です。
• スタンダードアクセス: ユーザーは、アナリティクス、キャンペーンマネージメント、クリエイティブ、カスタムオーディエンス、コンバージョンエンドポイントへのRead and writeのアクセスが可能です。

注: 2023年7月以前にアクセスの申請を出した広告APIの開発者は、別のレベルのアクセスや権限が付与されている可能性があります。その場合、OAuthトークンは5つまでとなります。既存のアプリにエンドポイントを追加する場合やトークン制限を外す場合は、アクセス権の引き上げページをご確認ください。

アカウントレベル権限

広告アカウントにアクセスできる各ユーザーには、特定のアカウントレベル権限（ アカウント管理者、広告マネージャー、キャンペーンアナリスト、オーガニックアナリスト、クリエイティブマネージャー）があります。アカウントレベルの権限についての最新ドキュメントについてはbusiness.twitter.comを参照してください。アプリケーションでは、認証済みユーザーアクセスAPIエンドポイントを通じて現在認証されているユーザーの権限を取得し、アクセスできるAPIエンドポイントと広告機能を確認できます。

注: コンバージョンAPIに利用されるユーザートークンは、アカウント管理者か広告マネージャーのアカウントレベル権限を持つユーザーに利用してください。

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

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

広告主のアクセストークンを取得する方法は2通りあります。最も一般的な方法は、ウェブUI内から直接3レッグ認証OAuthフローを通じて取得する方法です。広告主に表示されるパブリックでアクセス可能なUIのないアプリケーションでは、PINベースのOAuthプロセスを実装できます。ユーザーが3レッグ認証のフローを完了すると、アプリケーションには認証情報ができ、APIを通じて広告アカウントにリクエストを作成できるようになります。

広告主アカウントへのアクセス権を得るには、OAuthフローを通じてアカウントの認証情報を取得することをほとんどの広告API開発者に強くお勧めします。これにより、ユーザーの代わりにAPIを呼び出し、そのユーザーとしてアクションを実行できるようになります。こうしたトークンには有効期限はありませんが、ユーザーによりいつでも取り消すことができます。

2.開発者のアクセストークンを取得する

このオプションでは、広告主がads.twitter.comでTwitter UIを通じてTwitter広告アカウントへの@ユーザー名アクセスを付与する必要があります。3レッグ認証OAuthフローを通じて取得したアカウントへのアクセストークンで、広告主のTwitter広告アカウントにアクセスできるようになります。

これにより、広告主のOAuthトークンではなく独自の@ユーザー名のOAuthトークンを使ってAPIを呼び出すことができます。このオプションの主な特徴は、ツイートの委任/作成者権限が@ユーザー名に付与されている場合、プロモーション専用ツイートのみ作成できることです。

FULLプロモーション可能なユーザーの代わりにプロモーション専用ツイートを作成するためのアクセス権限を取得するには、このフローでツイートを作成するためのアクセス権限も付与されている必要があります。これにより、GET accounts/:account_id/authenticated_user_accessエンドポイントのTWEET_COMPOSER権限を通じてアクセスできるようになります。

これらの方法の違い

* 詳細については上の「開発者のアクセストークンを取得する」セクションを参照してください。

サンプルユースケース

OAuth 3レッグ認証ウェブフローを通じた広告主のアクセストークン

標準フローはウェブベースで、3レッグ認証OAuthフローを使用します。次に示すスクリーンショットはサンプルの一部で、そのソースはhttps://github.com/twitterdev/twauth-webで確認できます。

ある時点で、アプリケーションを認証するためにTwitterにリダイレクトします。リクエストトークンでTwitterにリダイレクトすると、ユーザーはアプリケーションを認証するよう促されますアプリケーションが認証されたら、ユーザーは、リクエストトークンが生成される際に提供されるコールバックURLにリダイレクトされます。これを使用して、このユーザーで永久的なアクセストークンを取得し、ローカルで保存します。