API の構造

動画: 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	グローバル	○
キャンペーン 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

たとえば、お客様 ID が 1234567 の Google 広告アカウントで、ID が 987654 のキャンペーンの場合、resource_name は次のようになります。

customers/1234567/campaigns/987654

サービス

本サービスでは、Google 広告のエンティティの取得と変更を行うことができます。サービスには、変更、オブジェクトと統計情報の取得、メタデータ取得の 3 種類があります。

オブジェクトを変更（mutate）する

これらのサービスは、mutate リクエストを使用して、関連するリソースタイプのインスタンスを変更します。また、単一のリソースインスタンスを取得する get リクエストも提供します。これは、リソースの構造を調べる場合に便利です。

サービスの例:

CustomerService: customers を変更します。
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 から返される情報は、フィールドリファレンスドキュメントでもご確認いただけます。

概要

エンティティの関係