ข้อความ Protobuf

เวอร์ชัน 14.0.0 ของไลบรารีของไคลเอ็นต์ Python มีพารามิเตอร์การกำหนดค่าที่จำเป็นใหม่ที่เรียกว่า use_proto_plus ซึ่งระบุว่าคุณต้องการให้ไลบรารีแสดงผลข้อความ Proto-plus หรือข้อความ Protobuf โปรดดูรายละเอียดวิธีตั้งค่าพารามิเตอร์นี้ที่เอกสารการกำหนดค่า

ส่วนนี้จะอธิบายผลของประสิทธิภาพในการเลือกประเภทของข้อความที่จะใช้ ดังนั้นเราขอแนะนำให้คุณอ่านและทำความเข้าใจตัวเลือกต่างๆ เพื่อประกอบการตัดสินใจ อย่างไรก็ตาม หากต้องการอัปเกรดเป็นเวอร์ชัน 14.0.0 โดยไม่เปลี่ยนแปลงโค้ด ให้ตั้งค่า use_proto_plus เป็น True เพื่อไม่ให้การเปลี่ยนแปลงอินเทอร์เฟซเสียหาย

ข้อความ Proto-plus เทียบกับข้อความ Protobuf

ในเวอร์ชัน 10.0.0 ไลบรารีของไคลเอ็นต์ Python ได้ย้ายข้อมูลไปยังไปป์ไลน์ของโปรแกรมสร้างโค้ดใหม่ที่ผสานรวม Proto-plus เข้าด้วยกันเป็นวิธีปรับปรุงการยศาสตร์ของอินเทอร์เฟซข้อความ Protobuf โดยทำให้การทำงานเหมือนออบเจ็กต์ Python แบบเดิมมากขึ้น ข้อดีข้อเสียของการปรับปรุงนี้คือ Proto บวกเพิ่มค่าใช้จ่ายในการเพิ่มประสิทธิภาพ

ประสิทธิภาพของ Proto Plus

ประโยชน์สำคัญอย่างหนึ่งของ Proto-plus คือแปลงข้อความ มาพร้อมค่าเริ่มต้นและประเภทที่รู้จักกันดีเป็นประเภท Python ดั้งเดิมผ่านกระบวนการที่เรียกว่า type marshaling

การจัดรูปแบบจะเกิดขึ้นเมื่อมีการเข้าถึงช่องบนอินสแตนซ์ข้อความ Proto-plus โดยเฉพาะอย่างยิ่งเมื่อมีการอ่านหรือตั้งค่าช่อง เช่น ในคำนิยาม Protobuf

syntax = "proto3";

message Dog {
  string name = 1;
}

เมื่อแปลงคำจำกัดความนี้เป็นคลาส Proto+ แล้ว คลาสจะมีลักษณะดังนี้

import proto

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

จากนั้นคุณจะเริ่มต้นคลาส Dog และเข้าถึงช่อง name ได้เช่นเดียวกับออบเจ็กต์ Python อื่นๆ

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

เมื่ออ่านและตั้งค่าช่อง name ระบบจะแปลงค่าจากประเภท Python str แบบดั้งเดิมเป็นประเภท string เพื่อให้ค่าดังกล่าวเข้ากันได้กับรันไทม์ Protobuf

ในการวิเคราะห์ที่เราได้ดำเนินการนับตั้งแต่เปิดตัวเวอร์ชัน 10.0.0 เราพบว่าเวลาที่ใช้ในการแปลงประเภทเหล่านี้มีผลกระทบด้านประสิทธิภาพมากพอ จึงเป็นสิ่งสำคัญที่จะทำให้ผู้ใช้มีตัวเลือกในการใช้ข้อความ Protobuf

กรณีการใช้งานสำหรับข้อความ Proto-plus และ Protobuf

กรณีการใช้งานข้อความ Proto-plus
โปรโตคอล เนื่องจากมีการเปิดเผยออบเจ็กต์ 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 Ads

การเรียงลำดับไบต์

ข้อความ 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 ให้แปลงข้อความดังกล่าวเป็นข้อความ produf เพื่อใช้ตัวช่วย ดังนี้

ข้อความ 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)

Enum

Enum ที่ข้อความ Proto-plus แสดงถือเป็นอินสแตนซ์ประเภท enum แบบเนทีฟของ Python ดังนั้นจึงได้ใช้วิธีการอำนวยความสะดวกหลายวิธี

การดึงข้อมูลประเภท enum

เมื่อใช้เมธอด GoogleAdsClient.get_type เพื่อเรียก enum ข้อความที่แสดงจะแตกต่างไปเล็กน้อย โดยขึ้นอยู่กับว่าคุณใช้ข้อความ Proto-plus หรือข้อความ มาพร้อม "โปรโตคอล" เช่น

ข้อความ Proto-plus
val = client.get_type("CampaignStatusEnum").CampaignStatus.PAUSED
ข้อความ Protobuf
val = client.get_type("CampaignStatusEnum").PAUSED

เรามีแอตทริบิวต์ Convesion ในอินสแตนซ์ GoogleAdsClient ที่มีอินเทอร์เฟซที่สอดคล้องกันเพื่อช่วยให้คุณเรียก Enum ได้ง่ายขึ้น ไม่ว่าจะใช้ข้อความประเภทใดก็ตาม

val = client.enums.CampaignStatusEnum.PAUSED

การดึงข้อมูลค่า enum

บางครั้งการทราบค่าหรือรหัสช่องของ enum ที่ระบุก็มีประโยชน์ เช่น PAUSED ใน CampaignStatusEnum ตรงกับ 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))

การดึงข้อมูลชื่อ enum

บางครั้งการทราบชื่อของฟิลด์ enum ก็อาจเป็นประโยชน์ ตัวอย่างเช่น เมื่ออ่านออบเจ็กต์จาก API คุณอาจต้องการทราบว่าสถานะแคมเปญที่บ่งบอกตรงกับ 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+ โดยทั่วไปแล้ว ฟิลด์ที่ซ้ำจะเทียบเท่ากับรายการที่พิมพ์ ซึ่งหมายความว่าฟิลด์จะทำงานแทบจะเหมือนกับ list

ต่อท้ายฟิลด์สเกลาร์ที่ซ้ำกัน

เมื่อเพิ่มค่าลงในช่องประเภทสเกลที่ซ้ำกัน เช่น ช่อง string หรือ int64 อินเทอร์เฟซจะเหมือนกันโดยไม่คำนึงถึงประเภทข้อความ

ข้อความ Proto-plus
ad.final_urls.append("https://www.example.com")
ข้อความ Protobuf
ad.final_urls.append("https://www.example.com")

ซึ่งรวมถึงเมธอด list อื่นๆ ที่ใช้กันทั่วไปทั้งหมดด้วย เช่น extend

ข้อความ 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 เราขอแนะนำให้ใช้เมธอดตัวช่วย 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

รายการทั้งหมดของชื่อที่สงวนไว้จะสร้างขึ้นในโมดูล Gapic Generator เข้าถึงแบบเป็นโปรแกรมได้เช่นกัน

ก่อนอื่น ให้ติดตั้งโมดูลโดยทำดังนี้

python -m pip install gapic-generator

จากนั้นใน REPL หรือสคริปต์ Python

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())

เครื่องมือติดตามปัญหา

หากมีข้อสงสัยเกี่ยวกับการเปลี่ยนแปลงเหล่านี้หรือพบปัญหาในการย้ายข้อมูลไปยังไลบรารีเวอร์ชัน 14.0.0 โปรดแจ้งปัญหาในเครื่องมือติดตามของเรา