API 呼び出しの仕組み

このガイドでは、すべての API 呼び出しの共通構造について説明します。

API とのやり取りにクライアント ライブラリを使用している場合は、基となるリクエストの詳細について特に考慮する必要はありません。ただし、テストやデバッグを行う際には API 呼び出しの構造に関する知識が役立ちます。

Google Ads API は、REST バインディングを利用した gRPC API です。呼び出す方法は次の 2 つがあります。

推奨:

  1. リクエストの本文をプロトコル バッファとして作成します。

  2. HTTP/2 を使用してサーバーに送信します。

  3. レスポンスをプロトコル バッファにシリアル化解除します。

  4. 結果を解釈する。

Google のドキュメントのほとんどは、gRPC の使用について説明しています。

省略可:

  1. リクエストの本文を JSON オブジェクトとして作成します。

  2. HTTP 1.1 を使用してサーバーに送信します。

  3. レスポンスを JSON オブジェクトとして逆シリアル化します。

  4. 結果を解釈する。

REST の使用方法については、REST インターフェース ガイドをご覧ください。

リソース名

API のほとんどのオブジェクトは、リソース名文字列で識別されます。これらの文字列は、REST インターフェースを使用する際の URL としても機能します。構造については、REST インターフェースのリソース名をご覧ください。

複合 ID

オブジェクトの ID がグローバル レベルで一意でない場合、そのオブジェクトの複合 ID は、親 ID とチルダ（~）を前に付けて作成されます。

たとえば、広告グループ広告 ID はグローバル レベルで一意ではないため、親オブジェクト（広告グループ）ID を先頭に追加して、一意の複合 ID を作成します。

  • 123 の AdGroupId + ~ + 45678 の AdGroupAdId = 123~45678 の複合広告グループ広告 ID。

リクエスト ヘッダー

HTTP ヘッダー（grpc メタデータ）をリクエストの本文に加えることができます。

承認

OAuth2 アクセス トークンを Authorization: Bearer YOUR_ACCESS_TOKEN の形式で含める必要があります。これは、クライアントの代理として機能するマネージャー アカウント、または自身のアカウントを直接管理する広告主のいずれかを識別するものです。アクセス トークンを取得する方法については、OAuth2 ガイドをご覧ください。アクセス トークンの有効期限は取得後 1 時間です。失効した場合は、アクセス トークンを更新して新たに取得してください。クライアント ライブラリを使用している場合、失効したトークンは自動的に更新されます。

認証エラーが発生した場合は、正しい認証情報を使用し、十分な権限があることを確認してください。USER_PERMISSION_DENIED エラーは、認証されたユーザーがリクエストで指定されたお客様アカウントにアクセスできない可能性があることを示します。権限の管理について詳しくは、Google 広告のアクセスレベルをご覧ください。

developer-token

開発者トークンは、Google Ads API 開発者を一意に識別する 22 文字の文字列です。開発者トークン文字列の例は ABcdeFGH93KL-NOPQ_STUv です。開発者トークンは developer-token : ABcdeFGH93KL-NOPQ_STUv の形式で含める必要があります。

login-customer-id

これは、リクエストで使用する承認済みクライアントのお客様 ID で、ハイフン（-）なしで使用します。MCC アカウントからクライアント アカウントにアクセスしている場合、このヘッダーは MCC アカウントのお客様 ID に設定する必要があります。MCC アカウントで認証を行うときに login-customer-id を含めないと、AuthorizationError.USER_PERMISSION_DENIED エラーが発生します。このエラータイプについて詳しくは、一般的なエラーをご覧ください。

https://googleads.googleapis.com/v24/customers/1234567890/campaignBudgets:mutate

ログインした後に Google 広告 UI でアカウントを選択するか、右上にある自分のプロフィール画像をクリックすると、login-customer-id が設定されます。このヘッダーを含めないと、デフォルトのオペレーティング カスタマになります。

linked-customer-id

このヘッダーは必須であり、リンクされた Google 広告アカウントで操作を行う際にパートナー（サードパーティ製アプリ分析プロバイダやデータ パートナーなど）によって使用されます。このヘッダーでは、商品リンクを含む Google 広告アカウントのお客様 ID を指定する必要があります。

パートナーが商品リンクに基づいて Google 広告アカウントに API 呼び出しを行う必要があるシナリオを考えてみましょう。

  • 広告主: API 呼び出しによって管理または更新される Google 広告アカウント。広告主アカウントの ID はリクエストで指定します。REST では、これは customerId パスパラメータ（customers/1111111111/... など）です。gRPC では、これはリクエストの customer_id フィールドです。
  • パートナー: パートナー アカウント（サードパーティ製アプリ分析プロバイダやデータ パートナーなど）。
  • リンクされたアカウント: パートナーとサービス間のリンクが確立され、パートナーに広告主へのアクセス権が付与されている Google 広告アカウント。

パートナーにアクセスできるユーザーが、API 呼び出しを行って広告主のエンティティを操作します（コンバージョンのアップロードやユーザーリストの管理など）。リンクされたアカウントは、広告主自身のアカウント、または広告主のクライアント センター（MCC）アカウントです。

リクエスト ヘッダーは次のように設定する必要があります。

  • Authorization: パートナーにアクセスできるユーザーの OAuth2 トークン。
  • developer-token: API アプリケーションの開発者トークン。通常はパートナーに関連付けられています。
  • login-customer-id: パートナーの顧客 ID。認証されたユーザーがこのアカウントにアクセスできる必要があります。
  • linked-customer-id: リンクされたアカウントの顧客 ID。このヘッダーは、このリクエストの承認がリンクされたアカウントとパートナーのプロダクト リンクに依存していることを示します。

リンクには次の 2 つのシナリオがあります。

  • 広告主がパートナーと直接のプロダクト リンクを持っている場合、リンクされたアカウントは広告主となり、linked-customer-id は広告主の顧客 ID に設定する必要があります。
  • 広告主様がパートナーとのサービスリンクがある MCC アカウントで管理されている場合、リンクされたアカウントは MCC アカウントとなり、linked-customer-id は MCC のお客様 ID に設定する必要があります。

例 1: 直接リンク

広告主 1111111111 がパートナー 2222222222 と直接リンクしており、API 呼び出しが customers/1111111111/... をターゲットにしている場合:

Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_TOKEN
login-customer-id: 2222222222
linked-customer-id: 1111111111

例 2: マネージャー リンク

広告主 1111111111 がクライアント センター 3333333333 によって管理され、クライアント センター 3333333333 がパートナー 2222222222 とリンクしており、API 呼び出しが customers/1111111111/... をターゲットにしている場合:

Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_TOKEN
login-customer-id: 2222222222
linked-customer-id: 3333333333

レスポンス ヘッダー

以下のヘッダー（grpc trailing-metadata）がレスポンスの本文とともに返されます。デバッグ目的でこれらの値をログに記録することをおすすめします。

request-id

request-id は、このリクエストを一意に識別する文字列です。

前へ
リソース メタデータ