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

Como o campo operations de uma solicitação de mutação é repetido, uma única solicitação pode conter várias operações (até 10.000 por solicitação) para esse tipo de recurso. Por padrão, todas as operações na solicitação são executadas de forma atômica, a menos que você defina partial_failure 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 de recursos temporários ou referências cruzadas:as operações em uma chamada de mutação específica do recurso são processadas de forma independente. Não é possível atribuir IDs negativos temporários (como customers/CUSTOMER_ID/campaigns/-1) ou referenciar entidades recém-criadas de outras operações na mesma solicitação.

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 operações dependentes, use GoogleAdsService.Mutate.

Diferenças específicas da versão

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

• Serviços de meta de ciclo de vida:na v25 e em versões mais recentes, todas as metas de ciclo de vida, incluindo aquisição de novos clientes (new_customer_acquisition_goal_settings), retenção de clientes (retention_goal_settings) e retenção de fidelidade (loyalty_retention_goal_settings), são modificadas por GoalService.MutateGoals e CampaignGoalConfigService.MutateCampaignGoalConfigs usando um campo operations repetido padrão. Isso substitui CustomerLifecycleGoalService.ConfigureCustomerLifecycleGoals e CampaignLifecycleGoalService.ConfigureCampaignLifecycleGoals, que são usados para aquisição de novos clientes na v24 e em versões anteriores e aceitam um campo operation singular.
• Campos de data e hora da campanha:ao criar ou atualizar um Campaign, a v23 e versões mais recentes usam start_date_time e end_date_time (yyyy-MM-dd HH:mm:ss), substituindo os campos start_date e end_date, que só têm data e eram usados na v22.
• Mutabilidade da atestação de conteúdo sintético:embora Asset.synthetic_content_info e Ad.synthetic_content_info apareçam no esquema da v22 e versões mais recentes, os campos synthetic_content_info.advertiser_attestation.status e synthetic_content_info.advertiser_attestation.source só são mutáveis na v23 e versões mais recentes (system_attestation é sempre OUTPUT_ONLY). A tentativa de mudar os subcampos advertiser_attestation na v22 retorna um erro de campo imutável ("The field attempted to be mutated is immutable" ou "Field cannot be set").