API 構造ガイドで説明したように、Google Ads API の各最上位リソースには、対応するリソースタイプ固有のサービスがあります。次のサービスがサポートされています。
- リソースのインスタンスを変更する
- 検査用にリソースの単一インスタンスを取得する
このガイドでは、CampaignService を使用して Campaign オブジェクトの変更と検査について説明しますが、他のすべてのリソースタイプ固有のサービスに同じコンセプトが適用されます。
オブジェクトの変更
リソースタイプ固有のサービスごとに、変更リクエストを受け入れる mutate メソッドがあります。このリクエストを構成する要素は次のとおりです。
- A:
customerId - オペレーションの集合
- レスポンス コンテンツ タイプの設定。ミューテーション後に可変リソースまたはリソース名のみを返すかどうかを決定します。
たとえば、CampaignService の MutateCampaigns メソッドは、以下で構成される MutateCampaignsRequest を受け取ります。
- A:
customerId CampaignOperationオブジェクトのコレクション- 優先するレスポンス タイプを示す
response_content_typeフィールド。
運用
CampaignOperation などのオペレーション オブジェクトでは、operation フィールドを設定して、単一のリソースで実行するアクションを指定できます。このフィールドは、タイプがリソースタイプである次の属性で構成される oneof フィールドです。
create- リソースの新しいインスタンスを作成します。
updateupdateリソースの属性と一致するようにリソースを更新します。このフィールドを設定する場合は、オペレーションのupdate_maskも設定する必要があります。これにより、更新オペレーション中に変更する属性が Google Ads API に伝えられます。各クライアント ライブラリには、Google のクライアント ライブラリに示されているように、update_maskを生成するユーティリティまたはヘルパー メソッドがあります。remove- リソースを削除します。
operation フィールドは oneof フィールドであるため、1 回のオペレーションで複数のオブジェクトを変更することはできません。たとえば、あるキャンペーンを作成して別のキャンペーンを削除する場合は、CampaignOperation の 2 つのインスタンスをリクエストに追加します（1 つは create を設定し、もう 1 つは remove を設定します）。
バッチ処理
単一のオペレーションでは単一のリソースの作成、更新、削除しかできませんが、単一の mutate リクエストには複数のオペレーションを含めることができます。それぞれに 1 つのオペレーションが含まれる複数の変更リクエストを送信するのではなく、オペレーションを 1 つの変更リクエストにまとめる必要があります。
たとえば、10 個のキャンペーンを作成する場合は、10 個の CampaignOperation オブジェクトを含む 1 つの MutateCampaignsRequest を送信します。
mutate レスポンス
レスポンスで返される内容は、変更リクエストの response_content_type で送信された内容によって異なります。たとえば、MUTABLE_RESOURCE が指定されていた場合、レスポンスにはキャンペーンの可変フィールドのみが含まれます。そうすることで、再構成することなく、そのリソース オブジェクトに対してフォローアップ ミューテーションを行うことができます。
mutate エラー
特定の mutate リクエストのオペレーションは、リクエスト内のすべてのオペレーションが成功した場合にのみ Google 広告アカウントに適用されます。一般的なエラーのリストと対処方法については、一般的なエラーのガイドをご覧ください。
get によるオブジェクトの検査（非推奨）
オブジェクトの変更に加えて、リソースタイプ固有のサービスには、単一のリソースのすべての属性を取得する get メソッドもあります。このメソッドは、属性が resource_name のみの get リクエストを受け入れます。
get メソッドは、単一のオブジェクトのすべての属性を簡単に取得できるように、Google Ads API によって提供されます。これは、API の学習や、デバッグや教育などの目的で個々のオブジェクトの検査を行うための優れたツールですが、アプリで get メソッドを使って処理やレポート作成用のオブジェクトを取得することはできません。代わりに、GoogleAdsService を使用してください。これにより、オブジェクトの特定の属性のみの取得やパフォーマンス指標の取得が可能になり、大規模な結果セットをストリーミングできます。アプリが多数の get リクエストを送信すると、レート制限に達することがあります。