このガイドでは、Google Ads API を構成する主要なコンポーネントについて説明します。Google Ads API は、リソースとサービスで構成されています。リソースは Google 広告エンティティを表し、サービスは Google 広告エンティティを取得して操作します。
オブジェクト階層
Google 広告アカウントは、オブジェクトの階層と見なすことができます。
アカウントの最上位リソースは customer です。
各顧客には、1 つ以上の有効なキャンペーンが含まれています。
各キャンペーンには、広告を論理的なコレクションにグループ化するために使用される 1 つ以上の広告グループが含まれています。
広告グループの広告は、広告グループで実行している広告を表します。アプリ キャンペーン（広告グループごとに 1 つの広告グループ広告のみを設定可能）を除き、各広告グループには 1 つ以上の広告グループ広告が含まれます。
P-MAX キャンペーンは、他のキャンペーン タイプとは異なる構造を使用します。P-MAX キャンペーンには、広告グループと広告グループ広告ではなく、アセット グループが含まれます。クリエイティブ アセットをアセット グループにリンクするには AssetGroupAsset を使用し、オーディエンス シグナルまたは検索テーマ シグナルを関連付けるには AssetGroupSignal を使用します。
1 つ以上の AdGroupCriterion リソースまたは CampaignCriterion リソースを広告グループまたはキャンペーンに添付できます。これらは、広告がトリガーされる仕組みを定義する条件を表します。
キーワード、年齢層、地域など、さまざまな条件タイプがあります。キャンペーン単位で定義された条件は、キャンペーン内の他のすべてのリソースに影響します。AdGroupAd.start_date_time と AdGroupAd.end_date_time を使用して、キャンペーンまたは個別の広告の予算、開始日時、終了日時を指定することもできます。
最後に、アカウント、キャンペーン、広告グループ、アセット グループの単位でアセットを関連付けることができます。アセットを使用すると、電話番号、番地、プロモーションなどの追加情報を広告に表示できます。アセットの概要をご覧ください。
リソース
リソースは、Google 広告アカウント内のエンティティを表します。Campaign と AdGroup は、リソースの 2 つの例です。
オブジェクト ID
Google 広告のすべてのオブジェクトは、独自の ID で識別されます。これらの ID の一部はすべての Google 広告アカウントでグローバルに一意ですが、一部は限定された範囲内でのみ一意です。
| オブジェクト ID | 一意性の範囲 | グローバル レベルでの一意性 |
|---|---|---|
| Budget ID | グローバル | あり |
| Campaign ID | グローバル | あり |
| AdGroup ID | グローバル | あり |
| 広告 ID | 広告グループ | いいえ。ただし、（AdGroupId、AdId）のペアはグローバルに一意です。複数の広告グループ間で AdId を共有することは禁止されています。 |
| AdGroupCriterion ID | 広告グループ | いいえ。ただし、（AdGroupId、CriterionId）のペアはグローバルに一意です。 |
| CampaignCriterion ID | キャンペーン | いいえ。ただし、（CampaignId、CriterionId）のペアはグローバルに一意です。 |
| ラベル ID | お客様 | いいえ。ただし、（CustomerId、LabelId）のペアはグローバルに一意です。 |
| UserList ID | グローバル | ○ |
| アセット ID | グローバル | ○ |
これらの ID ルールは、Google 広告オブジェクトのローカル ストレージを設計する際に役立ちます。
一部のオブジェクトは、複数のエンティティ タイプで使用できます。このような場合、オブジェクトにはその内容を説明する type フィールドが含まれます。たとえば、AdGroupAd は、レスポンシブ検索広告、ホテル広告、デマンド ジェネレーション広告などのオブジェクトを参照できます。この値には AdGroupAd.ad.type フィールドからアクセスでき、AdType 列挙型の値が返されます。可変性はバージョンによって異なる場合があります（たとえば、Ad の VideoResponsiveAdInfo は v24 以降で可変です）。
リソース名
各リソースは、リソースとその親をパスに連結する resource_name 文字列によって一意に識別されます。たとえば、キャンペーンのリソース名は次の形式になります。
customers/customer_id/campaigns/campaign_id
たとえば、お客様 ID が 1234567 の Google 広告アカウントで、ID が 987654 のキャンペーンの場合、resource_name は次のようになります。
customers/1234567/campaigns/987654
サービス
サービスを使用すると、Google 広告のエンティティを取得して変更できます。サービスには、変更、オブジェクトと統計情報の取得、メタデータの取得サービスの 3 種類があります。
オブジェクトを変更（mutate）する
リソース固有のサービスは、mutate リクエストを使用して、関連付けられたリソースタイプのインスタンスを変更します。GoogleAdsService.Mutate を使用して、1 つのリクエストで複数のリソースタイプにわたるアトミック ミューテーションを実行することもできます（キャンペーンの予算、キャンペーン、広告グループをまとめて作成するなど）。
リソース固有のサービスの例:
お客様を変更するための
CustomerService。キャンペーンを変更するための
CampaignService。広告グループを変更するための
AdGroupService。
各 mutate リクエストには、対応する operation オブジェクトを含める必要があります。たとえば、CampaignService.MutateCampaigns メソッドは CampaignOperation の 1 つ以上のインスタンスを想定しています。オペレーションの詳細については、オブジェクトの変更をご覧ください。
同時変換
Google 広告 オブジェクトには、複数のソースから同時並行で変更を加えることはできません。複数のユーザーがアプリを使用して同じオブジェクトを更新している場合や、複数のスレッドを使用して Google 広告オブジェクトを並行して変更している場合は、エラーが発生する可能性があります。これには、同じアプリケーションの複数のスレッドから、または異なるアプリケーション（アプリと Google 広告 UI の同時セッションなど）からオブジェクトを更新することが含まれます。
この API には、更新前にオブジェクトをロックする方法はありません。2 つのソースが同時にオブジェクトを変更しようとすると、API は DatabaseError.CONCURRENT_MODIFICATION_ERROR を発生させます。
非同期ミューテーションと同期ミューテーション
Google Ads API の mutate メソッドは同期的です。API 呼び出しは、オブジェクトが変更された後にのみレスポンスを返します。そのため、各リクエストのレスポンスを待つ必要があります。このアプローチは比較的簡単にコーディングできますが、プロセスが呼び出しの完了を待機することを強制されると、ロード バランシングに悪影響を及ぼし、リソースを無駄にする可能性があります。
別の方法として、BatchJobService を使用してオブジェクトを非同期で変更することもできます。この方法では、複数のサービスに対して一連のオペレーションをバッチ処理し、完了を待たずに次の処理に進みます。バッチジョブが送信されると、Google Ads API サーバーはオペレーションを非同期で実行し、プロセスを解放して他のオペレーションを実行します。ジョブのステータスを定期的に確認して、完了したかどうかを確認できます。
非同期処理の詳細については、バッチ処理ガイドをご覧ください。
変換の検証
ほとんどの変更リクエストは、実際のデータに対して呼び出しを実際に実行しなくても検証できます。オペレーションを実際に実行せずに、欠落しているパラメータと正しくないフィールド値のリクエストをテストできます。
この機能を使用するには、リクエストのオプションの validate_only ブール値フィールドを true に設定します。リクエストは、実行されるかのように完全に検証されますが、最終的な実行はスキップされます。エラーが見つからない場合、レスポンスは、変更された結果が入力されずに返されます（results は空です）。検証が失敗すると、リクエストはデフォルト（partial_failure = false）で GoogleAdsFailure RPC エラーで失敗するか、partial_failure = true の場合に partial_failure_error でオペレーション固有のエラーを含む通常のレスポンスを返します。
validate_only は、一般的なポリシー違反の広告をテストする場合に特に役立ちます。特定の単語、句読点、大文字、長さなど、ポリシーに違反している広告は自動的に不承認となります。1 つの不正な広告が原因で、バッチ全体が失敗する可能性があります。validate_only リクエスト内で新しい広告をテストすると、このような違反を検出できます。実際の動作については、ポリシー違反エラーの処理のコード例をご覧ください。
オブジェクトと掲載結果の統計情報を取得する
GoogleAdsService は、オブジェクトとパフォーマンス統計情報を取得するための単一の統合サービスです。
GoogleAdsService のすべての Search リクエストと SearchStream リクエストには、クエリを実行するリソース、取得するリソース属性とパフォーマンス指標、リクエストのフィルタリングに使用する述語、パフォーマンス統計情報の詳細な分析に使用するセグメントを指定するクエリが必要です。クエリ形式の詳細については、Google 広告クエリ言語ガイドをご覧ください。
メタデータの取得
GoogleAdsFieldService は、Google Ads API のリソースに関するメタデータ（リソースで使用可能な属性やそのデータ型など）を取得します。このサービスへのクエリの詳細については、リソース メタデータ ガイドをご覧ください。
このサービスは、GoogleAdsService へのクエリの作成に必要な情報を提供します。便宜上、GoogleAdsFieldService から返される情報は、フィールド リファレンス ドキュメントでも確認できます。