API の構造

動画: 2019 年のワークショップで紹介されたサービスとリソースに関する動画をご覧ください

このガイドでは、Google Ads API を構成する主なコンポーネントを紹介します。Google Ads API は「リソース」と「サービス」で構成されます。リソースは Google 広告エンティティを表し、サービスは Google 広告エンティティを取得して操作します。

オブジェクト階層

Google 広告アカウントは、オブジェクトの階層として見ることができます。

キャンペーン モデル

  • アカウントの最上位のリソースは顧客です。

  • 各顧客には有効なキャンペーンが 1 つ以上含まれています。

  • 各キャンペーンには 1 つ以上の広告グループが含まれ、広告グループを使用して広告を論理的なコレクションにグループ化します。

  • 広告グループ広告は、掲載中の広告を表します。広告グループごとに 1 つの広告グループ広告しか作成できないアプリ キャンペーンを除き、各広告グループには 1 つ以上の広告グループ広告が含まれます。

1 つ以上の AdGroupCriterion または CampaignCriterion を、広告グループまたはキャンペーンに関連付けることができます。広告をトリガーする方法を定義する条件を表します。

条件タイプには、キーワード、年齢層、地域など、さまざまな種類があります。キャンペーン レベルで定義された条件は、キャンペーン内の他のすべてのリソースに影響します。また、キャンペーン全体の予算と期間を指定することもできます。

最後に、アカウント、キャンペーン、または広告グループ単位で広告表示オプションを追加します。広告表示オプションを使うと、電話番号、住所、プロモーションなどの追加情報を広告に追加できます。

リソース

リソースは、Google 広告アカウント内のエンティティを表します。リソースの例として、CampaignAdGroup があります。

オブジェクト ID

Google 広告のオブジェクトは、それぞれ固有の ID で識別されます。これらの ID には、すべての Google 広告アカウントでグローバルに一意であるものと、限られた範囲内でのみ一意であるものがあります。

オブジェクト ID 一意性の範囲 グローバルに一意か?
予算 ID グローバル
キャンペーン ID Global
AdGroup ID Global
Ad ID 広告グループ いいえ。ただし、(AdGroupIdAdId)ペアはグローバルに一意です
AdGroupCriterion ID 広告グループ いいえ。ただし、(AdGroupIdCriterionId)ペアはグローバルに一意です
CampaignCriterion ID キャンペーン いいえ。ただし、(CampaignIdCriterionId)ペアはグローバルに一意です
広告表示オプション キャンペーン いいえ。ただし、(CampaignIdAdExtensionId)ペアはグローバルに一意です
フィード 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

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

customers/1234567/campaigns/987654

サービス

サービスを使用すると、Google 広告のエンティティを取得、変更できます。サービスには、変更、オブジェクトと統計情報の取得、メタデータ取得の 3 つのタイプがあります。

オブジェクトを変更(mutate)する

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

サービスの例:

mutate リクエストには、対応する operation オブジェクトを含める必要があります。たとえば、CampaignService.MutateCampaigns メソッドは CampaignOperation の 1 つ以上のインスタンスを想定しています。オペレーションについて詳しくは、オブジェクトの変更と検査をご覧ください。

同時変換

Google 広告 オブジェクトには、複数のソースから同時並行で変更を加えることはできません。このため、複数のユーザーがアプリで同じオブジェクトを更新している場合や、複数のスレッドを使用して Google 広告 オブジェクトを並行して変更する場合は、エラーが発生する可能性があります。これには、同じアプリの複数のスレッドや異なるアプリの複数のスレッド(アプリと同時の Google 広告 UI セッションなど)からオブジェクトを更新することも含まれます。

この API には、更新前にオブジェクトをロックする方法はありません。2 つのソースがオブジェクトを同時に変更しようとすると、API は DatabaseError.CONCURRENT_MODIFICATION_ERROR を発生させます。

非同期変換と同期変換

Google Ads API の mut メソッドは同期的です。API 呼び出しはオブジェクトが変更された後にのみレスポンスを返すため、各リクエストに対するレスポンスを待つ必要があります。このアプローチはコーディングが比較的簡単ですが、プロセスが呼び出しの完了を待たなければならない場合、ロード バランシングに悪影響を及ぼし、リソースを浪費する可能性があります。

別の方法として、BatchJobService を使用してオブジェクトを非同期で変更することもできます。この方法では、オペレーションの完了を待たずに、複数のサービスに対してバッチ オペレーションが実行されます。バッチジョブが送信されると、Google Ads API サーバーはオペレーションを非同期で実行し、プロセスが他のオペレーションを実行できるようになります。ジョブの完了状況を定期的に確認できます。

非同期処理の詳細については、バッチ処理ガイドをご覧ください。

変換の検証

ほとんどの変換リクエストは、実際のデータに対して呼び出しを実際に実行することなく検証できます。実際にオペレーションを実行しなくても、パラメータの不足やフィールド値の誤りに関するリクエストをテストできます。

この機能を使用するには、リクエストのオプションの validate_only ブール値フィールドを true に設定します。その場合、リクエストが実行される場合と同様に完全に検証されますが、最終的な実行はスキップされます。エラーが見つからなかった場合は、空のレスポンスが返されます。検証で不合格になると、レスポンス内のエラー メッセージに障害点が示されます。

validate_only は、一般的なポリシー違反について広告をテストする場合に特に役立ちます。特定の単語、句読点、大文字、長さなどのポリシーに違反している広告は、自動的に不承認となります。不正な広告が 1 つでも、バッチ全体が失敗する可能性があります。validate_only リクエスト内で新しい広告をテストすれば、そのような違反が見つかる場合があります。実際の動作については、ポリシー違反エラーを処理するコードサンプルを参照してください。

オブジェクトと掲載結果の統計情報を取得する

GoogleAdsService は、オブジェクトとパフォーマンス統計情報を取得するための単一の統合サービスです。

GoogleAdsService に対するすべての Search リクエストと SearchStream リクエストには、クエリ対象のリソース、取得するリソース属性とパフォーマンス指標、リクエストのフィルタリングに使用する述語、パフォーマンス統計情報をさらに細かく分類するセグメントを指定するクエリが必要です。クエリ形式の詳細については、Google 広告クエリ言語ガイドをご覧ください。

メタデータの取得

GoogleAdsFieldService は、リソースで使用可能な属性やそのデータ型など、Google Ads API のリソースに関するメタデータを取得します。

このサービスは、GoogleAdsService に対するクエリの作成に必要な情報を提供します。GoogleAdsFieldService から返される情報は、フィールド リファレンス ドキュメントでもご覧いただけます。