このガイドでは、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 は空です）。検証に失敗すると、デフォルトでは GoogleAdsFailure RPC エラー（partial_failure = false）でリクエストが失敗するか、partial_failure = true の場合は partial_failure_error にオペレーション固有のエラーを含む通常のレスポンスが返されます。
validate_only は、一般的なポリシー違反に関する広告のテストに特に役立ちます。特定の単語、句読点、大文字、長さなどのポリシーに違反している広告は、自動的に不承認となります。1 つの不正な広告が原因で、バッチ全体が失敗する可能性があります。validate_only リクエスト内で新しい広告をテストすることで、このような違反を検出できます。実際に動作するコードについては、ポリシー違反エラーの処理のコード例を参照してください。
オブジェクトと掲載結果の統計情報を取得する
GoogleAdsService は、オブジェクトとパフォーマンス統計情報を取得するための単一の統合サービスです。
GoogleAdsService のすべての Search リクエストと SearchStream リクエストには、クエリを実行するリソース、取得するリソース属性とパフォーマンス指標、リクエストのフィルタリングに使用する述語、パフォーマンス統計情報の詳細な分析に使用するセグメントを指定するクエリが必要です。クエリ形式の詳細については、Google 広告クエリ言語ガイドをご覧ください。
メタデータの取得
GoogleAdsFieldService は、リソースで使用可能な属性やデータ型など、Google Ads API のリソースに関するメタデータを取得します。このサービスのクエリの詳細については、リソース メタデータ ガイドをご覧ください。
このサービスは、GoogleAdsService へのクエリの作成に必要な情報を提供します。便宜上、GoogleAdsFieldService から返される情報は、フィールド リファレンス ドキュメントでも確認できます。