API 呼び出しの仕組み

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

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

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

  1. （推奨）リクエストの本文をプロトコル バッファとして作成し、HTTP/2 を使用してサーバーに送信し、プロトコル バッファへのレスポンスを逆シリアル化して、結果を解釈します。Google のドキュメントのほとんどで、gRPC の使用が説明されています。

  2. （省略可）リクエストの本文を JSON オブジェクトとして作成し、HTTP 1.1 を使用してサーバーに送信し、レスポンスを JSON オブジェクトとしてシリアル化解除して、結果を解釈します。REST の使用について詳しくは、REST インターフェースのガイドをご覧ください。

リソース名

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

複合 ID

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

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

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

リクエスト ヘッダー

以下は、リクエストの本文に付随する HTTP ヘッダー（grpc メタデータ）です。

承認

クライアントに代わってクライアント センター（MCC）アカウントか、アカウントを直接管理している広告主を識別する OAuth2 アクセス トークンを Authorization: Bearer YOUR_ACCESS_TOKEN の形式で含める必要があります。アクセス トークンを取得する手順については、OAuth2 ガイドをご覧ください。アクセス トークンの有効期限は取得後 1 時間です。失効した場合は、アクセス トークンを更新して新たに取得してください。クライアント ライブラリを使用している場合、失効したトークンは自動的に更新されます。

developer-token

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

login-customer-id

これは、リクエストで使用する承認済み顧客のお客様 ID で、ハイフン（-）は省略します。顧客アカウントへのアクセスが MCC アカウントから行われている場合、このヘッダーは必須で、MCC アカウントのお客様 ID に設定する必要があります。

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

login-customer-id を設定すると、Google 広告にログインした後、または右上のプロフィール画像をクリックして、管理画面でアカウントを選択するのと同じ結果になります。このヘッダーを含めない場合、デフォルトでオペレーティング カスタマーになります。

リンクされたお客様 ID

このヘッダーは、第三者のアプリ分析プロバイダが、リンクされた Google 広告アカウントにコンバージョンをアップロードする際にのみ使用します。

アカウント A のユーザーが、ThirdPartyAppAnalyticsLink を介して、そのエンティティへの読み取りおよび編集アクセス権をアカウント B に付与するシナリオを考えます。リンクされると、リンクによって提供される権限に従い、アカウント B のユーザーはアカウント A に対して API 呼び出しを行うことができます。この場合、アカウント A の API 呼び出し権限は、他の API 呼び出しで使用されている MCC アカウントの関係ではなく、アカウント B へのサードパーティ リンクによって決まります。

第三者アプリ分析プロバイダは、次のように API 呼び出しを行います。

  • linked-customer-id: データをアップロードする第三者のアプリ分析アカウント（アカウント B）。
  • customer-id: データのアップロード先の Google 広告アカウント（アカウント A）。
  • login-customer-id ヘッダーと Authorization ヘッダー: アカウント B にアクセスできるユーザーを識別する値の組み合わせ。

レスポンス ヘッダー

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

request-id

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

前へ
リソース メタデータ