動画: 2019 年のワークショップでのサービスとリソースのトークを確認する
このガイドでは、Google Ads API を構成する主なコンポーネントをご紹介します。Google Ads API はリソースとサービスで構成されます。リソースは Google 広告エンティティを表しますが、サービスは Google 広告エンティティの取得と操作を行います。
オブジェクト階層
Google 広告アカウントは、オブジェクトの階層と考えることができます。
アカウントの最上位リソースはお客様です。
各アカウントには、有効なキャンペーンが 1 つ以上含まれています。
各
Campaignには、広告を論理的なコレクションにまとめるために使用される 1 つ以上の広告グループが含まれます。各
AdGroupには、1 つ以上の広告グループ広告が含まれています。AdGroupAdは、掲載している広告を表します。
1 つ以上の AdGroupCriterion または CampaignCriterion を広告グループまたはキャンペーンに追加できます。広告の表示基準を定義します。
キーワード、年齢層、地域など、さまざまな条件タイプを使用できます。キャンペーン レベルで定義された基準は、キャンペーン内の他のすべてのリソースに影響します。キャンペーン全体の予算と日付も指定できます。
最後に、アカウント、キャンペーン、広告グループの各単位で広告表示オプションを追加できます。広告表示オプションを使用すると、広告に追加情報（電話番号、住所、プロモーションなど）を提供できます。
リソース
リソースは、Google 広告アカウント内のエンティティを表します。Campaign と AdGroup は 2 つのリソースの例です。
オブジェクト ID
Google 広告内のすべてのオブジェクトは、固有の ID で識別されます。一部の ID は、すべての Google 広告アカウントでグローバルに一意なものと、特定の範囲でのみ一意です。
| オブジェクト ID | 一意性のスコープ | グローバル レベルでの一意性 |
|---|---|---|
| 予算 ID | グローバル | ○ |
| キャンペーン ID | Global | ○ |
| AdGroup ID | Global | ○ |
| Ad ID | 広告グループ | いいえ。ただし、（AdGroupId、AdId）ペアはグローバルに一意です。 |
| AdGroupCriterion ID | 広告グループ | いいえ。ただし、（AdGroupId、CriterionId）ペアはグローバルに一意です。 |
| CampaignCriterion ID | キャンペーン | いいえ。ただし、（CampaignId、CriterionId）ペアはグローバルに一意です。 |
| 広告表示オプション | キャンペーン | いいえ。ただし、（CampaignId、AdExtensionId）ペアはグローバルに一意です。 |
| フィード ID | グローバル | ○ |
| Feed Item ID | Global | ○ |
| Feed Attribute ID | フィード | いいえ |
| Feed Mapping ID | Global | ○ |
| Label ID | Global | ○ |
| ユーザーリスト ID | Global | ○ |
これらの ID ルールは、Google 広告オブジェクトのローカル ストレージを設計するときに便利です。
一部のオブジェクトは複数のエンティティ タイプに使用できます。その場合、オブジェクトにはその内容を説明する type フィールドが含まれます。たとえば、AdGroupAd はテキスト広告、ホテル広告、ローカル広告などを参照できます。この値は AdGroupAd.ad.type フィールドからアクセスでき、AdType 列挙型で値を返します。
リソース名
各リソースは、リソースとその親をパスに連結する resource_name 文字列で一意に識別されます。たとえば、キャンペーンのリソース名は次の形式になります。
customers/customer_id/campaigns/campaign_id
そのため、お客様 ID 1234567 の Google 広告アカウントで ID が 987654 のキャンペーンの場合、resource_name は次のようになります。
customers/1234567/campaigns/987654
サービス
サービスでは、Google 広告のエンティティを取得して変更できます。サービスには、変更、オブジェクトと統計情報の取得、メタデータ取得の 3 種類があります。
オブジェクトを変更（mutate）する
これらのサービスは、mutate リクエストを使用して、関連付けられたリソースタイプのインスタンスを変更します。また、1 つのリソース インスタンスを取得する get リクエストも提供します。これはリソースの構造を調べるのに便利です。
サービスの例:
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 に設定します。リクエストは、実行されるかのように完全に検証されますが、最終的な実行はスキップされます。エラーが見つからない場合は、空のレスポンスが返されます。検証で不合格だった場合、レスポンスのエラー メッセージに障害点が表示されます。
validate_only は、一般的なポリシー違反について広告をテストする場合に特に役立ちます。特定の語句、句読点、大文字、長さなどのポリシーに違反した広告は自動的に不承認となります。不正な広告が 1 つしかないと、バッチ全体が失敗する可能性があります。validate_only リクエストで新しい広告をテストすると、こうした違反を確認できます。実際に対処するには、ポリシー違反エラーの処理に関するコードサンプルをご覧ください。
オブジェクトと掲載結果の統計情報を取得する
GoogleAdsService は、オブジェクトとパフォーマンス統計を取得するための単一の統合サービスです。
GoogleAdsService のすべての Search および SearchStream リクエストには、クエリするリソース、取得するリソース属性とパフォーマンス指標、リクエストのフィルタリングに使用する述語、パフォーマンス統計をさらに細かく分類するためのセグメントを指定するクエリが必要です。クエリの形式について詳しくは、Google 広告クエリ言語ガイドをご覧ください。
メタデータを取得する
GoogleAdsFieldService は、Google Ads API のリソースに関するメタデータを取得します。たとえば、リソースで利用可能な属性やそのデータ型などです。
このサービスでは、GoogleAdsService へのクエリの作成に必要な情報が提供されます。便宜上、GoogleAdsFieldService から返される情報をフィールド リファレンス ドキュメントで参照することもできます。