Service and Type Getters

Fetching references to all the various proto classes required to use the API in Python can be verbose and requires you to have an intrinsic understanding of the API or frequently context-switch to reference the protos or documentation.

The client's get_service and get_type methods

These two getter methods allow you to retrieve any service or type object in the API. The get_service method is used to retrieve service clients. get_type is used for any other object. Service client classes are defined in code under the version path google/ads/googleads/v*/services/services/ and all types are defined under the various object categories, google/ads/googleads/v*/common|enums|errors|resources|services/types/. All the code underneath the version directory is generated, so it's a best practice to use these methods instead of importing the objects directly, in case the structure of the codebase changes.

Here's an example of how to use the get_service method to retrieve an instance of the GoogleAdsService client.

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

Here's an example of how to use the get_type method to retrieve a Campaign instance.

from google.ads.googleads.client import GoogleAdsClient

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

Enums

While you can use the get_type method to retrieve Enums, each GoogleAdsClient instance also has an enums attribute that dynamically loads Enums using the same mechanism as the get_type method. This interface is intended to be simpler and easier to read than using get_type:

client = GoogleAdsClient.load_from_storage(version=v15)

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

Proto object fields that are enums are represented in Python by the native enum type. That means that you can easily read the value of the member. Working with the campaign instance from the previous example in a Python repl:

>>> print(campaign.status)
CampaignStatus.PAUSED
>>> type(campaign.status)
<enum 'CampaignStatus'>
>>> print(campaign.status.value)
3

Sometimes it's useful to know the name of the field that corresponds to the enum value as shown above. You can access this information using the name attribute:

>>> print(campaign.status.name)
'PAUSED'
>>> type(campaign.status.name)
<class 'str'>

Interacting with enums is different depending on whether you have the use_proto_plus configuration set to true or false. For details on the two interfaces, see the protobuf messages documentation.

Versioning

Multiple versions of the API are maintained at the same time. While v15 may be the latest version, earlier versions are still accessible until they are sunset. The library will include separate proto message classes that correspond to each active API version. To access a message class for a specific version supply the version keyword parameter when initializing a client so that it always returns instance from that given version:

client = GoogleAdsService.load_from_storage(version="/google-ads/api/reference/rpc/v15/")
# The Campaign instance will be from the v15 version of the API.
campaign = client.get_type("Campaign")

It's also possible to specify the version when calling the get_service and get_type methods. Doing this will override the version provided when initializing the client:

client = GoogleAdsService.load_from_storage()
# This will load the v15 version of the GoogleAdsService.
googleads_service = client.get_service(
    "GoogleAdsService", version="v15")

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

If no version keyword parameter is provided the library will default to using the latest version. An updated list of the latest and other available versions can be found in the left-hand navigation section of the API Reference documentation.