このガイドでは、すべての API 呼び出しに共通する構造について説明します。
API とのやり取りにクライアント ライブラリを使用している場合は基となるリクエストの詳細について特に考慮する必要はありませんが、テストやデバッグを行う際にはそのようなリクエストの知識が役立ちます。
Google Ads API は、REST バインディングを利用した gRPC API で、呼び出す方法は次の 2 つがあります。
推奨: リクエストの本文をプロトコル バッファとして作成し、HTTP/2 を使用してサーバーに送信し、レスポンスをプロトコル バッファに逆シリアル化して、結果を解釈します。Google のドキュメントのほとんどで、gRPC の使用が説明されています。
（省略可）リクエストの本文を 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 メタデータ）は次のとおりです。
承認
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/v16/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 は、このリクエストを一意に識別する文字列です。