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 using 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 v6 but this version could change
from google.ads.google_ads.v6.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 you cannot access enum field names using enum field numbers
of enum instances retrieved by the service.enums
interface described
above.
Versioning
Multiple versions of the API are maintained at the same time. While
v6
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='v6')
campaign = client.get_type('Campaign', version='v6')
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.