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 を作成します。

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

リクエスト ヘッダー

リクエストの本文に付随する HTTP ヘッダー(grpc メタデータ)は次のとおりです。

承認

OAuth2 アクセス トークンを Authorization: Bearer YOUR_ACCESS_TOKEN の形式で含めて、クライアントの代理を務める MCC アカウントか、アカウントを直接管理している広告主かを識別する必要があります。アクセス トークンを取得する方法については、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/v14/customers/1234567890/campaignBudgets:mutate

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

リンクされたお客様 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 は、このリクエストを一意に識別する文字列です。