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