Conforme discutido no guia da estrutura da API, cada recurso de nível superior na Google Ads API 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 vai 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 a
tipos de recurso.
Alterar objetos
Cada serviço específico ao tipo de recurso tem um método mutate que aceita uma solicitação desse tipo. Essa solicitação consiste em:
- 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_typeindica o tipo de resposta preferencial.
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. Esse campo é um oneof, que consiste nos 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 está definido, você também precisa definir oupdate_maskda 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 um método auxiliar que gera oupdate_maskpara você, conforme demonstrado em 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 à solicitação: uma com create definido e outra com remove definido.
Operações em lote
Embora uma única operação possa criar, atualizar ou remover um único recurso, uma única solicitação mutate pode conter várias operações. Combine suas operações em uma única solicitação mutate em vez de enviar várias solicitações mutate com uma única operação.
Por exemplo, se você quiser criar dez campanhas, envie um único MutateCampaignsRequest com dez objetos CampaignOperation.
Respostas da modificação
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 conteria apenas os campos mutáveis na campanha. Em seguida, 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 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 do 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 um único atributo resource_name.
Os métodos "get" são uma conveniência da API Google Ads para facilitar a recuperação de todos os atributos de um único objeto. Embora essa seja uma ótima ferramenta para
aprender sobre 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, já que ele permite recuperar apenas
atributos específicos de objetos, é compatível com a recuperação de métricas de desempenho e
permite fazer streaming por meio de grandes conjuntos de resultados. Se o app enviar um grande
número de solicitações GET, poderá ocorrer a limitação de taxa.