API 呼び出しの仕組み

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

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

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

優先:

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

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

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

  4. 結果を解釈する。

ほとんどのドキュメントでは、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 の形式で含めてください。これはクライアント センター（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/v20/customers/1234567890/campaignBudgets:mutate

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

linked-customer-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 は、このリクエストを一意に識別する文字列です。

前へ
リソース メタデータ