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 メタデータ）をリクエストの本文に加えることができます。

承認

OAuth 2.0 アクセス トークンを Authorization: Bearer YOUR_ACCESS_TOKEN の形式で含めてください。これはクライアント センター（MCC）アカウントがクライアントの代理なのか、広告主様がアカウントを直接管理しているのかを識別するために必要となります。アクセス トークンを取得する方法については、OAuth2 ガイドをご覧ください。アクセス トークンの有効期限は取得後 1 時間です。失効した場合は、アクセス トークンを更新して新たに取得してください。クライアント ライブラリを使用している場合、失効したトークンは自動的に更新されます。

認証エラーが発生した場合は、正しい認証情報を使用し、十分な権限があることを確認してください。USER_PERMISSION_DENIED エラーは、認証されたユーザーがリクエストで指定されたお客様アカウントにアクセスできない可能性があることを示します。権限の管理について詳しくは、Google 広告のアクセスレベルをご覧ください。

login-customer-id

これは、リクエストで使用する承認済みクライアントのお客様 ID で、ハイフン（-）なしで使用します。MCC アカウントからクライアント アカウントにアクセスしている場合、このヘッダーは MCC アカウントのお客様 ID に設定する必要があります。MCC アカウントで認証を行うときに login-customer-id を含めないと、AuthorizationError.USER_PERMISSION_DENIED エラーが発生します。このエラータイプについて詳しくは、一般的なエラーをご覧ください。アカウント アクセスが解決される仕組みの詳細については、OAuth アクセスモデルのガイドをご覧ください。

https://googleads.googleapis.com/v25/customers/CUSTOMER_ID/campaignBudgets:mutate

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

linked-customer-id

このヘッダーは必須であり、リンクされた Google 広告アカウントでアクションを実行する際にパートナー（サードパーティ製アプリ分析プロバイダやデータ パートナーなど）によって使用されます。このヘッダーでは、商品リンクがある Google 広告アカウントのお客様 ID を指定する必要があります。

パートナーが商品リンクに基づいて Google 広告アカウントに API 呼び出しを行う必要があるシナリオを考えてみましょう。

  • 広告主: API 呼び出しによって管理または更新される Google 広告アカウント。広告主アカウントの ID はリクエストで指定します。REST では、これは customerId パスパラメータ（customers/1111111111/... など）です。gRPC では、これはリクエストの customer_id フィールドです。
  • パートナー: パートナー アカウント（サードパーティ製アプリ分析プロバイダやデータ パートナーなど）。
  • リンクされたアカウント: パートナーとのサービス間のリンクが確立され、パートナーに広告主へのアクセス権が付与されている Google 広告アカウント。

パートナー アカウントにアクセスできるユーザーが、広告主アカウントのエンティティに対して API 呼び出しを行います（コンバージョンのアップロードやユーザーリストの管理など）。リンクされたアカウントは、広告主アカウント自体、または広告主アカウントのクライアント センター（MCC）アカウントにできます。

リクエスト ヘッダーは次のように設定する必要があります。

  • Authorization: パートナーにアクセスできるユーザーの OAuth 2.0 アクセス トークン。
  • login-customer-id: パートナーの顧客 ID。認証されたユーザーがこのアカウントにアクセスできる必要があります。
  • linked-customer-id: リンクされたアカウントの顧客 ID。このヘッダーは、このリクエストの承認がリンクされたアカウントのパートナーとのプロダクト リンクに依存していることを示します。

リンクには次の 2 つのシナリオがあります。

  • 広告主アカウントがパートナー アカウントと直接商品リンクしている場合、リンクされたアカウントは広告主となり、linked-customer-id は広告主アカウントの顧客 ID に設定する必要があります。
  • 広告主アカウントが、パートナー アカウントとのプロダクト リンクを持つ MCC アカウントによって管理されている場合、リンクされたアカウントは MCC アカウントであり、linked-customer-id は MCC の顧客 ID に設定する必要があります。

例 1: 直接リンク

広告主様アカウント 1111111111 がパートナー アカウント 2222222222 と直接リンクされており、API 呼び出しが customers/1111111111/... をターゲットにしている場合:

Authorization: Bearer YOUR_ACCESS_TOKEN
login-customer-id: 2222222222
linked-customer-id: 1111111111

例 2: マネージャー リンク

広告主アカウント 1111111111 が MCC アカウント 3333333333 によって管理され、MCC アカウント 3333333333 がパートナー アカウント 2222222222 とリンクしており、API 呼び出しが customers/1111111111/... をターゲットとしている場合:

Authorization: Bearer YOUR_ACCESS_TOKEN
login-customer-id: 2222222222
linked-customer-id: 3333333333

レスポンス ヘッダー

以下のヘッダー（grpc trailing-metadata）がレスポンスの本文とともに返されます。デバッグ目的でこれらの値をログに記録することをおすすめします。

request-id

request-id は、このリクエストを一意に識別する文字列です。

前へ
リソース メタデータ