API 呼び出しの仕組み

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

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

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

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

  2. （省略可）リクエストの本文を JSON オブジェクトとして作成し、HTTP 1.1 を使用してサーバーに送信し、レスポンスを JSON オブジェクトとしてシリアル化解除して、結果を解釈します。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/v17/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 は、このリクエストを一意に識別する文字列です。

前へ
リソース メタデータ