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 v17 version of GoogleAdsService will
# be returned.
client = GoogleAdsClient.load_from_storage(version="v17")
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="v17")
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=v17)
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
v17
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/v17/")
# The Campaign instance will be from the v17 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 v17 version of the GoogleAdsService.
googleads_service = client.get_service(
"GoogleAdsService", version="v17")
client = GoogleAdsService.load_from_storage(version="v17")
# This will load the v15 version of a Campaign.
campaign = client.get_type("Campaign", version="v15")
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.