Pesan Protobuf

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

Bagian ini menjelaskan implikasi performa dari memilih jenis pesan yang akan digunakan. Oleh karena itu, sebaiknya baca dan pahami opsi tersebut untuk membuat keputusan yang tepat.

Pesan proto-plus versus protobuf

Pipeline generator kode mengintegrasikan proto-plus sebagai cara untuk meningkatkan ergonomi antarmuka pesan protobuf dengan membuatnya berperilaku lebih seperti objek Python native. Namun, hal ini berarti bahwa penggunaan proto-plus akan menimbulkan overhead performa.

Performa proto-plus

Salah satu manfaat inti proto-plus adalah mengonversi pesan protobuf dan jenis yang dikenal menjadi jenis Python native melalui proses yang disebut marshaling jenis.

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

syntax = "proto3";

message Dog {
  string name = 1;
}

Saat definisi ini dikonversi ke class proto-plus, tampilannya akan terlihat seperti ini:

import proto

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

Kemudian, Anda dapat melakukan inisialisasi 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 menetapkan kolom name, nilai dikonversi dari jenis str Python native menjadi jenis string sehingga nilai tersebut kompatibel dengan runtime protobuf.

Berdasarkan analisis performa, kami telah menentukan bahwa waktu yang dihabiskan untuk melakukan konversi jenis ini memiliki dampak performa yang cukup besar sehingga pengguna harus memutuskan, berdasarkan kebutuhan mereka, apakah akan menggunakan pesan protobuf atau tidak.

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 dapat dikelola dan dibaca. Karena mengekspos objek Python native, API ini lebih mudah digunakan dan dipahami.

Kasus penggunaan pesan Protobuf

Gunakan protobuf untuk kasus penggunaan yang sensitif terhadap performa, terutama di aplikasi yang perlu memproses laporan besar dengan cepat, atau yang membuat permintaan mutasi dengan operasi dalam jumlah besar, misalnya dengan BatchJobService atau OfflineUserDataJobService.

Mengubah jenis pesan secara dinamis

Setelah memilih jenis pesan yang sesuai untuk aplikasi, Anda mungkin menemukan bahwa Anda perlu menggunakan jenis lain untuk alur kerja tertentu. Dalam hal ini, Anda dapat dengan mudah beralih di antara kedua jenis tersebut secara dinamis menggunakan utilitas yang ditawarkan oleh library klien. Menggunakan class pesan Dog yang sama dari atas:

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, tetapi di sini kita akan menyoroti beberapa 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. Jadi, saat menggunakan pesan proto-plus, konversikan ke 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 dari jenis enum native Python, sehingga 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 ada baiknya mengetahui nilai, atau ID kolom, dari enum tertentu, misalnya, PAUSED di 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
# To read the value of campaign status
print(status_enum.CampaignStatus.Value(campaign.status))

Pengambilan nama enum

Terkadang ada gunanya mengetahui nama kolom enum. Misalnya, saat membaca objek dari API, Anda mungkin ingin mengetahui status kampanye yang sesuai dengan int 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
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 bahwa kolom tersebut berperilaku hampir sama dengan list.

Menambahkan nilai ke kolom skalar berulang

Saat menambahkan nilai ke kolom jenis skalar berulang, 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 akan 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 cara yang berbeda:

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 ada gunanya mengetahui apakah instance pesan berisi informasi apa pun, atau memiliki kolom yang ditetapkan.

Pesan proto-plus

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

Pesan Protobuf

is_empty = campaign.ByteSize() == 0

Salinan pesan

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

client.copy_from(campaign, other_campaign)

Kolom pesan kosong

Proses untuk menetapkan kolom pesan kosong sama, terlepas dari jenis pesan yang Anda gunakan. Anda hanya perlu menyalin pesan kosong ke kolom yang dimaksud. Lihat bagian Salinan pesan serta panduan Kolom Pesan Kosong. Berikut adalah contoh cara menetapkan kolom pesan kosong:

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

Nama kolom yang merupakan kata khusus untuk 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. Berikut adalah contoh penggunaan instance Asset:

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

Daftar lengkap nama yang dicadangkan dibuat dalam modul generator gapic. Data ini juga dapat diakses 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 kolom

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

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 kolom pada pesan telah ditetapkan, meskipun ditetapkan ke nilai default.

Metode pesan Protobuf

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

# 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

Jika ada pertanyaan tentang perubahan ini atau masalah saat bermigrasi ke library versi terbaru, laporkan masalah di pelacak kami.