Conforme descrito 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:
- Modificar instâncias do recurso
- Como recuperar uma única instância do recurso para inspeção
Este guia vai usar CampaignService
para
demonstrar como modificar e inspecionar objetos Campaign
, mas os mesmos conceitos se aplicam a todos os outros serviços específicos a
tipos de recursos.
Mudança de objetos
Cada serviço específico ao tipo de recurso terá um método mutate que aceita uma solicitação desse tipo. Essa solicitação consiste em:
- Um
customerId
- Uma coleção 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 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 é oneof e 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 é definido, você também precisa definir oupdate_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 oupdate_mask
para você, 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
à solicitação: uma com create
e outra com remove
definidos.
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 mutate em vez de enviar várias solicitações mutate que, cada uma delas, contém 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 modificação. Por exemplo, se MUTABLE_RESOURCE
fosse especificado, a resposta conteria apenas os campos mutáveis na campanha. Depois, você pode fazer modificações de continuidade 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 os 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 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 usar a API ou inspecionar um objeto individual para fins de depuração ou educação, seu app não pode usar métodos get a fim de recuperar objetos para processamento ou geração de relatórios. Em vez disso, use GoogleAdsService
, porque ele permite extrair apenas
atributos específicos de objetos, recuperar métricas de desempenho e
permitir o streaming por grandes conjuntos de resultados. Se o app enviar um grande
número de solicitações GET, poderá ocorrer a limitação de taxa.