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 + 45678 の ~ + AdGroupAdId = 123~45678 の複合広告グループの広告 ID。

リクエスト ヘッダー

リクエスト本文の HTTP ヘッダー（または grpc メタデータ）は次のとおりです。

承認

クライアントに代わって操作するクライアント センター（MCC）アカウント、または独自のアカウントを直接管理する広告主を識別する Authorization: Bearer YOUR_ACCESS_TOKEN の形式で、OAuth2 アクセス トークンを含める必要があります。アクセス トークンを取得する方法については、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/v12/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 は、このリクエストを一意に識別する文字列です。

前へ
リソース メタデータ