動画: 2019 年のワークショップでのサービスとリソースに関する講演をご覧ください
このガイドでは、Google Ads API を構成する主要コンポーネントについて説明します。Google Ads API はリソースとサービスで構成されています。リソースは Google 広告エンティティを表し、サービスは Google 広告エンティティを取得して操作します。
オブジェクト階層
Google 広告アカウントは、オブジェクトの階層と見なすことができます。
アカウントの最上位リソースはお客様です。
各お客様には、有効なキャンペーンが 1 つ以上含まれています。
各キャンペーンには 1 つ以上の広告グループが含まれます。広告グループは、広告を論理的なコレクションにグループ化するために使用されます。
広告グループ広告は、配信中の広告を表します。アプリ キャンペーンを除き、各広告グループには 1 つ以上の広告グループ広告が含まれます。アプリ キャンペーンでは、広告グループごとに 1 つの広告グループ広告のみを含めることができます。
1 つ以上の AdGroupCriterion または CampaignCriterion を広告グループまたはキャンペーンに適用できます。これらは、広告のトリガー方法を定義する条件を表します。
条件の種類には、キーワード、年齢層、地域など、さまざまなものがあります。キャンペーン単位で定義された条件は、キャンペーン内の他のすべてのリソースに影響します。キャンペーン全体の予算と期間を指定することもできます。
最後に、広告表示オプションをアカウント単位、キャンペーン単位、または広告グループ単位で関連付けることができます。広告表示オプションを使用すると、電話番号、住所、プロモーションなどの追加情報を広告に表示できます。
リソース
リソースは、Google 広告アカウント内のエンティティを表します。Campaign と AdGroup はリソースの例です。
オブジェクト ID
Google 広告のすべてのオブジェクトは、独自の ID で識別されます。これらの ID には、すべての Google 広告アカウントでグローバルに一意のものもあれば、限定されたスコープ内でのみ一意のものもあります。
| オブジェクト ID | 一意性の範囲 | グローバルで一意ですか？ |
|---|---|---|
| 予算 ID | グローバル | あり |
| Campaign ID | グローバル | あり |
| AdGroup ID | グローバル | あり |
| Ad ID | 広告グループ | いいえ。ただし、（AdGroupId、AdId）ペアはグローバルに一意です。 |
| AdGroupCriterion ID | 広告グループ | いいえ。ただし、（AdGroupId、CriterionId）ペアはグローバルに一意です。 |
| CampaignCriterion ID | キャンペーン | いいえ。ただし、（CampaignId、CriterionId）ペアはグローバルに一意です。 |
| 広告表示オプション | キャンペーン | いいえ。ただし、（CampaignId、AdExtensionId）ペアはグローバルに一意です。 |
| フィード ID | グローバル | あり |
| Feed Item ID | グローバル | あり |
| Feed Attribute ID | フィード | なし |
| Feed Mapping ID | グローバル | あり |
| Label ID | グローバル | ○ |
| ユーザーリスト ID | グローバル | ○ |
これらの ID ルールは、Google 広告オブジェクトのローカル ストレージを設計する際に役立ちます。
一部のオブジェクトは、複数のエンティティ タイプに使用できます。このような場合、オブジェクトには内容を記述する type フィールドが含まれます。たとえば、AdGroupAd は、テキスト広告、ホテル広告、ローカル広告などのオブジェクトを参照できます。この値には AdGroupAd.ad.type フィールドからアクセスでき、AdType 列挙型の値を返します。
リソース名
各リソースは resource_name 文字列によって一意に識別され、リソースとその親をパスに連結します。たとえば、キャンペーン リソース名の形式は次のとおりです。
customers/customer_id/campaigns/campaign_id
Google 広告アカウントのキャンペーン ID が 987654、お客様 ID が 1234567 の場合、resource_name は次のようになります。
customers/1234567/campaigns/987654
サービス
サービスを使用すると、Google 広告エンティティを取得して変更できます。サービスには、変更、オブジェクトと統計情報の取得、メタデータの取得の 3 種類があります。
オブジェクトを変更（mutate）する
これらのサービスは、mutate リクエストを使用して関連するリソースタイプのインスタンスを変更します。また、単一のリソース インスタンスを取得する get リクエストも提供します。これはリソースの構造を調べる場合に役に立ちます。
サービスの例:
CustomerService: お客様の変更。CampaignService: キャンペーンを変更します。AdGroupService: 広告グループを変更します。
各 mutate リクエストには、対応する operation オブジェクトを含める必要があります。たとえば、CampaignService.MutateCampaigns メソッドは CampaignOperation の 1 つ以上のインスタンスを想定しています。オペレーションの詳細については、オブジェクトの変更と検査をご覧ください。
同時変換
Google 広告 オブジェクトには、複数のソースから同時並行で変更を加えることはできません。複数のユーザーがアプリで同じオブジェクトを更新する場合や、複数のスレッドを使用して Google 広告オブジェクトを並行して変更する場合、エラーが発生する可能性があります。これには、同じアプリ内の複数のスレッドから、または異なるアプリ（アプリと同時に実行されている Google 広告 UI セッションなど）からオブジェクトを更新することが含まれます。
この API には、更新前にオブジェクトをロックする方法はありません。2 つのソースが同時にオブジェクトを変更しようとすると、API は DatabaseError.CONCURRENT_MODIFICATION_ERROR を発生させます。
非同期ミューテーションと同期ミューテーション
Google Ads API の変更メソッドは同期的です。API 呼び出しは、オブジェクトが変更された後にのみレスポンスを返します。そのため、各リクエストのレスポンスを待機する必要があります。このアプローチはコードを記述するのが比較的簡単ですが、プロセスが呼び出しの完了を待機しなければならない場合、ロード バランシングに悪影響を及ぼし、リソースを浪費する可能性があります。
別の方法として、BatchJobService を使用してオブジェクトを非同期で変更することもできます。この方法では、完了を待たずに複数のサービスに対してオペレーションのバッチを実行します。バッチジョブが送信されると、Google Ads API サーバーはオペレーションを非同期で実行し、他のオペレーションを実行するためのプロセスを解放します。ジョブのステータスを定期的に確認して、完了を確認できます。
非同期処理の詳細については、バッチ処理ガイドをご覧ください。
変換の検証
ほとんどの変更リクエストは、実際のデータに対して呼び出しを実際に実行しなくても検証できます。オペレーションを実際に実行せずに、パラメータが不足しているリクエストやフィールド値が正しくないリクエストをテストできます。
この機能を使用するには、リクエストのオプションの validate_only ブール値フィールドを true に設定します。リクエストは、実行されるかのように完全に検証されますが、最終的な実行はスキップされます。エラーが見つからない場合、空のレスポンスが返されます。検証で不合格だった場合は、レスポンスのエラー メッセージに不合格の内容が示されます。
validate_only は、広告で一般的なポリシー違反がないかテストする場合に特に役立ちます。特定の単語、句読点、大文字、長さなど、ポリシーに違反している広告は自動的に拒否されます。1 つの不適切な広告が原因で、バッチ全体が失敗する可能性があります。validate_only リクエスト内で新しい広告をテストすると、このような違反が検出されます。実際に動作するコードについては、ポリシー違反エラーの処理のコード例をご覧ください。
オブジェクトと掲載結果の統計情報を取得する
GoogleAdsService は、オブジェクトと掲載結果の統計情報を取得するための単一の統合サービスです。
GoogleAdsService のすべての Search リクエストと SearchStream リクエストには、クエリするリソース、取得するリソース属性と掲載結果の指標、リクエストのフィルタに使用する述語関数、掲載結果の統計情報をさらに細分化するために使用するセグメントを指定するクエリが必要です。クエリの形式について詳しくは、Google 広告クエリ言語ガイドをご覧ください。
メタデータの取得
GoogleAdsFieldService は、リソースで使用可能な属性やそのデータ型など、Google Ads API のリソースに関するメタデータを取得します。
このサービスは、GoogleAdsService へのクエリの作成に必要な情報を提供します。GoogleAdsFieldService により返される情報は、フィールド リファレンス ドキュメントでもご覧いただけます。