Pesan Protobuf

Dengan parameter konfigurasi use_proto_plus, Anda dapat menentukan apakah Anda ingin library menampilkan pesan proto-plus atau pesan protobuf. Untuk mengetahui detail cara menetapkan parameter ini, lihat dokumen konfigurasi.

Bagian ini menjelaskan implikasi performa dari setiap opsi sehingga Anda dapat memilih pendekatan terbaik untuk aplikasi Anda.

Pesan proto-plus versus protobuf

Pipeline pembuat kode mengintegrasikan proto-plus sebagai cara untuk meningkatkan ergonomi antarmuka pesan protobuf dengan membuatnya berperilaku lebih seperti objek Python standar. Namun, ini berarti penggunaan proto-plus menimbulkan beban performa.

Performa proto-plus

Salah satu manfaat utama proto-plus adalah kemampuannya untuk mengonversi pesan protobuf dan jenis terkenal ke jenis Python bawaan melalui proses yang disebut marshaling jenis.

Marshalling terjadi saat kolom diakses pada instance pesan proto-plus, khususnya saat kolom dibaca atau ditetapkan, misalnya, dalam definisi protobuf:

syntax = "proto3";

message Dog {
  string name = 1;
}

Jika dikonversi menjadi class proto-plus, definisi ini akan terlihat seperti ini:

import proto


class Dog(proto.Message):
    name = proto.Field(proto.STRING, number=1)

Kemudian, Anda dapat menginisialisasi class Dog dan mengakses kolom name-nya seperti yang Anda lakukan pada objek Python lainnya:

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

Saat membaca dan menyetel kolom name, nilai dikonversi dari jenis str Python bawaan ke jenis string agar nilai kompatibel dengan runtime protobuf.

Waktu yang dihabiskan untuk melakukan konversi jenis ini memiliki dampak performa yang cukup besar sehingga Anda harus memutuskan, berdasarkan kebutuhan aplikasi Anda, apakah akan menggunakan pesan proto-plus atau protobuf.

Kasus penggunaan untuk pesan proto-plus dan protobuf

Kasus penggunaan pesan proto-plus
Proto-plus menawarkan sejumlah peningkatan ergonomis dibandingkan pesan protobuf, sehingga ideal untuk menulis kode yang mudah dikelola dan dibaca. Karena mengekspos objek Python standar, objek ini lebih mudah digunakan dan dipahami.
Kasus penggunaan pesan Protobuf
Gunakan protobuf untuk kasus penggunaan yang sensitif terhadap performa, khususnya di aplikasi yang perlu memproses laporan besar dengan cepat, atau yang membuat permintaan perubahan dengan sejumlah besar operasi, misalnya dengan BatchJobService atau OfflineUserDataJobService.

Mengubah jenis pesan secara dinamis

Setelah memilih jenis pesan yang sesuai untuk aplikasi, Anda mungkin mendapati bahwa Anda perlu menggunakan jenis pesan lainnya untuk alur kerja tertentu. Dalam hal ini, Anda dapat beralih di antara kedua jenis secara dinamis menggunakan utilitas yang ditawarkan oleh pustaka klien. Menggunakan class pesan Dog yang sama dari sebelumnya:

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)

Perbedaan antarmuka pesan Protobuf

Antarmuka proto-plus didokumentasikan secara mendetail, dan bagian berikut menyoroti perbedaan utama yang memengaruhi kasus penggunaan umum untuk library klien Google Ads.

Serialisasi byte

Pesan proto-plus
serialized = type(campaign).serialize(campaign)
deserialized = type(campaign).deserialize(serialized)
Pesan Protobuf
serialized = campaign.SerializeToString()
deserialized = campaign.FromString(serialized)

Serialisasi JSON

Pesan proto-plus
serialized = type(campaign).to_json(campaign)
deserialized = type(campaign).from_json(serialized)
Pesan Protobuf
from google.protobuf.json_format import MessageToJson, Parse

serialized = MessageToJson(campaign)
deserialized = Parse(serialized, campaign)

Mask kolom

Metode helper mask kolom yang disediakan oleh api-core dirancang untuk menggunakan instance pesan protobuf. Saat menggunakan pesan proto-plus, konversikan pesan tersebut menjadi pesan protobuf untuk menggunakan helper:

Pesan 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)
Pesan Protobuf
from google.api_core.protobuf_helpers import field_mask

campaign = client.get_type("Campaign")
mask = field_mask(None, campaign)

Enum

Enum yang diekspos oleh pesan proto-plus adalah instance jenis enum bawaan Python dan oleh karena itu mewarisi sejumlah metode praktis.

Pengambilan jenis enum

Saat menggunakan metode GoogleAdsClient.get_type untuk mengambil enum, pesan yang ditampilkan sedikit berbeda, bergantung pada apakah Anda menggunakan pesan proto-plus atau protobuf. Contoh:

Pesan proto-plus
val = client.get_type("CampaignStatusEnum").CampaignStatus.PAUSED
Pesan Protobuf
val = client.get_type("CampaignStatusEnum").PAUSED

Untuk mempermudah pengambilan enum, ada atribut praktis pada instance GoogleAdsClient yang memiliki antarmuka yang konsisten, terlepas dari jenis pesan yang Anda gunakan:

val = client.enums.CampaignStatusEnum.PAUSED

Pengambilan nilai enum

Terkadang berguna untuk mengetahui nilai, atau ID kolom, dari enum tertentu, misalnya, PAUSED pada CampaignStatusEnum sesuai dengan 3:

