このページは Cloud Translation API によって翻訳されました。

Protobuf メッセージ

バージョン 14.0.0 Python クライアントライブラリに、新しい必須構成パラメータが導入されました。呼び出すかどうかを指定する use_proto_plus という関数です。 proto-plus messages、または protobuf メッセージ。詳細については、このパラメータの設定方法については、構成ドキュメントをご覧ください。

このセクションでは、パフォーマンスへの影響について、記載されています。詳しくは、このモジュールのコースで十分な情報を得たうえで判断できます必要に応じてコードを変更せずにバージョン 14.0.0 にアップグレードする場合は、インターフェースの変更の互換性を損なわないように、use_proto_plus を True に変更。

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

バージョン 10.0.0 では、Python クライアントライブラリが新しいコード生成ツールに移行されました。統合されたパイプラインを proto-plus を使用して、人間工学的に改善された protobuf メッセージインターフェースが、オブジェクトに似ていますこの改善によるトレードオフはパフォーマンスのオーバーヘッドが生じます

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

proto-plus の主な利点の一つは、protobuf を変換し、メッセージ既知の型を使用してネイティブな Python 型を type というプロセスでマーシャリング。

マーシャリングは、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)

次に、Dog クラスを初期化して、その name フィールドにアクセスする場合と同様です。次のように指定します。

dog = Dog()
dog.name = "Scruffy"
print(dog.name)

name フィールドを読み取って設定すると、値がネイティブ Python の str 型を string 型に変換するため、その値が protobuf ランタイムと互換性があることを確認します。

バージョン 10.0.0 のリリース以降に実施された分析では、以下の点が改善されています。これらのタイプのコンバージョンに費やす時間で、十分な余裕があると判断したユーザーが protobuf を使用できるようにすることが、パフォーマンスへの影響です。ブロックすることもできます。

proto-plus メッセージと protobuf メッセージのユースケース

Proto-plus メッセージのユースケース: Proto-plus には、protobuf メッセージに比べ、人間工学的に多くの改善が加えられています。保守可能で読みやすいコードを記述するのに最適ですこれらのツールは Python ネイティブオブジェクトなので、使いやすく理解しやすいです。
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 メソッドを使用して列挙型を取得すると、メッセージ返されるメッセージの種類は、 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-plus ドキュメント、通常、繰り返しフィールドは型付きリストと同等です。 list とほぼ同じように動作します。

繰り返しスカラーフィールドへの追加

繰り返しスカラーに値を追加する場合 type フィールド。例: string または int64 フィールドの場合、メッセージに関係なくインターフェースは同じ type:

プロトコルとメッセージ

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 メッセージの両方には、copy_from を使用することをおすすめします。 GoogleAdsClient のヘルパーメソッド:

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

予約されている電話番号の一覧は、名前構築されます。 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())

公開バグトラッカー

これらの変更についてご不明な点がある場合や、バージョン 14.0.0 のライブラリについては、の。

Protobuf メッセージ

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

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

proto-plus メッセージと protobuf メッセージのユースケース

動的に変化するメッセージ タイプ

Protobuf メッセージ インターフェースの違い

バイトのシリアル化

JSON シリアル化

フィールド マスク

列挙型

列挙型の取得

列挙値の取得

列挙型名の取得

繰り返しフィールド

繰り返しスカラー フィールドへの追加

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

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

空のメッセージ

メッセージのコピー

空のメッセージ フィールド

予約済みの単語であるフィールド名

フィールドの有無

Protobuf メッセージ メソッド

公開バグトラッカー

動的に変化するメッセージタイプ

Protobuf メッセージインターフェースの違い

フィールドマスク

繰り返しスカラーフィールドへの追加

空のメッセージフィールド

Protobuf メッセージメソッド