Python で API を使用するために必要なさまざまな proto クラスへの参照を取得することは、冗長になる可能性があり、API の本質的な理解が必要になります。また、proto やドキュメントを参照するために頻繁にコンテキストを切り替える必要があります。
クライアントの get_service メソッドと get_type メソッド
これらの 2 つの getter メソッドを使用すると、API 内のサービス オブジェクトまたは型オブジェクトを取得できます。get_service メソッドは、サービス クライアントの取得に使用されます。他のオブジェクトには get_type が使用されます。サービス クライアント クラスは、バージョン パス google/ads/googleads/v*/services/ のコードで定義され、すべてのタイプはさまざまなオブジェクト カテゴリ google/ads/googleads/v*/common|enums|errors|resources|services/types/ で定義されます。バージョン ディレクトリの下にあるすべてのコードが生成されるため、コードベースの構造が変更された場合に備えて、オブジェクトを直接インポートするのではなく、これらのメソッドを使用することをおすすめします。
次の例は、get_service メソッドを使用して GoogleAdsService クライアントのインスタンスを取得する方法を示しています（または、google-ads v28.4.0 以降で is_async=True を渡すことによって非同期 GoogleAdsServiceAsyncClient を取得する方法を示しています）。
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 v25 version of GoogleAdsService will
# be returned.
client = GoogleAdsClient.load_from_storage(version="v25")
googleads_service = client.get_service("GoogleAdsService")
# Supported in google-ads v28.4.0 and later: retrieve an async service client.
googleads_async_service = client.get_service("GoogleAdsService", is_async=True)
次の例は、get_type メソッドを使用して Campaign インスタンスを取得する方法を示しています。
from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage(version="v25")
campaign = client.get_type("Campaign")
列挙型
get_type メソッドを使用して列挙型を取得できますが、各 GoogleAdsClient インスタンスには、get_type メソッドと同じメカニズムを使用して列挙型を動的に読み込む enums 属性もあります。このインターフェースは、get_type を使用するよりもシンプルで読みやすくなっています。
from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage(version="v25")
campaign = client.get_type("Campaign")
campaign.status = client.enums.CampaignStatusEnum.PAUSED
列挙型である Proto オブジェクト フィールドは、Python では組み込みの enum 型で表されます。つまり、メンバーの値を直接読み取ることができます。Python REPL で前の例の campaign インスタンスを操作します。
>>> print(campaign.status)
CampaignStatus.PAUSED
>>> type(campaign.status)
<enum 'CampaignStatus'>
>>> print(campaign.status.value)
3
列挙型値に対応するフィールドの名前を知っておくと便利な場合があります。この情報には、name 属性を使用してアクセスできます。
>>> print(campaign.status.name)
'PAUSED'
>>> type(campaign.status.name)
<class 'str'>
列挙型とのやり取りは、use_proto_plus 構成が true または false のどちらに設定されているかによって異なります。2 つのインターフェースの詳細については、protobuf メッセージのドキュメントをご覧ください。
バージョニング
API の複数のバージョンが同時に維持されます。v25 は最新バージョンですが、以前のバージョンは廃止されるまで引き続きアクセスできます。このライブラリには、アクティブな API バージョンごとに対応する個別の proto メッセージ クラスが含まれています。特定のバージョンのメッセージ クラスにアクセスするには、クライアントの初期化時に version キーワード パラメータを指定して、常にその指定されたバージョンのインスタンスを返すようにします。
from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage(version="v25")
# The Campaign instance will be from the v25 version of the API.
campaign = client.get_type("Campaign")
クライアントの初期化時に version を指定しない場合は、get_service メソッドと get_type メソッドを呼び出すときに、呼び出しごとにバージョンを指定できます（GoogleAdsClient の初期化時に version が設定されている場合、get_service または get_type に渡された version 引数はオーバーライドされます）。
from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage()
# This loads the v25 version of the GoogleAdsService.
googleads_service = client.get_service(
"GoogleAdsService", version="v25"
)
# This loads a specific supported API version (such as v23) of a Campaign.
campaign = client.get_type("Campaign", version="v23")
version キーワード パラメータが指定されていない場合、ライブラリはインストールされている google-ads パッケージでサポートされている最も高い API バージョン（最新リリースでは "v25"）をデフォルトで使用します。マイナー API リリース（v25.1 など）には、メジャー バージョン文字列（version="v25"）を使用してアクセスします。最新バージョンとその他の利用可能なバージョンの最新リストは、API リファレンス ドキュメントの左側のナビゲーション セクションにあります。