Il recupero dei riferimenti a tutte le varie classi proto necessarie per utilizzare l'API in Python può essere dettagliato e richiede una comprensione intrinseca dell'API o un frequente cambio di contesto per fare riferimento ai proto o alla documentazione.
I metodi get_service e get_type del client
Questi due metodi getter ti consentono di recuperare qualsiasi oggetto di servizio o tipo nell'API. Il metodo get_service viene utilizzato per recuperare i client di servizio. get_type viene utilizzato per qualsiasi altro oggetto. Le classi client di servizio sono definite nel codice nel percorso della versione google/ads/googleads/v*/services/ e tutti i tipi sono definiti nelle varie categorie di oggetti google/ads/googleads/v*/common|enums|errors|resources|services/types/. Tutto il codice nella directory della versione viene generato, quindi è consigliabile utilizzare questi metodi anziché importare direttamente gli oggetti, nel caso in cui la struttura del codebase cambi.
L'esempio seguente mostra come utilizzare il metodo get_service per recuperare un'istanza del client GoogleAdsService (o un GoogleAdsServiceAsyncClient asincrono in google-ads v28.4.0 e versioni successive passando 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)
L'esempio seguente mostra come utilizzare il metodo get_type per recuperare un'istanza Campaign:
from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage(version="v26")
campaign = client.get_type("Campaign")
Enum
Sebbene sia possibile utilizzare il metodo get_type per recuperare gli enum, ogni istanza GoogleAdsClient ha anche un attributo enums che carica dinamicamente gli enum utilizzando lo stesso meccanismo del metodo get_type. Questa interfaccia è più semplice e facile da leggere rispetto all'utilizzo di 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
I campi degli oggetti proto che sono enum sono rappresentati in Python dal tipo enum integrato. Ciò significa che puoi leggere direttamente il valore del membro. Utilizzo dell'istanza campaign dell'esempio precedente in un REPL Python:
>>> print(campaign.status)
CampaignStatus.PAUSED
>>> type(campaign.status)
<enum 'CampaignStatus'>
>>> print(campaign.status.value)
3
A volte è utile conoscere il nome del campo che corrisponde al valore enum. Puoi accedere a queste informazioni utilizzando l'attributo name:
>>> print(campaign.status.name)
'PAUSED'
>>> type(campaign.status.name)
<class 'str'>
L'interazione con gli enum è diversa a seconda che la configurazione
use_proto_plus
sia impostata su true o false. Per maggiori dettagli sulle due interfacce, consulta la documentazione sui messaggi protobuf.
Controllo delle versioni
Vengono gestite più versioni dell'API contemporaneamente. Sebbene v26 sia l'ultima versione, le versioni precedenti sono ancora accessibili fino alla loro disattivazione. La libreria include classi di messaggi proto separate che corrispondono a ogni versione attiva dell'API. Per accedere a una classe di messaggi per una versione specifica, fornisci il parametro della parola chiave version durante l'inizializzazione di un client in modo che restituisca sempre un'istanza della versione specificata:
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 non specifichi un version durante l'inizializzazione del client, puoi specificare la versione per chiamata quando chiami i metodi get_service e get_type (tieni presente che se version è impostato durante l'inizializzazione di GoogleAdsClient, esegue l'override di qualsiasi argomento version passato a get_service o 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 non viene fornito alcun parametro della parola chiave version, la libreria utilizza per impostazione predefinita la versione dell'API più recente supportata dal pacchetto google-ads installato ("v26" nell'ultima release). Tieni presente che alle release secondarie dell'API (come v25.1) si accede utilizzando la stringa della versione principale (version="v25"). Un elenco aggiornato delle versioni più recenti e di altre versioni disponibili è disponibile nella sezione di navigazione a sinistra della documentazione di riferimento dell'API (API Reference).