API 呼び出しの構造

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

クライアント ライブラリを使用して API を操作する場合は、基盤となるリクエストの詳細を把握する必要はありません。ただし、API 呼び出しの構造に関する知識は、テストやデバッグの際に役立ちます。

Google Ads API は、REST バインディングを備えた gRPC API です。つまり、API を呼び出す方法は 2 つあります。

推奨:

  1. リクエストの本文をプロトコル バッファとして作成します。
  2. HTTP/2 を使用してサーバーに送信します。
  3. レスポンスをプロトコル バッファにデシリアライズします。
  4. 結果を解釈する。

ほとんどのドキュメントでは、gRPC の使用について説明しています。

省略可:

  1. リクエストの本文を JSON オブジェクトとして作成します。
  2. HTTP 1.1 を使用してサーバーに送信します。
  3. レスポンスを JSON オブジェクトとしてデシリアライズします。
  4. 結果を解釈する。

REST の使用方法については、REST インターフェース ガイドをご覧ください。

リソース識別子

Google Ads API のオブジェクトは、構造化されたリソース名と複合識別子を使用してアドレス指定されます。

リソース名

API のほとんどのオブジェクトは、リソース名文字列で識別されます。これらの文字列は、REST インターフェースを使用する際の URL としても機能します。構造については、REST インターフェースのリソース名をご覧ください。

複合 ID

オブジェクトの ID がグローバルに一意でない場合、そのオブジェクトの複合 ID は、親 ID とチルダ（~）を先頭に追加して作成されます。

たとえば、AdGroupAd のリソース名パターンは customers/{customer_id}/adGroupAds/{ad_group_id}~{ad_id} です。この複合識別子は、親広告グループ ID（ad_group.id）と基になる広告 ID（ad_group_ad.ad.id）を組み合わせたものであるため、広告 ID の前に広告グループ ID を追加します。

  • AdGroupId（123）+ ~ + AdId（45678）= 複合広告グループの広告 ID（123~45678）。

リクエスト ヘッダー

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

承認

クライアントの代理として機能する MCC アカウント、または自身のアカウントを直接管理する広告主を識別する Authorization: Bearer YOUR_ACCESS_TOKEN 形式の OAuth 2.0 アクセス トークンを含める必要があります。アクセス トークンを取得する手順については、OAuth2 ガイドをご覧ください。アクセス トークンは、取得後 1 時間有効です。有効期限が切れたら、アクセス トークンを更新して新しいトークンを取得します。クライアント ライブラリは、期限切れのトークンを自動的に更新します。

認可エラーが発生した場合は、正しい認証情報を使用していること、十分な権限があることを確認してください。USER_PERMISSION_DENIED エラーは、認証されたユーザーがリクエストで指定されたクライアント アカウントにアクセスできない可能性があることを示します。Google Cloud プロジェクトが Test アクセスのみを承認されており、本番環境アカウントをターゲットとするリクエストを送信すると、API は v25 以降では AuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION（v24 以前では AuthorizationError.ACTION_NOT_PERMITTED）を返します。権限の管理について詳しくは、Google 広告のアクセスレベルをご覧ください。

login-customer-id

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

https://googleads.googleapis.com/v26/customers/1234567890/campaignBudgets:mutate

login-customer-id の設定は、ログイン後に Google 広告の管理画面でアカウントを選択するか、右上のプロフィール画像をクリックすることに相当します。このヘッダーを指定しない場合、デフォルトでオペレーティング カスタマーが使用されます。

linked-customer-id

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

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

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

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

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

  • 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 がマネージャー アカウント 3333333333 によって管理されている場合、マネージャー アカウント 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 は、このリクエストを一意に識別する文字列です。失敗した API リクエストや予期しない API リクエストのトラブルシューティングをサポートに問い合わせる場合は、この値を指定してください。

前へ
リソース メタデータ