Protobuf メッセージ

use_proto_plus 構成パラメータを使用すると、ライブラリが proto-plus メッセージを返すか、protobuf メッセージを返すかを指定できます。このパラメータの設定方法の詳細については、構成ドキュメントをご覧ください。

このセクションでは、使用するメッセージの種類を選択した場合のパフォーマンスへの影響について説明します。十分な情報に基づいて決定を下すため、オプションを読んで理解することをおすすめします。

proto-plus メッセージと protobuf メッセージ

コード生成パイプラインでは、proto-plus を統合して protobuf メッセージ インターフェースのエルゴノミクスを改善し、ネイティブの Python オブジェクトのように動作させます。ただし、proto-plus を使用するとパフォーマンス オーバーヘッドが発生します。

プロトコル + パフォーマンス

proto-plus の主なメリットの 1 つは、型マーシャリングというプロセスを介して、protobuf メッセージと well-known 型をネイティブ 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 ランタイムと互換性を持つようになります。

パフォーマンス分析に基づいて、これらの型変換に費やされる時間がパフォーマンスに大きな影響を与えるため、ユーザーはニーズに基づいて 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 広告クライアント ライブラリの一般的なユースケースに影響する主な違いをいくつか紹介します。

バイトのシリアル化

Proto-plus メッセージ
serialized = type(campaign).serialize(campaign)
deserialized = type(campaign).deserialize(serialized)
Protobuf メッセージ
serialized = campaign.SerializeToString()
deserialized = campaign.FromString(serialized)

JSON シリアル化

Proto-plus メッセージ
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 メッセージに変換します。

Proto-plus メッセージ
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 メッセージのどちらを使用するかによって若干異なります。例:

Proto-plus メッセージ
val = client.get_type("CampaignStatusEnum").CampaignStatus.PAUSED
Protobuf メッセージ
val = client.get_type("CampaignStatusEnum").PAUSED

列挙型の取得を簡単にするため、GoogleAdsClient インスタンスには、使用しているメッセージ タイプに関係なく一貫したインターフェースを持つ便利な属性があります。

val = client.enums.CampaignStatusEnum.PAUSED

列挙値の取得

特定の列挙型の値（フィールド ID）を知っておくと便利な場合があります。たとえば、CampaignStatusEnum の PAUSED は 3 に対応しています。

Proto-plus メッセージ
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 がどのキャンペーン ステータスに対応しているかを知りたい場合があります。

Proto-plus メッセージ
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-plus のドキュメントで説明されているように、繰り返しフィールドは通常、型付きリストと同等です。つまり、list とほぼ同じ動作をします。

繰り返しスカラー フィールドに値を追加する

string フィールドや int64 フィールドなど、反復するスカラー型のフィールドに値を追加する場合、インターフェースはメッセージ タイプに関係なく同じです。

Proto-plus メッセージ
ad.final_urls.append("https://www.example.com")
Protobuf メッセージ
ad.final_urls.append("https://www.example.com")

これには、extend など、他のすべての一般的な list メソッドも含まれます。

Proto-plus メッセージ
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"])

繰り返しフィールドにメッセージ タイプを追加する

繰り返しフィールドがスカラー型でない場合、繰り返しフィールドに追加する際の動作は若干異なります。

Proto-plus メッセージ
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

繰り返しフィールドを割り当てる

スカラー フィールドとスカラー以外の繰り返しフィールドの両方で、リストをフィールドに割り当てる方法は次のとおりです。

Proto-plus メッセージ
# 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

空のメッセージ

メッセージ インスタンスに情報が含まれているかどうかや、いずれかのフィールドが設定されているかどうかを確認すると役に立つ場合があります。

Proto-plus メッセージ
# 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 ジェネレータ モジュールで作成されます。プログラムでアクセスすることもできます。

まず、モジュールをインストールします。

python -m pip install gapic-generator

次に、Python REPL またはスクリプトで次のようにします。

import gapic.utils
print(gapic.utils.reserved_names.RESERVED_NAMES)

フィールドでの存在感

protobuf メッセージ インスタンスのフィールドにはデフォルト値があるため、フィールドが設定されているかどうかを直感的に判断できない場合があります。

Proto-plus メッセージ
# 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

これらの変更についてご不明な点がある場合や、ライブラリの最新バージョンへの移行で問題が発生した場合は、トラッカーで問題を報告してください。