Buscar referências a todas as várias classes proto necessárias para usar a API em Python pode ser detalhado e exige que você tenha uma compreensão intrínseca da API ou mude de contexto com frequência para referenciar os protos ou a documentação.
Os métodos get_service e get_type do cliente
Esses dois métodos getter permitem recuperar 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/, 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ão é gerado. Por isso, é recomendável usar esses métodos em vez de importar os objetos diretamente, caso a estrutura da base de código mude.
O exemplo a seguir mostra como usar o método get_service para recuperar uma
instância do cliente GoogleAdsService
(ou um GoogleAdsServiceAsyncClient assíncrono em google-ads v28.4.0 e
depois transmitindo is_async=True):
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 v25 version of GoogleAdsService will
# be returned.
client = GoogleAdsClient.load_from_storage(version="v25")
googleads_service = client.get_service("GoogleAdsService")
# Supported in google-ads v28.4.0 and later: retrieve an async service client.
googleads_async_service = client.get_service("GoogleAdsService", is_async=True)
O exemplo a seguir mostra 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="v25")
campaign = client.get_type("Campaign")
Tipos enumerados
Embora seja possível usar o método get_type para recuperar enums, cada
instância GoogleAdsClient também tem um atributo enums que carrega dinamicamente
enums usando o mesmo mecanismo do método get_type. Essa interface é mais simples e fácil de ler do que usar get_type:
from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage(version="v25")
campaign = client.get_type("Campaign")
campaign.status = client.enums.CampaignStatusEnum.PAUSED
Os campos de objetos proto que são enums são representados em Python pelo tipo
enum integrado. Isso significa que você pode ler o valor do membro
diretamente. Trabalhando com a instância campaign do exemplo anterior em um
REPL 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 do enum. Você pode acessar essas informações usando o atributo name:
>>> print(campaign.status.name)
'PAUSED'
>>> type(campaign.status.name)
<class 'str'>
A interação com enums é diferente dependendo se você tem a configuração
use_proto_plus
definida como true ou false. Para detalhes sobre as duas interfaces, consulte
a documentação de mensagens protobuf.
Controle de versões
Várias versões da API são mantidas ao mesmo tempo. Embora v25 seja a versão mais recente, as versões anteriores ainda estarão acessíveis até serem desativadas. A biblioteca inclui classes de mensagens proto separadas que correspondem a cada versão ativa da API. Para acessar uma classe de mensagem
de uma versão específica, forneça o parâmetro de palavra-chave version ao inicializar
um cliente para que ele sempre retorne uma instância dessa versão:
from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage(version="v25")
# The Campaign instance will be from the v25 version of the API.
campaign = client.get_type("Campaign")
Se você não especificar um version ao inicializar o cliente, poderá especificar
a versão por chamada ao chamar os métodos get_service e get_type.
Se version for definido ao inicializar GoogleAdsClient, ele vai substituir
qualquer argumento version transmitido para get_service ou get_type:
from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage()
# This loads the v25 version of the GoogleAdsService.
googleads_service = client.get_service(
"GoogleAdsService", version="v25"
)
# This loads a specific supported API version (such as v23) of a Campaign.
campaign = client.get_type("Campaign", version="v23")
Se nenhum parâmetro de palavra-chave version for fornecido, a biblioteca vai usar a
versão mais recente da API compatível com o pacote google-ads instalado
("v25" na versão mais recente). As versões secundárias da API (como v25.1) são acessadas usando a string da versão principal (version="v25"). 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.