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. Services are defined in code under the version path (google/ads/google_ads/v*/services/) and all types are exported via the types.py file. In general use get_service to retrieve a service client and get_type for any other object.

It's recommended that you use both of these getter methods to access services and types. However you can import these classes directly, for example:

# note this example uses v4 but this version could change
from google.ads.google_ads.v4.proto.resources.campaign_pb2 import Campaign
campaign = Campaign()

The get_type client method simplifies this by importing the module and instantiating the message class for you:

from google.ads.google_ads.client import GoogleAdsClient
# "get_type" is a class method so it can be called on the class
# definition directly
campaign = GoogleAdsClient.get_type('Campaign')
# or on an instance of the class
# "load_from_storage" loads your API credentials from disk, passes
# them to the class initializer and returns an instance of itself.
client = GoogleAdsClient.load_from_storage()
campaign = client.get_type('Campaign')

Similarly you can import service clients manually, however you will need to instantiate them with a transport class, interceptors, and OAuth2 credentials before using them. Instead it's easier to simply use the get_service instance method:

from google.ads.google_ads.client import GoogleAdsClient
# "load_from_storage" loads your API credentials from disk so they
# can be used for service initialization. Since "get_service" requires
# API credentials it can only be called on instances of the GoogleAdsClient.
client = GoogleAdsClient.load_from_storage()
google_ads_service = client.get_service('GoogleAdsService')

Enums

For enumerations you can use the get_type method and access the object's enumerable fields directly:

campaign.status = client.get_type('CampaignStatusEnum').PAUSED

However every service client is decorated with an enums property that exposes every enum in the API, so you can also use:

campaign_service = client.get_service('CampaignService')
campaign_status_enum = campaign_service.enums.CampaignStatusEnum
campaign = client.get_type('Campaign')
campaign.status = campaign_status_enum.CampaignStatus.PAUSED

When working with a proto object field whose value is an enum you might notice that accessing that field returns an int. For example, if you're interacting with a campaign with status PAUSED in a repl:

>>> print(campaign.status)
3
>>> type(campaign.status)
<class 'int'>

Sometimes it's useful to know the name of the field that corresponds to the field number above. You can access this information by passing the field number to the enums Name method:

from google.ads.google_ads.client import GoogleAdsClient
campaign_status_enum = client.get_type('CampaignStatusEnum')
field_name = campaign_status_enum.CampaignStatus.Name(campaign.status)
print(field_name)
# will print a str: 'PAUSED'

Note that it's not possible to access enum field names using enum field numbers using enum instances retrieved via the service.enums interface described above.

Versioning

Multiple versions of the API are maintained at the same time. While v4 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 to either the get_service or get_type methods:

google_ads_service = client.get_service('GoogleAdsService',
version='v4')
campaign = client.get_type('Campaign', version='v4')

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.