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