リソース サービス ミューテーション

リソース専用のサービスを使用することは、Google Ads API で単一のリソースタイプのエンティティを作成、更新、削除する最も直接的な方法です。

mutate エンドポイント

変更可能な各リソースには、対応するサービスとオペレーション タイプがあります。専用サービスを使用してリソースを変更するには、オペレーションの次のいずれかのフィールドに値を入力し、サービスの mutate エンドポイントに送信します。

  • 作成（create）: 作成する新しいリソース オブジェクト。
  • 更新（update）: 変更されたリソース オブジェクト。変更されたフィールドを指定する update_mask が付随します。
  • 削除（remove）: 削除するターゲット リソースの resource_name 文字列。

たとえば、新しい Campaign を作成するには、次の手順を完了します。

  1. 選択した属性を使用して Campaign オブジェクトを作成します。
  2. CampaignOperation の create フィールドに割り当てます。
  3. MutateCampaignsRequest でオペレーションを CampaignService.MutateCampaigns に送信します。

この同じパターンは、Google Ads API のすべてのリソース固有のサービスに適用されます。

次の REST JSON ペイロードは、CampaignService.MutateCampaigns へのリクエストを示しています。

{
  "customerId": "CUSTOMER_ID",
  "operations": [
    {
      "create": {
        "name": "Interplanetary Cruise #1",
        "advertisingChannelType": "SEARCH",
        "status": "PAUSED",
        "manualCpc": {},
        "campaignBudget": "customers/CUSTOMER_ID/campaignBudgets/BUDGET_ID",
        "containsEuPoliticalAdvertising": "DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING"
      }
    }
  ],
  "partialFailure": false,
  "validateOnly": false
}

複数のオペレーションと制限事項

ほとんどのリソース固有の変更リクエストは、繰り返し operations フィールドを受け入れるため、1 つのリクエストにそのリソースタイプに対する複数のオペレーションを含めることができます（リクエストあたり最大 10,000 オペレーション、AdGroupCriterionService.MutateAdGroupCriteria の場合は 20,000 オペレーション。CustomerService.MutateCustomer は単一の operation フィールドを受け入れます）。デフォルトでは、サービスが partial_failure をサポートし、true に設定されていない限り、リクエスト内のすべてのオペレーションがアトミックに実行されます。

ただし、個々のリソース サービスには 2 つの重要な制限があります。

  • 単一のリソースタイプ: リソース サービスへのリクエストは、その特定のサービスによって管理されているリソースのみを変更できます。
  • リソース間の仮 ID は使用できません。リソース固有の mutate 呼び出しは 1 つのリソースタイプのみを受け入れるため、親リソース（customers/CUSTOMER_ID/campaigns/-1 など）に仮の負の ID を割り当てて、同じリクエスト内の別のタイプの子リソース（AdGroup など）から参照することはできません。（同じリソースタイプ内の自己参照一時 ID は、AdGroupCriterion リスティング グループや AssetGroupListingGroupFilter ノードなどの階層ツリーでサポートされています）。

1 つのリクエストで複数のリソースタイプを変更する必要がある場合や、異なるリソースタイプ間で一時的なリソース名を参照する必要がある場合は、代わりに GoogleAdsService.Mutate を使用します。

バージョン固有の違い

リソースを変更する際は、サポートされている Google Ads API のバージョン間で次の違いに注意してください。

  • ライフサイクル目標サービス: 「ユーザー維持」目標は、標準の繰り返し operations フィールドを使用して、GoalService.MutateGoals（retention_goal_settings）と CampaignGoalConfigService.MutateCampaignGoalConfigs（campaign_retention_settings）を介して、サポートされているすべてのバージョンで変更されます。v25 以降では、新規顧客の獲得（new_customer_acquisition_goal_settings / campaign_new_customer_acquisition_settings）とリピート顧客の維持（loyalty_retention_goal_settings / campaign_loyalty_retention_settings）も GoalService.MutateGoals と CampaignGoalConfigService.MutateCampaignGoalConfigs を介して変更されます。これは、v23 と v24 で新規顧客の獲得に使用され、単一の operation フィールドを受け入れる CustomerLifecycleGoalService.ConfigureCustomerLifecycleGoals と CampaignLifecycleGoalService.ConfigureCampaignLifecycleGoals に代わるものです。
前へ
概要
次へ
一括変更