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

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

変更エンドポイント

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

  • 作成（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 呼び出しでは単一のリソースタイプのみが受け入れられるため、親リソース（customers/CUSTOMER_ID/campaigns/-1 など）に一時的な負の ID を割り当てて、同じリクエストで異なるタイプの子リソース（AdGroup など）から参照することはできません。（同じリソース タイプ内の自己参照一時 ID は、AdGroupCriterion リスティング グループや AssetGroupListingGroupFilter ノードなどの階層ツリーでサポートされています）。

単一のリクエストで複数のリソースタイプを変更する必要がある場合や、異なるリソースタイプ間で一時リソース名を参照する場合は、代わりに 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 を置き換えるものです。
前へ
概要
次へ
一括変更