通常、検索広告 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 UI でアカウントを選択するか、右上にある自分のプロフィール画像をクリックしたときと同じ効果が得られます。
レスポンス ヘッダー
以下のヘッダー（gRPC trailing-metadata）がレスポンスの本文とともに返されます。デバッグ目的でこれらの値をログに記録することをおすすめします。
リクエスト ID
request-id ヘッダーは、リクエストを一意に識別する文字列です。