Python で API を使用するのに必要なさまざまなプロトクラスへの参照をすべて取得すると、冗長になる可能性があります。また、API を深く理解しているか、プロトまたはドキュメントを参照するために頻繁にコンテキスト スイッチを行う必要があります。
クライアントの get_service メソッドと get_type メソッド
これらの 2 つのゲッター メソッドを使用すると、API 内の任意のサービスまたは型オブジェクトを取得できます。get_service メソッドは、サービス クライアントを取得するために使用されます。get_type は、他のオブジェクトに使用されます。サービス クライアント クラスは、バージョンパス google/ads/googleads/v*/services/services/ のコードで定義され、すべてのタイプはさまざまなオブジェクト カテゴリ google/ads/googleads/v*/common|enums|errors|resources|services/types/ で定義されます。バージョン ディレクトリの下のコードはすべて生成されるため、コードベースの構造が変更された場合に備えて、オブジェクトを直接インポートするのではなく、これらのメソッドを使用することをおすすめします。
get_service メソッドを使用して GoogleAdsService クライアントのインスタンスを取得する方法の例を次に示します。
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 v18 version of GoogleAdsService will
# be returned.
client = GoogleAdsClient.load_from_storage(version="v18")
googleads_service = client.get_service("GoogleAdsService")
get_type メソッドを使用して Campaign インスタンスを取得する方法の例を次に示します。
from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage(version="v18")
campaign = client.get_type("Campaign")
列挙型
get_type メソッドを使用して列挙型を取得できますが、各 GoogleAdsClient インスタンスには、get_type メソッドと同じメカニズムを使用して列挙型を動的に読み込む enums 属性もあります。このインターフェースは、get_type を使用するよりもシンプルで読みやすくすることを目的としています。
client = GoogleAdsClient.load_from_storage(version=v18)
campaign = client.get_type("Campaign")
campaign.status = client.enums.CampaignStatusEnum.PAUSED
列挙型であるプロトオブジェクト フィールドは、Python ではネイティブの 列挙型で表されます。つまり、メンバーの値を簡単に読み取ることができます。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 の複数のバージョンが同時に維持されます。v18 が最新バージョンですが、以前のバージョンは廃止されるまで引き続きアクセスできます。ライブラリには、アクティブな API バージョンごとに個別の proto メッセージ クラスが含まれます。特定のバージョンのメッセージクラスにアクセスするには、クライアントの初期化時に version キーワード パラメータを指定して、常に指定されたバージョンのインスタンスを返します。
client = GoogleAdsService.load_from_storage(version="/google-ads/api/reference/rpc/v18/")
# The Campaign instance will be from the v18 version of the API.
campaign = client.get_type("Campaign")
get_service メソッドと get_type メソッドを呼び出すときにバージョンを指定することもできます。これにより、クライアントの初期化時に指定されたバージョンがオーバーライドされます。
client = GoogleAdsService.load_from_storage()
# This will load the v18 version of the GoogleAdsService.
googleads_service = client.get_service(
"GoogleAdsService", version="v18")
client = GoogleAdsService.load_from_storage(version="v18")
# This will load the v16 version of a Campaign.
campaign = client.get_type("Campaign", version="v16")
version キーワード パラメータが指定されていない場合、ライブラリはデフォルトで最新バージョンを使用します。最新バージョンとその他の利用可能なバージョンの最新リストについては、API リファレンスのドキュメントの左側のナビゲーション セクションをご覧ください。