La récupération des références à toutes les différentes classes proto requises pour utiliser l'API en Python peut être fastidieuse et nécessite une compréhension intrinsèque de l'API ou un changement de contexte fréquent pour référencer les protos ou la documentation.
Méthodes get_service et get_type du client
Ces deux méthodes getter vous permettent de récupérer n'importe quel objet de service ou de type dans l'API. La méthode get_service permet de récupérer les clients de service. get_type est utilisé pour tout autre objet. Les classes de client de service sont définies dans le code sous le chemin d'accès de version google/ads/googleads/v*/services/, et tous les types sont définis sous les différentes catégories d'objets google/ads/googleads/v*/common|enums|errors|resources|services/types/. Tout le code du répertoire de version est généré. Il est donc recommandé d'utiliser ces méthodes au lieu d'importer directement les objets, au cas où la structure de la codebase changerait.
L'exemple suivant montre comment utiliser la méthode get_service pour récupérer une instance du client GoogleAdsService (ou un GoogleAdsServiceAsyncClient asynchrone dans google-ads v28.4.0 et versions ultérieures en transmettant 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'exemple suivant montre comment utiliser la méthode get_type pour récupérer une instance Campaign :
from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage(version="v26")
campaign = client.get_type("Campaign")
Enums
Bien que vous puissiez utiliser la méthode get_type pour récupérer des énumérations, chaque instance GoogleAdsClient possède également un attribut enums qui charge dynamiquement les énumérations à l'aide du même mécanisme que la méthode get_type. Cette interface est plus simple et plus facile à lire que l'utilisation de 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
Les champs d'objet proto qui sont des énumérations sont représentés en Python par le type enum intégré. Cela signifie que vous pouvez lire directement la valeur du membre. Utilisation de l'instance campaign de l'exemple précédent dans un REPL Python :
>>> print(campaign.status)
CampaignStatus.PAUSED
>>> type(campaign.status)
<enum 'CampaignStatus'>
>>> print(campaign.status.value)
3
Il est parfois utile de connaître le nom du champ qui correspond à la valeur d'énumération. Vous pouvez accéder à ces informations à l'aide de l'attribut name :
>>> print(campaign.status.name)
'PAUSED'
>>> type(campaign.status.name)
<class 'str'>
L'interaction avec les énumérations diffère selon que la configuration use_proto_plus est définie sur true ou false. Pour en savoir plus sur les deux interfaces, consultez la documentation sur les messages protobuf.
Gestion des versions
Plusieurs versions de l'API sont gérées en même temps. Bien que v26 soit la dernière version, les versions antérieures restent accessibles jusqu'à leur abandon. La bibliothèque inclut des classes de messages proto distinctes qui correspondent à chaque version d'API active. Pour accéder à une classe de message pour une version spécifique, fournissez le paramètre de mot clé version lors de l'initialisation d'un client afin qu'il renvoie toujours une instance de cette version donnée :
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")
Si vous ne spécifiez pas de version lors de l'initialisation du client, vous pouvez spécifier la version par appel lors de l'appel des méthodes get_service et get_type (notez que si version est défini lors de l'initialisation de GoogleAdsClient, il remplace tout argument version transmis à 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")
Si aucun paramètre de mot clé version n'est fourni, la bibliothèque utilise par défaut la version d'API la plus élevée compatible avec votre package google-ads installé ("v26" dans la dernière version). Notez que les versions mineures de l'API (telles que v25.1) sont accessibles à l'aide de leur chaîne de version majeure (version="v25"). Vous trouverez une liste actualisée des dernières versions et des autres versions disponibles dans la section de navigation de gauche de la documentation de référence de l'API.