หน้านี้ได้รับการแปลโดย Cloud Translation API

ข้อความ 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-plus ทำให้เกิดโอเวอร์เฮดประสิทธิภาพ

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

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

การจัดรูปแบบจะเกิดขึ้นเมื่อมีการเข้าถึงช่องในอินสแตนซ์ข้อความ 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 ได้ตามที่ต้องการ ออบเจ็กต์ Python อื่นๆ:

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

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

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

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

กรณีการใช้งานข้อความ Proto-plus: Proto-plus มีการปรับปรุงด้านสรีรศาสตร์ในหลายๆ ด้าน จึงเหมาะอย่างยิ่งสำหรับการเขียนโค้ดที่บำรุงรักษาและอ่านได้ เนื่องจากจะเปิดเผย ออบเจ็กต์ Python แบบดั้งเดิมนั้นใช้งานและเข้าใจได้ง่ายกว่า
กรณีการใช้งานข้อความ Protobuf: ใช้ Protobufs สำหรับกรณีการใช้งานที่อ่อนไหวต่อประสิทธิภาพ โดยเฉพาะในแอป ที่ต้องประมวลผลรายงานขนาดใหญ่อย่างรวดเร็ว หรือสร้างคำขอเปลี่ยนแปลงด้วย การดำเนินการจำนวนมาก เช่น 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 แสดงถือเป็นอินสแตนซ์ของภาษา Python enum ดังนั้น สืบทอดวิธีการอำนวยความสะดวกหลายวิธี

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

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

ข้อความ Proto-plus

val = client.get_type("CampaignStatusEnum").CampaignStatus.PAUSED

ข้อความ Protobuf

val = client.get_type("CampaignStatusEnum").PAUSED

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

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 คุณอาจต้องทราบว่าแคมเปญมีสถานะใด 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")

ซึ่งรวมถึงเมธอด 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 เมธอด Helper ใน 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

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

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

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 ไปเป็นข้อความ produf ที่มีคู่กัน:

# 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 ของไลบรารี ปัญหาใน แท็กติดตาม