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 modificar um recurso usando o serviço dedicado, preencha um dos seguintes campos na operação e envie-o ao endpoint de modificação do serviço:

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

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

1. Crie 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 singular). 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 modificar recursos gerenciados por esse serviço específico.
• Não há IDs temporários entre recursos: como uma chamada de mutação específica do 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 de autorreferência no mesmo tipo de recurso são compatíveis com árvores hierárquicas, como grupos de produtos anunciados AdGroupCriterion e nós AssetGroupListingGroupFilter.)

Se você precisar modificar 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

Ao modificar recursos, lembre-se da seguinte diferença entre as versões compatíveis da API Google Ads:

• Serviços de metas de ciclo de vida: as metas de retenção de clientes são modificadas em todas as versões compatíveis usando GoalService.MutateGoals (retention_goal_settings) e CampaignGoalConfigService.MutateCampaignGoalConfigs (campaign_retention_settings) com um campo operations repetido padrão. 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 único campo operation.