Getters de serviço e tipo

Buscar referências a todas as várias classes de 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 que alterne frequentemente o contexto para consultar os protos ou a documentação.

Os métodos get_service e get_type do cliente

Esses dois métodos getter permitem recuperar qualquer objeto de serviço ou 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 objeto google/ads/googleads/v*/common|enums|errors|resources|services/types/. Todo o código no diretório de versão é 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 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 no google-ads v28.4.0 e posterior 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 v26 version of GoogleAdsService will
# be returned.
client = GoogleAdsClient.load_from_storage(version="v26")
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="v26")
campaign = client.get_type("Campaign")

Tipos enumerados

Embora seja possível usar o método get_type para recuperar tipos enumerados, cada instância de GoogleAdsClient também tem um atributo enums que carrega dinamicamente tipos enumerados 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="v26")

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

Os campos de objeto proto que são tipos enumerados são representados em Python pelo tipo integrado enum. Isso significa que você pode ler o valor do membro diretamente. Trabalhando com a instância campaign do exemplo anterior em um REPL 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 do tipo enumerado. 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 tipos enumerados é diferente dependendo se a configuração use_proto_plus está definida como true ou false. Para mais detalhes sobre as duas interfaces, consulte a documentação de mensagens do protobuf.

Controle de versões

Várias versões da API são mantidas ao mesmo tempo. Embora v26 seja a versão mais recente, as versões anteriores ainda estã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 para 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="v26")
# The Campaign instance will be from the v26 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 v26 version of the GoogleAdsService.
googleads_service = client.get_service(
    "GoogleAdsService", version="v26"
)

# 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 usará como padrão a versão mais recente da API compatível com o pacote google-ads instalado ("v26" 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 de outras versões disponíveis pode ser encontrada na seção de navegação à esquerda da documentação de referência da API.