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