Getters de tipo e serviço

A busca de referências para 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 a alternância de contexto com frequência 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 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 em 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 de código seja alterada.

Este é 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 v11 version of GoogleAdsService will
# be returned.
client = GoogleAdsClient.load_from_storage(version="v11")
googleads_service = client.get_service("GoogleAdsService")

Aqui está um exemplo de como usar o método get_type para recuperar uma instância do Campaign.

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage(version="v11")
campaign = client.get_type("Campaign")

Enums

Embora você possa usar o método get_type para recuperar Enums, cada instância de GoogleAdsClient também tem um atributo enums que carrega dinamicamente Enums usando o mesmo mecanismo que o método get_type. O objetivo dessa interface é ser mais simples e fácil de ler do que usar o get_type:

client = GoogleAdsClient.load_from_storage(version=v11)

campaign = client.get_type("Campaign")
campaign.status = client.enums.CampaignStatusEnum.PAUSED

Os campos do objeto proto que são enumerações são representados em Python pelo tipo enum nativo. Isso significa que é possível ler facilmente o valor do membro. Como trabalhar 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, como mostrado acima. 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 as enums é diferente dependendo da configuração de use_proto_plus definida como true ou false. Para ver 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 v11 possa ser a versão mais recente, as versões anteriores continuarão acessíveis até o pôr do sol. A biblioteca incluirá classes proto de mensagem separadas que correspondam a cada versão da API ativa. 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:

client = GoogleAdsService.load_from_storage(version="/google-ads/api/reference/rpc/v11/")
# The Campaign instance will be from the v11 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 v11 version of the GoogleAdsService.
googleads_service = client.get_service(
  "GoogleAdsService",
  version="v11"
)

client = GoogleAdsService.load_from_storage(version="v11")
# This will load the v9 version of a Campaign.
campaign = client.get_type("Campaign", version="v9")

Se nenhum parâmetro de palavra-chave version for fornecido, a biblioteca usará por padrão a versão mais recente. Veja uma lista atualizada das versões mais recentes e de outras versões disponíveis na seção de navegação à esquerda da documentação Referência da API.