動画: 2019 年のワークショップでのサービスとリソースに関する講演をご覧ください
このガイドでは、Google Ads API を構成する主要コンポーネントについて説明します。Google Ads API はリソース とサービス で構成されています。リソースは Google 広告エンティティを表し、サービスは Google 広告エンティティを取得して操作します。
オブジェクト階層
Google 広告アカウントは、オブジェクトの階層として見ることができます。
アカウントの最上位のリソースは 顧客です。
各顧客には、1 つ以上のアクティブな キャンペーンが含まれています。
各キャンペーンには、広告を論理的なコレクションにグループ化するために使用される広告グループが 1 つ以上含まれています。
広告グループ広告は、掲載している広告を 表します。広告グループごとに 1 つの広告グループ広告のみを設定できるアプリ キャンペーンを除き、各広告グループには 1 つ以上の広告グループ広告が含まれています。
1 つ以上の AdGroupCriterion
または CampaignCriterion を広告グループまたは
キャンペーンに添付できます。これらは、広告がトリガーされる仕組みを定義する条件を表します。
条件には、キーワード、年齢層、地域など、 さまざまな種類があります。キャンペーン レベルで定義された条件は、キャンペーン内の他のすべてのリソースに影響します。キャンペーン全体の予算と日付を指定することもできます。
最後に、アセットをアカウント、キャンペーン、または広告グループ レベルで添付できます。 アセットを使用すると、電話番号、住所、プロモーションなど、広告に追加情報を提供できます。アセットの概要をご覧ください。
リソース
リソースは、Google 広告アカウント内のエンティティを表します。Campaign と AdGroup は、リソースの 2 つの例です。
オブジェクト ID
Google 広告のすべてのオブジェクトは、独自の ID で識別されます。これらの ID の一部はすべての Google 広告アカウントでグローバルに一意ですが、他の ID は限られた範囲内でのみ一意です。
| オブジェクト ID | 一意性のスコープ | グローバルで一意ですか？ |
|---|---|---|
| 予算 ID | グローバル | あり |
| Campaign ID | グローバル | あり |
| AdGroup ID | グローバル | あり |
| Ad ID | 広告グループ | いいえ。ただし、（AdGroupId、AdId）のペアはグローバルで一意です。 |
| AdGroupCriterion ID | 広告グループ | いいえ。ただし、（AdGroupId、CriterionId）のペアはグローバルで一意です。 |
| CampaignCriterion ID | キャンペーン | いいえ。ただし、（CampaignId、CriterionId）のペアはグローバルで一意です。 |
| ラベル ID | お客様 | いいえ。ただし、（CustomerId、LabelId）のペアはグローバルで一意です。 |
| ユーザーリスト 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顧客を変更するための customers。CampaignServiceキャンペーンを変更するための 。AdGroupService広告グループを変更するための ad groups。
各 mutate リクエストには、対応する operation オブジェクトを含める必要があります。たとえば、CampaignService.MutateCampaigns メソッドは、
CampaignOperation の 1 つ以上のインスタンスを想定しています。オペレーションの詳細については、
オブジェクトの変更と検査をご覧ください。
同時変換
Google 広告 オブジェクトには、複数のソースから同時並行で変更を加えることはできません。複数のユーザーがアプリで同じオブジェクトを更新している場合や、複数のスレッドを使用して Google 広告オブジェクトを並行して変更している場合は、エラーが発生する可能性があります。これには、同じアプリケーション内の複数のスレッドから、または異なるアプリケーション（アプリと同時セッションの Google 広告管理画面など）からオブジェクトを更新する場合が含まれます。
API には、更新前にオブジェクトをロックする方法はありません。2 つのソースがオブジェクトを同時に変更しようとすると、API は
DatabaseError.CONCURRENT_MODIFICATION_ERROR を発生させます。
非同期と同期の変更
Google Ads API の mutate メソッドは同期的です。API 呼び出しは、オブジェクトが変更された後にのみレスポンスを返すため、各リクエストのレスポンスを待つ必要があります。この方法は比較的簡単にコーディングできますが、プロセスが呼び出しの完了を待つ必要がある場合、ロード バランシングに悪影響を及ぼし、リソースを無駄にする可能性があります。
別の方法として、
BatchJobServiceを使用してオブジェクトを非同期で変更する方法があります。この方法では、完了を待たずに複数のサービスに対して
オペレーションのバッチを実行します。バッチジョブが送信されると、Google Ads API サーバーはオペレーションを非同期で実行し、プロセスが他のオペレーションを実行できるようにします。ジョブのステータスを定期的に確認して、完了を確認できます。
非同期処理について詳しくは、バッチ処理ガイドをご覧ください。
変換の検証
ほとんどの mutate リクエストは、実際のデータに対して呼び出しを実行しなくても検証できます。オペレーションを実際に実行しなくても、リクエストにパラメータが不足していないか、フィールドの値が正しくないかをテストできます。
この機能を使用するには、リクエストのオプションの validate_only ブール値フィールドを true に設定します。リクエストは実行されるかのように完全に検証されますが、最終的な実行はスキップされます。エラーが見つからない場合は、空のレスポンスが返されます。検証に失敗した場合は、レスポンスのエラー メッセージに失敗した箇所が示されます。
validate_only は、一般的なポリシー違反について広告をテストする場合に特に便利です。特定の単語、句読点、大文字、長さなどのポリシーに違反している場合、広告は自動的に不承認となります。1 つの不正な広告が原因で、バッチ全体が失敗する可能性があります。validate_only リクエスト内で新しい広告をテストすると、このような違反を検出できます。実際の動作については、ポリシー違反エラーの
処理に関するコード例をご覧ください。
オブジェクトと掲載結果の統計情報を取得する
GoogleAdsService は、オブジェクトと掲載結果の統計情報を取得するための単一の統合サービスです。
GoogleAdsService のすべての Search リクエストと SearchStream リクエストには、クエリするリソース、取得するリソース属性と掲載結果の指標、リクエストのフィルタに使用する述語関数、掲載結果の統計情報をさらに細分化するために使用するセグメントを指定するクエリが必要です。クエリの形式について詳しくは、
Google 広告クエリ言語ガイドをご覧ください。
メタデータの取得
GoogleAdsFieldService はリソースで使用可能な属性やそのデータ型など、Google Ads API のリソースに関するメタデータを取得します。
このサービスは、クエリの作成に必要な情報を提供します
GoogleAdsService。便宜上、
GoogleAdsFieldService により返される情報は、
フィールド リファレンス ドキュメントでもご覧いただけます。