通常、検索広告 360 Reporting API への呼び出しは、クライアント ライブラリを介して行います。詳細については、クライアント ライブラリの説明をご覧ください。ただし、テストやデバッグを行う際には、基盤となるリクエストの詳細の構造に関する知識が役立ちます。
Search Ads 360 Reporting API は、REST バインディングを利用した gRPC API です。つまり、API を呼び出す方法は次の 2 つです。
- 推奨される方法
- クライアント ライブラリを使用する:
- リクエストの本文をプロトコル バッファとして作成します。
- HTTP/2 を使用してリクエストをサーバーに送信します。
- レスポンスをプロトコル バッファにシリアル化解除します。
- 結果を解釈する。
- オプションの代替方法
- REST を使用します。
- リクエストの本文を JSON オブジェクトとして作成します。
- HTTP 1.1 を使用してリクエストをサーバーに送信する。
- レスポンスを JSON オブジェクトとして逆シリアル化します。
- 結果を解釈する。
詳細については、Google Cloud APIs をご覧ください。
以降のセクションは、gRPC プロトコルと REST プロトコルの両方に適用されます。
リソース名
API のほとんどのオブジェクトは、リソース名文字列で識別されます。これらの文字列は、REST インターフェースを使用する場合は URL としても機能します。
サポートされているリソースとそのパス表現の詳細については、[リファレンス] > [REST] をご覧ください。他のサービスにも同じ形式が使用されます。
複合 ID
オブジェクトの ID がグローバルに一意でない場合、そのオブジェクトの複合 ID は、親 ID とチルド（~）を前に付けて作成されます。
たとえば、広告グループ広告 ID はグローバル レベルで一意ではないため、親オブジェクト（広告グループ）ID を先頭に追加して、一意の複合 ID を作成します。
例: 123 の AdGroupId + ~ + 45678 の AdGroupAdId = 複合広告グループの広告 ID 123~45678。
リクエスト ヘッダー
次のセクションの HTTP ヘッダー（または gRPC メタデータ）をリクエストの本文に含める必要があります。
承認
OAuth2 アクセス トークンを次の形式で含める必要があります。
Authorization: Bearer [OAUTH_2.0_ACCESS_TOKEN]
このトークンは、クライアントの代理を務める MCC アカウントか、独自のサブマネージャーまたはクライアント アカウントを直接管理している広告主を識別できる必要があります。詳しくは、検索広告 360 のクライアント センター（MCC）アカウントについてと認証をご覧ください。
ログイン用お客様 ID ヘッダー
マネージャー アカウントを使用してサブマネージャー アカウントまたはクライアント アカウントにアクセスする場合は、login-customer-id ヘッダーが必要です。サブマネージャー アカウントまたはクライアント アカウントに直接アクセスする場合は必要ありません。厳密には必須ではありませんが、複数のアカウントにアクセスできる認証済みユーザーに対しては、常に login-customer-id を指定することをおすすめします。これにより、あいまいさが回避され、コンテキストが意図せず正しくないアカウントに設定されることがなくなります。
リクエストには、承認済みユーザーのお客様 ID をハイフンなしで含める必要があります（-）。次に例を示します。
https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/campaignBudgets
login-customer-id を設定することは、ログイン後に検索広告 360 の管理画面でアカウントを選択するか、右上のプロフィール画像をクリックすることと同じです。
レスポンス ヘッダー
以下のヘッダー（gRPC trailing-metadata）がレスポンスの本文とともに返されます。デバッグ目的でこれらの値をログに記録することをおすすめします。
リクエスト ID
request-id ヘッダーは、リクエストを一意に識別する文字列です。