Como alterar e inspecionar objetos

Conforme discutido no guia da estrutura da API, cada recurso de nível superior da API Google Ads tem um serviço correspondente específico ao tipo de recurso que é 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 inspeção de objetos Campaign, mas os mesmos conceitos se aplicam a todos os outros serviços específicos a cada tipo de recurso.

Mudança de objetos

Cada serviço específico ao tipo de recurso terá um método mutate 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 precisa ser retornado 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 indicando o tipo de resposta preferencial.

Operações

Um objeto de operação, como CampaignOperation, permite especificar a ação que você quer realizar em um único recurso definindo o campo operation. Esse campo é um oneof, composto pelos seguintes atributos, cujo tipo é o tipo do 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 o update_mask da operação, que informa à API Google Ads quais atributos precisam ser modificados durante a operação de atualização. Cada biblioteca de cliente tem um utilitário ou método auxiliar que gera o update_mask, conforme demonstrado nas nossas bibliotecas de cliente.

remove

Remove o recurso.

Como o campo operation é 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 definidas.

Operações em lote

Embora uma única operação possa criar, atualizar ou remover apenas um recurso, uma única solicitação de mutação pode conter várias operações. Combine suas operações em uma única solicitação de mutação em vez de enviar várias solicitações, cada uma contendo uma única operação.

Por exemplo, se você quiser criar 10 campanhas, envie um único MutateCampaignsRequest com 10 objetos CampaignOperation.

Modificar respostas

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 fosse especificado, a resposta teria apenas os campos mutáveis na campanha. Depois, você pode fazer modificações de acompanhamento nesse objeto de recurso sem precisar reconstruí-lo.

Erros de modificação

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

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 que tenha resource_name como único atributo.

Os métodos get são uma conveniência oferecida pela API Google Ads para facilitar a recuperação de todos os atributos de um único objeto. Embora ela seja uma ótima ferramenta para aprender a usar a API ou inspecionar um objeto individual para fins de depuração ou educação, seu app não deve usar métodos get a fim de recuperar objetos para processamento ou geração de relatórios. Em vez disso, use GoogleAdsService, já que ele permite extrair apenas atributos específicos de objetos, aceita a recuperação de métricas de desempenho e permite o streaming em grandes conjuntos de resultados. Se o app envia um grande número de solicitações get, pode haver limitações de taxa.