Python クライアント ライブラリのバージョン 14.0.0 には、use_proto_plus という新しい必須構成パラメータが導入されています。このパラメータは、ライブラリで proto-plus メッセージと protobuf メッセージのどちらを返すかを指定します。このパラメータの設定方法の詳細については、構成ドキュメントをご覧ください。
このセクションでは、使用するメッセージの種類を選択する際のパフォーマンスへの影響について説明します。十分な情報に基づいた決定を行うために、オプションを読んで理解することをおすすめします。ただし、コードを変更せずにバージョン 14.0.0 にアップグレードする場合は、use_proto_plus を True に設定して、インターフェースの変更を回避します。
proto-plus メッセージと protobuf メッセージ
バージョン 10.0.0 では、Python クライアント ライブラリが新しいコード生成パイプラインに移行されました。このパイプラインでは、protobuf メッセージ インターフェースをネイティブの Python オブジェクトのように動作させることで、protobuf メッセージ インターフェースのエルゴノミクスを改善しています。この改善によるトレードオフは、proto プラスによってパフォーマンスのオーバーヘッドが発生することです。
プロトコル + パフォーマンス
proto-plus の主なメリットの 1 つは、型マーシャリングと呼ばれるプロセスによって、protobuf メッセージと既知の型をネイティブの Python 型に変換できることです。
マーシャリングは、proto-plus メッセージ インスタンスでフィールドがアクセスされたときに発生します。特に、protobuf 定義などで、フィールドが読み取られたり設定されたりするときに発生します。
syntax = "proto3";
message Dog {
string name = 1;
}
この定義を proto-plus クラスに変換すると、次のようになります。
import proto
class Dog(proto.Message):
name = proto.Field(proto.STRING, number=1)
その後、他の Python オブジェクトの場合と同様に、Dog クラスを初期化して、その name フィールドにアクセスできます。
dog = Dog()
dog.name = "Scruffy"
print(dog.name)
name フィールドを読み取って設定すると、値はネイティブの Python str 型から string 型に変換され、protobuf ランタイムと互換性のある値になります。
バージョン 10.0.0 のリリース以降に Google が実施した分析の結果、これらの型変換に費やす時間はパフォーマンスに大きく影響するため、protobuf メッセージを使用するオプションをユーザーに提供することが重要であることがわかりました。
proto-plus メッセージと protobuf メッセージのユースケース
- Proto-plus メッセージのユースケース
- Proto-plus は、protobuf メッセージに比べて人間工学的に多くの点で改善されているため、保守可能で読み取り可能なコードの作成に最適です。ネイティブの Python オブジェクトを公開するため、使いやすく理解しやすくなります。
- Protobuf メッセージのユースケース
- protobuf は、パフォーマンス重視のユースケースで使用します。特に、大規模なレポートを迅速に処理する必要があるアプリや、
BatchJobServiceやOfflineUserDataJobServiceなど、多数のオペレーションを含む変更リクエストを構築するアプリで使用します。
動的に変化するメッセージ タイプ
アプリに適したメッセージ タイプを選択した後、特定のワークフローで他のタイプを使用しなければならない場合があります。この場合、クライアント ライブラリによって提供されるユーティリティを使用して、2 つのタイプを動的に切り替えることができます。上記と同じ Dog メッセージ クラスを使用します。
from google.ads.googleads import util
# Proto-plus message type
dog = Dog()
# Protobuf message type
dog = util.convert_proto_plus_to_protobuf(dog)
# Back to proto-plus message type
dog = util.convert_protobuf_to_proto_plus(dog)
Protobuf メッセージ インターフェースの違い
proto-plus インターフェースについてはこちらのドキュメントで詳しく説明していますが、ここでは、Google 広告クライアント ライブラリの一般的なユースケースに影響する主な違いをいくつか紹介します。
バイトのシリアル化
- プロトコルとメッセージ
serialized = type(campaign).serialize(campaign) deserialized = type(campaign).deserialize(serialized)
- Protobuf メッセージ
serialized = campaign.SerializeToString() deserialized = campaign.FromString(serialized)
JSON シリアル化
- プロトコルとメッセージ
serialized = type(campaign).to_json(campaign) deserialized = type(campaign).from_json(serialized)
- Protobuf メッセージ
from google.protobuf.json_format import MessageToJson, Parse serialized = MessageToJson(campaign) deserialized = Parse(serialized, campaign)
フィールド マスク
api-core が提供するフィールド マスク ヘルパー メソッドは、protobuf メッセージ インスタンスを使用するように設計されています。そのため、proto-plus メッセージを使用する場合は、protobuf メッセージに変換してヘルパーを使用します。
- プロトコルとメッセージ
from google.api_core.protobuf_helpers import field_mask campaign = client.get_type("Campaign") protobuf_campaign = util.convert_proto_plus_to_protobuf(campaign) mask = field_mask(None, protobuf_campaign)- Protobuf メッセージ
from google.api_core.protobuf_helpers import field_mask campaign = client.get_type("Campaign") mask = field_mask(None, campaign)
列挙型
proto-plus メッセージによって公開される列挙型は、Python のネイティブ enum 型のインスタンスであるため、いくつかの便利なメソッドを継承します。
列挙型の取得
GoogleAdsClient.get_type メソッドを使用して列挙型を取得する場合、返されるメッセージは、proto-plus メッセージと protobuf メッセージのどちらを使用するかによって若干異なります。次に例を示します。
- プロトコルとメッセージ
val = client.get_type("CampaignStatusEnum").CampaignStatus.PAUSED- Protobuf メッセージ
val = client.get_type("CampaignStatusEnum").PAUSED
列挙型の取得を簡単にするために、使用するメッセージ タイプに関係なく一貫したインターフェースを持つ GoogleAdsClient インスタンスに便利な属性があります。
val = client.enums.CampaignStatusEnum.PAUSED
列挙値の取得
特定の列挙型の値（フィールド ID）を知っておくと便利な場合があります。たとえば、CampaignStatusEnum の PAUSED は 3 に対応します。
- プロトコルとメッセージ
campaign = client.get_type("Campaign") campaign.status = client.enums.CampaignStatusEnum.PAUSED # To read the value of campaign status print(campaign.status.value)- Protobuf メッセージ
campaign = client.get_type("Campaign") status_enum = client.enums.CampaignStatusEnum campaign.status = status_enum.PAUSED # To read the value of campaign status print(status_enum.CampaignStatus.Value(campaign.status))
列挙型名の取得
列挙型フィールドの名前を知っておくと便利な場合があります。たとえば、API からオブジェクトを読み取る場合、int 3 がどのキャンペーンのステータスに対応しているかを知ることができます。
- プロトコルとメッセージ
campaign = client.get_type("Campaign") campaign.status = client.enums.CampaignStatusEnum.PAUSED # To read the name of campaign status print(campaign.status.name)- Protobuf メッセージ
campaign = client.get_type("Campaign") status_enum = client.enums.CampaignStatusEnum # Sets the campaign status to the int value for PAUSED campaign.status = status_enum.PAUSED # To read the name of campaign status status_enum.CampaignStatus.Name(campaign.status)
繰り返しフィールド
proto とドキュメントで説明されているように、繰り返しフィールドは一般的に型付きリストと同等です。つまり、list とほぼ同じように動作します。
繰り返しスカラー フィールドへの追加
繰り返しスカラー型フィールド（string フィールドや int64 フィールドなど）に値を追加する場合、メッセージ タイプに関係なくインターフェースは同じになります。
- プロトコルとメッセージ
ad.final_urls.append("https://www.example.com")- Protobuf メッセージ
ad.final_urls.append("https://www.example.com")
これには、extend など、他のすべての一般的な list メソッドも含まれます。
- プロトコルとメッセージ
ad.final_urls.extend(["https://www.example.com", "https://www.example.com/2"])
- Protobuf メッセージ
ad.final_urls.extend(["https://www.example.com", "https://www.example.com/2"])
繰り返しフィールドにメッセージ型を追加する
繰り返しフィールドがスカラー型でない場合、繰り返しフィールドに追加する際の動作は若干異なります。
- プロトコルとメッセージ
frequency_cap = client.get_type("FrequencyCapEntry") frequency_cap.cap = 100 campaign.frequency_caps.append(frequency_cap)- Protobuf メッセージ
# The add method initializes a message and adds it to the repeated field frequency_cap = campaign.frequency_caps.add() frequency_cap.cap = 100
繰り返しフィールドの割り当て
スカラー繰り返しフィールドと非スカラー繰り返しフィールドのどちらについても、さまざまな方法でリストをフィールドに割り当てることができます。
- プロトコルとメッセージ
# In proto-plus it's possible to use assignment. urls = ["https://www.example.com"] ad.final_urls = urls
- Protobuf メッセージ
# Protobuf messages do not allow assignment, but you can replace the # existing list using slice syntax. urls = ["https://www.example.com"] ad.final_urls[:] = urls
空のメッセージ
メッセージ インスタンスに情報が含まれているかどうかや、いずれかのフィールドが設定されているかどうかを確認すると役に立つ場合があります。
- プロトコルとメッセージ
# When using proto-plus messages you can simply check the message for # truthiness. is_empty = bool(campaign) is_empty = not campaign
- Protobuf メッセージ
is_empty = campaign.ByteSize() == 0
メッセージのコピー
proto-plus メッセージと protobuf メッセージの両方について、GoogleAdsClient で copy_from ヘルパー メソッドを使用することをおすすめします。
client.copy_from(campaign, other_campaign)
空のメッセージ フィールド
空のメッセージ フィールドを設定するプロセスは、使用しているメッセージの種類に関係なく同じです。必要な操作は、対象のフィールドに空のメッセージをコピーすることだけです。メッセージのコピー セクションと空のメッセージ フィールドのガイドをご覧ください。空のメッセージ フィールドを設定する方法の例を次に示します。
client.copy_from(campaign.manual_cpm, client.get_type("ManualCpm"))
予約済みの単語であるフィールド名
proto-plus メッセージを使用する場合、フィールド名が Python の予約語でもある場合、フィールド名の末尾にはアンダースコアが自動的に付きます。Asset インスタンスの操作例を次に示します。
asset = client.get_type("Asset")
asset.type_ = client.enums.AssetTypeEnum.IMAGE
予約済みの名前の完全なリストは、gapic generator モジュールで作成されています。プログラムからもアクセスできます。
まず、モジュールをインストールします。
python -m pip install gapic-generator
次に、Python の REPL またはスクリプトで次の操作を行います。
import gapic.utils
print(gapic.utils.reserved_names.RESERVED_NAMES)
フィールドの有無
protobuf メッセージ インスタンスのフィールドにはデフォルト値があるため、フィールドが設定されているかどうかを必ずしも直感的に判別できるわけではありません。
- プロトコルとメッセージ
# Use the "in" operator. has_field = "name" in campaign
- Protobuf メッセージ
campaign = client.get_type("Campaign") # Determines whether "name" is set and not just an empty string. campaign.HasField("name")
protobuf の Message クラス インターフェースには、デフォルト値が設定されていても、メッセージにフィールドが設定されているかどうかを確認する HasField メソッドがあります。
Protobuf メッセージ メソッド
protobuf メッセージ インターフェースには、proto-plus インターフェースの一部ではない便利なメソッドが含まれていますが、proto-plus メッセージを対応する protobuf に変換することで簡単にアクセスできます。
# Accessing the ListFields method
protobuf_campaign = util.convert_protobuf_to_proto_plus(campaign)
print(campaign.ListFields())
# Accessing the Clear method
protobuf_campaign = util.convert_protobuf_to_proto_plus(campaign)
print(campaign.Clear())
Issue Tracker
これらの変更についてご不明な点がある場合や、ライブラリのバージョン 14.0.0 への移行で問題が発生した場合は、Google のトラッカーで問題を報告してください。