Python で API を使用するために必要なさまざまな proto クラスへの参照をすべて取得するのは冗長になることがあるため、API を本質的に理解しているか、proto やドキュメントを参照するために頻繁にコンテキストの切り替えが必要になります。
クライアントの 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 v17 version of GoogleAdsService will
# be returned.
client = GoogleAdsClient.load_from_storage(version="v17")
googleads_service = client.get_service("GoogleAdsService")
次に、get_type
メソッドを使用して Campaign
インスタンスを取得する方法の例を示します。
from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage(version="v17")
campaign = client.get_type("Campaign")
列挙型
get_type
メソッドを使用して列挙型を取得できますが、各 GoogleAdsClient
インスタンスには get_type
メソッドと同じメカニズムを使用して列挙型を動的に読み込む enums
属性もあります。このインターフェースは、get_type
を使用するよりもシンプルで読みやすいように設計されています。
client = GoogleAdsClient.load_from_storage(version=v17)
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 が維持されます。v17
は最新のバージョンかもしれませんが、廃止されるまでは以前のバージョンもご利用いただけます。ライブラリには、アクティブな各 API バージョンに対応する個別の proto メッセージ クラスが含まれます。特定のバージョンのメッセージ クラスにアクセスするには、クライアントの初期化時に 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")
get_service
メソッドと get_type
メソッドを呼び出すときにバージョンを指定することもできます。これにより、クライアントの初期化時に指定されたバージョンがオーバーライドされます。
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")
version
キーワード パラメータが指定されていない場合、ライブラリはデフォルトで最新バージョンを使用します。最新バージョンと利用可能なその他のバージョンの最新のリストは、API リファレンス ドキュメントの左側のナビゲーション セクションにあります。