Mutação do serviço de recurso

Usar o serviço dedicado de um recurso é a maneira mais direta de criar, atualizar ou remover entidades de um único tipo de recurso na API Google Ads.

Endpoints de mutação

Cada recurso mutável tem um serviço e um tipo de operação correspondentes. Para fazer uma mutação de um recurso usando o serviço dedicado, preencha um dos seguintes campos na operação e envie para o endpoint de mutação do serviço:

• Criar (create): um novo objeto de recurso a ser criado.
• Atualização (update): o objeto de recurso modificado, acompanhado de um update_mask que especifica os campos alterados.
• Remover (remove): a string resource_name do recurso de destino a ser removida.

Por exemplo, para criar um novo Campaign, siga estas etapas:

1. Construa um objeto Campaign com os atributos escolhidos.
2. Atribua-o ao campo create de um CampaignOperation.
3. Envie a operação em um MutateCampaignsRequest para CampaignService.MutateCampaigns.

Esse mesmo padrão se aplica a todos os serviços específicos de recursos na API Google Ads:

• AdGroup:transmita um AdGroupOperation para AdGroupService.MutateAdGroups.
• CampaignCriterion:transmita um CampaignCriterionOperation para CampaignCriterionService.MutateCampaignCriteria.

O payload JSON REST a seguir ilustra uma solicitação para 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
}

Várias operações e limitações

A maioria das solicitações de mutação específicas de recursos aceita um campo operations repetido. Assim, uma única solicitação pode conter várias operações para esse tipo de recurso (até 10.000 operações por solicitação ou 20.000 para AdGroupCriterionService.MutateAdGroupCriteria; CustomerService.MutateCustomer aceita um campo operation único). Por padrão, todas as operações na solicitação são executadas de forma atômica, a menos que o serviço ofereça suporte a partial_failure e você o defina como true.

No entanto, os serviços de recursos individuais têm duas limitações importantes:

• Tipo de recurso único:uma solicitação para um serviço de recursos só pode mudar recursos gerenciados por esse serviço específico.
• Sem IDs temporários entre recursos:como uma chamada de mutação específica de recurso aceita apenas um tipo de recurso, não é possível atribuir um ID negativo temporário a um recurso pai (como customers/CUSTOMER_ID/campaigns/-1) e fazer referência a ele em um recurso filho de um tipo diferente (como um AdGroup) na mesma solicitação. IDs temporários autorreferenciados no mesmo tipo de recurso são compatíveis com árvores hierárquicas, como grupos de listagem AdGroupCriterion e nós AssetGroupListingGroupFilter.

Se você precisar fazer mutações em vários tipos de recursos em uma única solicitação ou referenciar nomes de recursos temporários em diferentes tipos de recursos, use GoogleAdsService.Mutate.

Diferenças específicas da versão

Considere a seguinte diferença entre as versões compatíveis da API Google Ads ao fazer mutações de recursos:

• Serviços de meta de ciclo de vida:as metas de retenção de clientes são modificadas em todas as versões compatíveis por GoalService.MutateGoals (retention_goal_settings) e CampaignGoalConfigService.MutateCampaignGoalConfigs (campaign_retention_settings) usando um campo operations padrão repetido. Na v25 e em versões mais recentes, a aquisição de novos clientes (new_customer_acquisition_goal_settings / campaign_new_customer_acquisition_settings) e a retenção de fidelidade (loyalty_retention_goal_settings / campaign_loyalty_retention_settings) também são modificadas por GoalService.MutateGoals e CampaignGoalConfigService.MutateCampaignGoalConfigs. Isso substitui CustomerLifecycleGoalService.ConfigureCustomerLifecycleGoals e CampaignLifecycleGoalService.ConfigureCampaignLifecycleGoals, que são usados para aquisição de novos clientes nas versões 23 e 24 e aceitam um campo operation único.