API の構造

ondemand_video 動画: 2019 年のワークショップのサービスとリソースについての講演を見る

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

オブジェクト階層

Google 広告アカウントは、オブジェクトの階層構造と考えることができます。

• アカウントの最上位のリソースは、 お客様によって異なります。

• 各顧客には 1 つ以上のアクティブな キャンペーン。

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

• 広告グループの広告は、お客様が掲載している できます。広告ごとに設定できる広告グループ広告は 1 つのみのアプリ キャンペーンを除く 各広告グループには 1 つ以上の広告グループの広告が含まれます。

1 つ以上の AdGroupCriterion を追加できます。 または CampaignCriterion を広告グループまたは あります広告をトリガーする方法を定義する条件を表します。

条件タイプは多数ありますが、 キーワード、年齢層、地域などですキャンペーンで定義されている条件 キャンペーン内のすべてのリソースに影響します。また、 キャンペーン全体の予算と期間

最後に、拡張機能を キャンペーン単位または広告グループ単位で適用できます拡張機能を使用すると、 電話番号、住所、プロモーションなどの情報を広告に追加できます。

リソース

リソースは、Google 広告アカウント内のエンティティを表します。Campaign と AdGroup の 2 つの例 できます。

オブジェクト ID

Google 広告のすべてのオブジェクトは、それぞれ独自の ID で識別されます。これらの ID の一部は すべての Google 広告アカウントでグローバルに一意である一方、他のアカウント内でのみ一意である 限られた範囲に 移動できます

これらの ID ルールは、Google 広告のローカル ストレージを設計するときに役立ちます。 説明します。

一部のオブジェクトは複数のエンティティ タイプで使用できます。その場合、オブジェクトには 内容を説明する type フィールドが含まれています。たとえば AdGroupAd はテキスト広告 ホテル広告、ローカル広告がありますこの値は、 AdGroupAd.ad.type フィールドであり、 AdType 列挙型。

リソース名

各リソースは resource_name 文字列で一意に識別されます。 リソースとその親をパスに連結します。たとえば、 リソース名の形式は次のとおりです。

customers/customer_id/campaigns/campaign_id

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

customers/1234567/campaigns/987654

サービス

本サービスでは、Google 広告のエンティティの取得と変更を行うことができます。データ アナリストが 変更、オブジェクトと統計情報の取得、メタデータの取得 提供します。

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

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

サービスの例:

• CustomerService（変更用） ユーザーです。

• CampaignService（変更用） キャンペーン。

• AdGroupService: 広告グループを変更します。

各 mutate リクエストには、対応する operation オブジェクトを含める必要があります。対象 たとえば、CampaignService.MutateCampaigns メソッドは 1 つ以上の CampaignOperation のインスタンス。詳しくは、 オブジェクトの変更と検査に 説明します。

同時変換

Google 広告 オブジェクトには、複数のソースから同時並行で変更を加えることはできません。この 複数のユーザーが同じオブジェクトを更新している場合に、 複数の API キーを使用して Google 広告オブジェクトを並行して変更する場合は、 説明します。これには、同じグループ内の複数のスレッドからオブジェクトを更新することも含まれます。 別のアプリケーション（たとえば、自分のアプリとアプリケーションが Google 広告 UI セッションなど）が含まれます。

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

非同期の変更と同期の変更

Google Ads API の変更メソッドは同期的です。API 呼び出しはレスポンスのみを返す 変更後にレスポンスが返されるまで待機する必要があります。 リクエストできます。このアプローチはコーディングは比較的簡単ですが、 ロード バランシングに悪影響を及ぼし、プロセスが 呼び出しが完了するまで待ちます。

もう 1 つの方法は、 BatchJobService - 次のロールのバッチを実行します。 オペレーションを実行できます。一度 送信されると、Google Ads API サーバーは処理を非同期的に実行します。 他のオペレーションを実行するためにプロセスが解放されます定期的に ジョブ ステータスが表示されます。

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

変換の検証

ほとんどの変更リクエストは、実際に呼び出しを実行しなくても検証できる 比較できます。パラメータの欠落や誤りの有無についてリクエストをテストできます。 値のみを取得することもできます。

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

validate_only は、一般的なポリシーに照らして広告をテストする場合に特に便利です。 できます。広告が以下のようなポリシーに違反している場合、広告は自動的に不承認になる 特定の単語、句読点、大文字アルファベットの使用方法、長さが不適切です。不適切な広告 1 個 バッチ全体が失敗する可能性がありますvalidate_only 内で新しい広告をテストする リクエストによって該当する違反が明らかになります。データを処理するには、 ポリシー違反のエラーを確認し、 見てみましょう。

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

GoogleAdsService は単一の統合エンドポイント オブジェクトとパフォーマンス統計情報を取得できます。

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

メタデータの取得

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

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