Como alterar e inspecionar objetos

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

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

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

Alterar objetos

Cada serviço específico ao tipo de recurso terá um método mut que aceita uma solicitação de mutaçã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 precisam ser retornados após a mutação.

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

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

Operações

Um objeto de operação como CampaignOperation permite especificar a ação que você quer executar em um único recurso definindo o campo operation. Este é um campo oneof com os atributos a seguir e 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 é definido, você também precisa definir a update_mask da operação. Ela 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 gera o update_mask, 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

Uma única operação só pode criar, atualizar ou remover um único recurso, mas uma única solicitação de mutação pode conter várias operações. Combine as operações em uma única solicitação de mutação em vez de enviar várias solicitações de mutação, cada uma contendo uma única operação.

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

Respostas da modificação

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

Erros de mutação

As operações em uma determinada solicitação de modificação só serão aplicadas à sua conta do Google Ads se todas as operações da solicitação forem bem-sucedidas. Confira o guia de erros comuns para ver uma lista de erros comuns e saber como resolvê-los.

Como inspecionar objetos com get (descontinuado)

Além de alterar objetos, cada serviço específico ao tipo de recurso 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.

Os métodos get são uma conveniência da API Google Ads que facilita 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, o app não pode usar métodos get para recuperar objetos para processamento ou geração de relatórios. Em vez disso, use GoogleAdsService, já que ele permite recuperar apenas atributos específicos de objetos, oferece suporte à recuperação de métricas de desempenho e permite o streaming em grandes conjuntos de resultados. Se o app enviar um grande número de solicitações de recebimento, poderá haver limites de taxa.