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 v8 version of GoogleAdsService will
# be returned.
client = GoogleAdsClient.load_from_storage(version="v8")
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="v8")
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=v8)
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'>
Versioning
Multiple versions of the API are maintained at the same time. While
v8 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/v8/")
# The Campaign instance will be from the v8 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 v8 version of the GoogleAdsService.
googleads_service = client.get_service(
"GoogleAdsService",
version="v8"
)
client = GoogleAdsService.load_from_storage(version="v8")
# This will load the v7 version of a Campaign.
campaign = client.get_type("Campaign", version="v7")
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.