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 を追加します。

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

リクエスト ヘッダー

リクエストの本文に付随する 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 がクライアント センター（MCC）アカウント 3333333333 によって管理され、クライアント センター（MCC）アカウント 3333333333 がパートナー アカウント 2222222222 とリンクしていて、API 呼び出しが customers/1111111111/... をターゲットにしている場合:

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

レスポンス ヘッダー

次のヘッダー（または gRPC トレーリング メタデータ）がレスポンス本文とともに返されます。デバッグ用にこれらの値をログに記録することをおすすめします。

request-id

request-id は、このリクエストを一意に識別する文字列です。失敗した API リクエストや予期しない API リクエストのトラブルシューティングを行う場合は、サポートに問い合わせる際にこの値を指定してください。

前へ
リソース メタデータ