Como alterar e inspecionar objetos

Objetivo: entender como modificar e inspecionar objetos usando a API Google Ads.

Conforme discutido no Guia da estrutura da API, cada recurso de nível superior da API Google Ads tem um serviço específico para o tipo de recurso correspondente compatível com:

• Como modificar instâncias do recurso
• Como recuperar uma única instância do recurso para inspeção

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

Termo-chave: um recurso de nível superior é um recurso cujo nome não inclui um ponto (.). Por exemplo, Campaign é um recurso de nível superior, mas Campaign.NetworkSettings não é.

Mudança de objetos

Cada serviço específico ao tipo de recurso terá um método Transform que aceita uma solicitação de modificação. Essa solicitação consiste no seguinte:

• Um customerId
• Um conjunto de operações
• Uma configuração de tipo de conteúdo de resposta que determina se o recurso mutável ou apenas o nome do recurso precisa ser retornado após a mutação.

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

• Um customerId
• Uma coleção de objetos CampaignOperation
• O campo response_content_type, que indica o tipo de resposta preferido.

Operações

Um objeto de operação como CampaignOperation permite que você especifique a ação que quer executar em um único recurso ao definir o campo operation. Esse campo é um oneof, com os seguintes atributos, que são do tipo de recurso:

create

Cria uma nova instância do recurso.

update

Atualiza o recurso para corresponder aos atributos do recurso update. Quando esse campo está definido, você também precisa definir a update_mask da operação, que informa à API Google Ads quais atributos serão modificados durante a operação de atualização. Cada biblioteca cliente tem um método utilitário ou auxiliar que gerará o update_mask para você, conforme demonstrado nas nossas bibliotecas de cliente.

remove

Remove o recurso.

Como o campo operation é um campo 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 e outra com remove.

Operações em lote

Embora uma única operação possa criar, atualizar ou remover um único recurso, uma única solicitação "muta" pode conter várias operações. Você precisa combinar suas operações em uma única solicitação "mut" em vez de enviar várias solicitações que contêm uma única operação.

Por exemplo, se você quiser criar 10 campanhas, envie uma única MutateCampaignsRequest com dez objetos CampaignOperation.

Respostas mutáveis

O que é retornado na resposta depende do que foi enviado no response_content_type da solicitação de mutação. Por exemplo, se MUTABLE_RESOURCE foi especificado, a resposta conterá apenas os campos mutáveis na campanha. Depois, é possível fazer mutações de acompanhamento nesse objeto de recurso sem precisar reconstruí-lo.

Erros da transformação

As operações em uma determinada solicitação de mutação serão aplicadas à sua conta do Google Ads somente se todas as operações na solicitação forem bem-sucedidas. Consulte o guia de erros comuns para ver uma lista de erros comuns e como resolvê-los.

Aviso: o get será desativado na v10. Use search ou searchStream para recuperar objetos.

Como inspecionar objetos com get (descontinuado)

Além de alterar objetos, cada serviço específico ao tipo de recurso também tem um método get para recuperar todos os atributos de um único recurso. Esse método aceita uma solicitação get com o único atributo resource_name.

Importante: use get com moderação.

Os métodos get são uma conveniência da API Google Ads que facilitam a recuperação de todos os atributos de um único objeto. Embora essa seja uma ótima ferramenta para aprender a API ou inspecionar um objeto individual para fins de depuração ou educação, seu app não deve usar métodos get para recuperar objetos para processamento ou geração de relatórios. Em vez disso, use GoogleAdsService, porque ele permite recuperar apenas atributos específicos de objetos, aceita recuperar métricas de desempenho e permite fazer streaming por grandes conjuntos de resultados. Se o aplicativo enviar um grande número de solicitações get, é possível que você encontre limites de taxa.