La récupération des références à toutes les classes de proto requises pour utiliser l'API en Python peut être détaillée 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.
Les méthodes get_service et get_type du client
Ces deux méthodes getter vous permettent de récupérer n'importe quel objet service ou 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 clients de service sont définies dans le code du chemin d'accès de la version google/ads/googleads/v*/services/services/, et tous les types sont définis dans les différentes catégories d'objets, google/ads/googleads/v*/common|enums|errors|resources|services/types/.
Tout le code situé sous le répertoire de version est généré. Il est donc recommandé d'utiliser ces méthodes plutôt que d'importer directement les objets, au cas où la structure du codebase change.
Voici un exemple d'utilisation de la méthode get_service pour récupérer une instance du client 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 v13 version of GoogleAdsService will
# be returned.
client = GoogleAdsClient.load_from_storage(version="v13")
googleads_service = client.get_service("GoogleAdsService")
Voici un exemple d'utilisation de 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="v13")
campaign = client.get_type("Campaign")
Enums
Bien que vous puissiez utiliser la méthode get_type pour récupérer les énumérations (enums), chaque instance GoogleAdsClient possède également un attribut enums qui charge les énumérations de manière dynamique à l'aide du même mécanisme que la méthode get_type. Cette interface est conçue pour être plus simple et plus facile à lire que l'utilisation de get_type :
client = GoogleAdsClient.load_from_storage(version=v13)
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 natif enum. Cela signifie que vous pouvez facilement lire la valeur du membre. Utilisation de l'instance campaign de l'exemple précédent dans un dépôt 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 correspondant à la valeur d'énumération, comme indiqué ci-dessus. 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 varie selon que la configuration de 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 v13 soit peut-être la dernière version, les versions antérieures restent accessibles jusqu'à leur abandon. La bibliothèque inclura des classes de messages proto distinctes correspondant à chaque version active de l'API. 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:
client = GoogleAdsService.load_from_storage(version="/google-ads/api/reference/rpc/v13/")
# The Campaign instance will be from the v13 version of the API.
campaign = client.get_type("Campaign")
Il est également possible de spécifier la version lorsque vous appelez les méthodes get_service et get_type. Cette action entraîne le remplacement de la version fournie lors de l'initialisation du client:
client = GoogleAdsService.load_from_storage()
# This will load the v13 version of the GoogleAdsService.
googleads_service = client.get_service(
"GoogleAdsService", version="v13")
client = GoogleAdsService.load_from_storage(version="v13")
# This will load the v11 version of a Campaign.
campaign = client.get_type("Campaign", version="v11")
Si aucun paramètre de mot clé version n'est fourni, la bibliothèque utilise par défaut la dernière version. Vous trouverez une liste à jour des versions les plus récentes et d'autres versions dans la section de navigation de gauche de la documentation de documentation de référence de l'API.