Mudar objetos

Conforme discutido no guia de estrutura da API, cada recurso de nível superior na API Google Ads tem um serviço específico do tipo de recurso correspondente que oferece suporte à modificação de instâncias do recurso. Também é possível usar GoogleAdsService.Mutate para modificar vários tipos de recursos de forma atômica em uma única solicitação.

Este guia usa CampaignService para demonstrar a modificação de objetos Campaign, mas os mesmos conceitos se aplicam a todos os outros serviços específicos do tipo de recurso.

Solicitações de modificação

Cada serviço específico do tipo de recurso tem um método mutate que aceita uma solicitação de modificação. Essa solicitação consiste em:

• Um customer_id (ou customerId em URLs REST)
• Uma coleção de operations
• Configurações de execução opcionais, como partial_failure, validate_only e response_content_type (que determina se o recurso mutável ou apenas o nome do recurso é retornado após a modificação)

Por exemplo, o MutateCampaigns método de CampaignService aceita um MutateCampaignsRequest que consiste em:

• Um customer_id
• Uma coleção de objetos CampaignOperation (operations)
• Configurações de execução opcionais (partial_failure, validate_only e response_content_type que indicam o tipo de resposta preferido)

Operações

Um objeto de operação, como um CampaignOperation, permite especificar a ação que você quer realizar em um único recurso definindo o campo operation. Esse campo é um oneof campo que consiste nos seguintes atributos:

create

Cria uma nova instância do recurso.

update

Atualiza o recurso para corresponder aos atributos do recurso update. Quando esse campo é definido, você também precisa definir a update_mask da operação, que informa à API Google Ads quais atributos modificar durante a operação de atualização. Cada biblioteca de cliente inclui um utilitário de máscara de campo ou um método auxiliar que gera o update_mask para você.

remove

Remove o recurso especificado pela string de nome do recurso (por exemplo, customers/1234567890/campaigns/987654321).

Como o campo operation é um oneof, não é possível usar uma única operação para modificar vários objetos. Por exemplo, se você quiser criar uma campanha e remover outra, adicione duas instâncias de CampaignOperation à sua solicitação: uma com create definida e outra com remove definida.

Operações em lote

Embora uma única operação só possa criar, atualizar ou remover um único recurso, uma única solicitação de modificação pode conter várias operações. Combine suas operações em uma única solicitação de modificação em vez de enviar várias solicitações de modificação que contenham uma única operação.

Por exemplo, se você quiser criar dez campanhas, envie uma única MutateCampaignsRequest que tenha dez objetos CampaignOperation. Para agrupar operações em diferentes tipos de recursos em uma única solicitação, use GoogleAdsService.Mutate ou recursos de modificação.

Respostas de modificação

O que é retornado na resposta depende do que foi enviado no response_content_type campo da solicitação de modificação. Por exemplo, se MUTABLE_RESOURCE for especificado, a resposta vai conter o resource_name do recurso e os campos mutáveis da campanha em campaign. Por padrão (RESOURCE_NAME_ONLY), apenas o resource_name é preenchido em cada MutateCampaignResult.

Erros de modificação

Por padrão (partial_failure = false), as operações em uma solicitação de modificação são aplicadas à sua conta do Google Ads somente se todas as operações na solicitação forem bem-sucedidas. Se alguma operação falhar, toda a solicitação será revertida. Para solicitações de modificação que oferecem suporte a falhas parciais (aquelas com um campo partial_failure na mensagem de solicitação), a definição de partial_failure = true confirma operações válidas, enquanto as operações com falha retornam erros específicos da operação no campo partial_failure_error da resposta. Consulte o guia de falhas parciais e o guia de erros comuns para mais detalhes sobre como lidar com erros.

Controlar alterações

Para acompanhar as mudanças feitas nos objetos da sua conta do Google Ads ou para recuperar o estado atual dos objetos, use os recursos change_status e change_event.

• change_status fornece um resumo de quais recursos foram alterados em um determinado período.
• change_event fornece um histórico detalhado das mudanças, incluindo os valores antigos e novos dos campos alterados.

Para consultar esses recursos, use o GoogleAdsService.SearchStream ou GoogleAdsService.Search método. Saiba mais sobre streaming de relatórios usando GoogleAdsService.