A busca de referências a todas as várias classes proto necessárias para usar a API no Python pode ser detalhada e exige que você tenha uma compreensão intrínseca da API ou alterne contextos frequentemente para fazer referência aos protos ou à documentação.
Os métodos get_service
e get_type
do cliente
Esses dois métodos getter permitem que você recupere qualquer serviço ou objeto de tipo na API. O método get_service
é usado para recuperar clientes de serviço. get_type
é usado para qualquer outro objeto. As classes de cliente de serviço são definidas no código
no caminho da versão google/ads/googleads/v*/services/services/
, e todos
os tipos são definidos nas várias categorias de objetos,
google/ads/googleads/v*/common|enums|errors|resources|services/types/
.
Todo o código abaixo do diretório de versões é gerado. Portanto, é uma prática
recomendada usar esses métodos em vez de importar os objetos diretamente, caso a
estrutura da base do código mude.
Confira um exemplo de como usar o método get_service
para recuperar uma instância
do cliente GoogleAdsService
.
from google.ads.googleads.client import GoogleAdsClient
# "load_from_storage" loads your API credentials from disk so they
# can be used for service initialization. Providing the optional `version`
# parameter means that the v17 version of GoogleAdsService will
# be returned.
client = GoogleAdsClient.load_from_storage(version="v17")
googleads_service = client.get_service("GoogleAdsService")
Confira um exemplo de como usar o método get_type
para recuperar uma
instância de Campaign
.
from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage(version="v17")
campaign = client.get_type("Campaign")
Tipos enumerados
Embora você possa usar o método get_type
para recuperar tipos enumerados, cada
instância de GoogleAdsClient
também tem um atributo enums
que carrega dinamicamente
os tipos enumerados usando o mesmo mecanismo que o método get_type
. Essa interface
é mais simples e fácil de ler do que usar get_type
:
client = GoogleAdsClient.load_from_storage(version=v17)
campaign = client.get_type("Campaign")
campaign.status = client.enums.CampaignStatusEnum.PAUSED
Os campos de objetos Proto que são enumerados são representados em Python pelo tipo
enum nativo. Isso significa que você
pode ler facilmente o valor do membro. Trabalhando com a instância campaign
do exemplo anterior em uma réplica do Python:
>>> print(campaign.status)
CampaignStatus.PAUSED
>>> type(campaign.status)
<enum 'CampaignStatus'>
>>> print(campaign.status.value)
3
Às vezes, é útil saber o nome do campo que corresponde ao valor de enumeração, conforme mostrado acima. Acesse essas informações usando o atributo
name
:
>>> print(campaign.status.name)
'PAUSED'
>>> type(campaign.status.name)
<class 'str'>
A interação com tipos enumerados é diferente dependendo da configuração
use_proto_plus
definida como true
ou false
. Para detalhes sobre as duas interfaces, consulte
a documentação de mensagens protobuf (em inglês).
Controle de versões
Várias versões da API são mantidas ao mesmo tempo. Embora
v17
possa ser a versão mais recente, as versões anteriores ainda
podem ser acessadas até serem desativadas. A biblioteca vai incluir classes de mensagens proto
separadas que correspondem a cada versão ativa da API. Para acessar uma classe de mensagem para uma versão específica, forneça o parâmetro de palavra-chave version
ao inicializar um cliente para que ele sempre retorne instâncias dessa versão:
client = GoogleAdsService.load_from_storage(version="/google-ads/api/reference/rpc/v17/")
# The Campaign instance will be from the v17 version of the API.
campaign = client.get_type("Campaign")
Também é possível especificar a versão ao chamar os métodos get_service
e
get_type
. Isso substitui a versão fornecida ao inicializar o cliente:
client = GoogleAdsService.load_from_storage()
# This will load the v17 version of the GoogleAdsService.
googleads_service = client.get_service(
"GoogleAdsService", version="v17")
client = GoogleAdsService.load_from_storage(version="v17")
# This will load the v15 version of a Campaign.
campaign = client.get_type("Campaign", version="v15")
Se nenhum parâmetro de palavra-chave version
for fornecido, a biblioteca usará por padrão a versão mais recente. Uma lista atualizada das versões mais recentes e outras disponíveis pode ser encontrada na seção de navegação à esquerda da documentação de Referência da API.