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 は親広告グループ 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/v25/customers/1234567890/campaignBudgets:mutate

login-customer-id を設定することは、ログイン後または右上のプロフィール画像をクリックした後に Google 広告の UI でアカウントを選択することと同じです。このヘッダーを指定しない場合、デフォルトは運用顧客になります。

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 トレーリング メタデータ）がレスポンス本文とともに返されます。デバッグ用にこれらの値をログに記録することをおすすめします。

request-id

request-id は、このリクエストを一意に識別する文字列です。サポートにお問い合わせの際は、この値をお知らせください。API リクエストの失敗や予期しない動作のトラブルシューティングに役立ちます。

前へ
リソース メタデータ