Pesan proto-plus
campaign = client.get_type("Campaign")
campaign.status = client.enums.CampaignStatusEnum.PAUSED
# To read the value of campaign status
print(campaign.status.value)
Pesan Protobuf
campaign = client.get_type("Campaign")
status_enum = client.enums.CampaignStatusEnum
campaign.status = status_enum.PAUSED
# Native protobuf enum fields already store the integer value (3):
print(campaign.status)
# Or look up the integer value from the enum name string:
print(status_enum.CampaignStatus.Value("PAUSED"))

Pengambilan nama enum

Terkadang, mengetahui nama kolom enum berguna. Misalnya, saat membaca objek dari API, Anda mungkin ingin mengetahui status kampanye yang sesuai dengan bilangan bulat 3:

Pesan proto-plus
campaign = client.get_type("Campaign")
campaign.status = client.enums.CampaignStatusEnum.PAUSED
# To read the name of campaign status
print(campaign.status.name)
Pesan 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
print(status_enum.CampaignStatus.Name(campaign.status))

Kolom berulang

Seperti yang dijelaskan dalam dokumen proto-plus, kolom berulang umumnya setara dengan daftar yang diketik, yang berarti kolom tersebut berperilaku hampir sama dengan list.

Menambahkan nilai ke kolom skalar berulang

Saat menambahkan nilai ke kolom berulang jenis skalar, misalnya kolom string atau int64, antarmukanya sama terlepas dari jenis pesan:

Pesan proto-plus
ad.final_urls.append("https://www.example.com")
Pesan Protobuf
ad.final_urls.append("https://www.example.com")

Hal ini juga mencakup semua metode list umum lainnya, misalnya extend:

Pesan proto-plus
ad.final_urls.extend(
    ["https://www.example.com", "https://www.example.com/2"]
)
Pesan Protobuf
ad.final_urls.extend(
    ["https://www.example.com", "https://www.example.com/2"]
)

Menambahkan jenis pesan ke kolom berulang

Jika kolom berulang bukan jenis skalar, perilaku saat menambahkannya ke kolom berulang sedikit berbeda:

Pesan proto-plus
frequency_cap = client.get_type("FrequencyCapEntry")
frequency_cap.cap = 100
campaign.frequency_caps.append(frequency_cap)
Pesan Protobuf
# The add method initializes a message and adds it to the repeated field
frequency_cap = campaign.frequency_caps.add()
frequency_cap.cap = 100

Menetapkan kolom berulang

Untuk kolom berulang skalar dan non-skalar, Anda dapat menetapkan daftar ke kolom dengan berbagai cara:

Pesan proto-plus
# In proto-plus it's possible to use assignment.
urls = ["https://www.example.com"]
ad.final_urls = urls
Pesan 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

Pesan kosong

Terkadang, Anda perlu mengetahui apakah instance pesan berisi informasi atau memiliki kolom yang ditetapkan.

Pesan proto-plus
# When using proto-plus messages you can check the message for truthiness.
is_empty = not bool(campaign)
Pesan Protobuf
is_empty = campaign.ByteSize() == 0

Salinan pesan

Untuk pesan proto-plus dan protobuf, gunakan metode helper copy_from di GoogleAdsClient:

client.copy_from(campaign, other_campaign)

Kolom pesan kosong

Proses untuk menyetel kolom pesan kosong sama, terlepas dari jenis pesan yang Anda gunakan. Anda menyalin pesan kosong ke kolom yang dimaksud. Lihat bagian Salinan pesan serta panduan Kolom pesan kosong. Contoh berikut menunjukkan cara menetapkan kolom pesan kosong:

client.copy_from(campaign.manual_cpm, client.get_type("ManualCpm"))

Nama kolom yang merupakan kata yang digunakan sistem

Saat menggunakan pesan proto-plus, nama kolom akan otomatis muncul dengan garis bawah di akhir jika nama tersebut juga merupakan kata yang dicadangkan di Python. Contoh berikut menunjukkan cara menggunakan instance Asset:

asset = client.get_type("Asset")
asset.type_ = client.enums.AssetTypeEnum.IMAGE

Daftar lengkap nama yang dicadangkan dibuat dalam modul generator gapic. Anda juga dapat mengaksesnya secara terprogram.

Pertama, instal modul:

python -m pip install gapic-generator

Kemudian, di REPL atau skrip Python:

import gapic.utils

print(gapic.utils.reserved_names.RESERVED_NAMES)

Kehadiran di lapangan

Karena kolom pada instance pesan protobuf memiliki nilai default, tidak selalu intuitif untuk mengetahui apakah kolom telah ditetapkan atau belum.

Pesan proto-plus
# Use the "in" operator.
has_field = "name" in campaign
Pesan Protobuf
campaign = client.get_type("Campaign")
# Determines whether "name" is set and not just an empty string.
campaign.HasField("name")

Antarmuka class Message protobuf memiliki metode HasField yang menentukan apakah sub-pesan, kolom oneof, atau kolom skalar optional pada pesan telah ditetapkan, meskipun ditetapkan ke nilai default. (Memanggil HasField pada kolom skalar non-opsional di proto3 akan memunculkan ValueError.)

Metode pesan Protobuf

Antarmuka pesan protobuf mencakup beberapa metode praktis yang bukan bagian dari antarmuka proto-plus; namun, Anda dapat mengaksesnya dengan mengonversi pesan proto-plus ke pesan protobuf yang sesuai:

# Accessing the ListFields method
protobuf_campaign = util.convert_proto_plus_to_protobuf(campaign)
print(protobuf_campaign.ListFields())

# Accessing the Clear method
protobuf_campaign = util.convert_proto_plus_to_protobuf(campaign)
protobuf_campaign.Clear()

Issue Tracker

Jika ada pertanyaan tentang perubahan ini atau masalah saat bermigrasi ke library versi terbaru, ajukan masalah di issue tracker.