Thông báo Protobuf

Với tham số cấu hình use_proto_plus, bạn có thể chỉ định xem bạn muốn thư viện trả về thông báo proto-plus hay thông báo protobuf. Để biết thông tin chi tiết về cách đặt thông số này, hãy xem tài liệu cấu hình.

Phần này mô tả những tác động đến hiệu suất của từng lựa chọn để bạn có thể chọn phương pháp phù hợp nhất cho ứng dụng của mình.

Thông báo proto-plus so với thông báo protobuf

Pipeline công cụ tạo mã tích hợp proto-plus như một cách để cải thiện tính công thái học của giao diện thông báo protobuf bằng cách làm cho các thông báo này hoạt động giống như các đối tượng Python tiêu chuẩn. Tuy nhiên, điều này có nghĩa là việc sử dụng proto-plus sẽ làm tăng chi phí hiệu suất.

Hiệu suất Proto-plus

Một trong những lợi ích cốt lõi của proto-plus là chuyển đổi thông báo protobuf và các loại phổ biến thành các loại Python tích hợp thông qua một quy trình gọi là phân loại theo kiểu.

Quá trình chuyển đổi xảy ra khi một trường được truy cập trên một phiên bản thông báo proto-plus, cụ thể là khi một trường được đọc hoặc đặt, ví dụ: trong một định nghĩa protobuf:

syntax = "proto3";

message Dog {
  string name = 1;
}

Khi được chuyển đổi thành một lớp proto-plus, định nghĩa này sẽ có dạng như sau:

import proto


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

Sau đó, bạn có thể khởi chạy lớp Dog và truy cập vào trường name của lớp này như mọi đối tượng Python khác:

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

Khi đọc và thiết lập trường name, giá trị sẽ được chuyển đổi từ loại str tích hợp sẵn của Python sang loại string để giá trị tương thích với thời gian chạy protobuf.

Thời gian thực hiện các lượt chuyển đổi loại này có tác động đủ lớn đến hiệu suất để bạn quyết định, dựa trên nhu cầu của ứng dụng, có nên sử dụng thông báo proto-plus hay protobuf hay không.

Các trường hợp sử dụng cho proto-plus và thông báo protobuf

Các trường hợp sử dụng thông báo Proto-plus

Proto-plus mang đến một số điểm cải tiến về tính công thái học so với các thông báo protobuf, vì vậy, chúng rất phù hợp để viết mã có thể duy trì và dễ đọc. Vì các đối tượng này hiển thị các đối tượng Python tiêu chuẩn, nên chúng dễ sử dụng và dễ hiểu hơn.

Các trường hợp sử dụng thông báo Protobuf

Sử dụng protobuf cho các trường hợp sử dụng nhạy cảm về hiệu suất, đặc biệt là trong những ứng dụng cần xử lý nhanh các báo cáo lớn hoặc tạo yêu cầu biến đổi với số lượng lớn các thao tác, chẳng hạn như với BatchJobService hoặc OfflineUserDataJobService.

Chuyển đổi linh hoạt các loại thông báo

Sau khi chọn loại thông báo phù hợp cho ứng dụng, bạn có thể thấy rằng bạn cần sử dụng loại thông báo khác cho một quy trình cụ thể. Trong trường hợp này, bạn có thể chuyển đổi giữa hai loại một cách linh hoạt bằng cách sử dụng các tiện ích do thư viện ứng dụng cung cấp. Sử dụng cùng một lớp thông báo Dog như trước:

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)

Sự khác biệt về giao diện thông báo Protobuf

Giao diện proto-plus được ghi lại chi tiết và các phần sau đây nêu bật những điểm khác biệt chính ảnh hưởng đến các trường hợp sử dụng phổ biến cho thư viện ứng dụng Google Ads.

Chuyển đổi tuần tự theo byte

Thông báo proto-plus

serialized = type(campaign).serialize(campaign)
deserialized = type(campaign).deserialize(serialized)

Thông báo Protobuf

serialized = campaign.SerializeToString()
deserialized = campaign.FromString(serialized)

Chuyển đổi tuần tự JSON

Thông báo proto-plus

serialized = type(campaign).to_json(campaign)
deserialized = type(campaign).from_json(serialized)

Thông báo Protobuf

from google.protobuf.json_format import MessageToJson, Parse

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

Mặt nạ trường

Phương thức trợ giúp mặt nạ trường do api-core cung cấp được thiết kế để sử dụng các thực thể thông báo protobuf. Khi sử dụng thông báo proto-plus, hãy chuyển đổi thông báo đó thành thông báo protobuf để sử dụng trình trợ giúp:

Thông báo 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)

Thông báo Protobuf

from google.api_core.protobuf_helpers import field_mask

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

Enum

Các enum do thông báo proto-plus hiển thị là các thực thể thuộc loại enum tích hợp của Python và do đó kế thừa một số phương thức thuận tiện.

Truy xuất loại enum

Khi sử dụng phương thức GoogleAdsClient.get_type để truy xuất enum, các thông báo được trả về sẽ hơi khác nhau, tuỳ thuộc vào việc bạn đang sử dụng thông báo proto-plus hay protobuf. Ví dụ:

Thông báo proto-plus

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

Thông báo Protobuf

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

Để đơn giản hoá việc truy xuất enum, có một thuộc tính tiện lợi trên các thực thể GoogleAdsClient có giao diện nhất quán bất kể bạn đang dùng loại thông báo nào:

val = client.enums.CampaignStatusEnum.PAUSED

Truy xuất giá trị enum

Đôi khi, bạn nên biết giá trị hoặc mã nhận dạng trường của một enum nhất định, ví dụ: PAUSED trên CampaignStatusEnum tương ứng với 3:

Thông báo proto-plus

campaign = client.get_type("Campaign")
campaign.status = client.enums.CampaignStatusEnum.PAUSED
# To read the value of campaign status
print(campaign.status.value)

Thông báo 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"))

Truy xuất tên enum

Đôi khi, bạn nên biết tên của một trường enum. Ví dụ: khi đọc các đối tượng từ API, bạn có thể muốn biết trạng thái chiến dịch nào tương ứng với số nguyên 3:

Thông báo proto-plus

campaign = client.get_type("Campaign")
campaign.status = client.enums.CampaignStatusEnum.PAUSED
# To read the name of campaign status
print(campaign.status.name)

Thông báo 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))

Các trường lặp lại

Như mô tả trong tài liệu proto-plus, các trường lặp lại thường tương đương với danh sách được nhập, tức là chúng hoạt động gần như giống hệt với list.

Thêm giá trị vào các trường vô hướng lặp lại

Khi thêm giá trị vào các trường loại vô hướng lặp lại, ví dụ: trường string hoặc int64, giao diện sẽ giống nhau bất kể loại thông báo:

Thông báo proto-plus

ad.final_urls.append("https://www.example.com")

Thông báo Protobuf

ad.final_urls.append("https://www.example.com")

Điều này cũng áp dụng cho tất cả các phương thức list phổ biến khác, chẳng hạn như extend:

Thông báo proto-plus

ad.final_urls.extend(
    ["https://www.example.com", "https://www.example.com/2"]
)

Thông báo Protobuf

ad.final_urls.extend(
    ["https://www.example.com", "https://www.example.com/2"]
)

Thêm các loại thông báo vào các trường lặp lại

Nếu trường lặp lại không phải là kiểu vô hướng, thì hành vi khi thêm các trường đó vào trường lặp lại sẽ hơi khác:

Thông báo proto-plus

frequency_cap = client.get_type("FrequencyCapEntry")
frequency_cap.cap = 100
campaign.frequency_caps.append(frequency_cap)

Thông báo Protobuf

# The add method initializes a message and adds it to the repeated field
frequency_cap = campaign.frequency_caps.add()
frequency_cap.cap = 100

Chỉ định các trường lặp lại

Đối với cả các trường lặp lại vô hướng và không vô hướng, bạn có thể chỉ định danh sách cho trường theo nhiều cách:

Thông báo proto-plus

# In proto-plus it's possible to use assignment.
urls = ["https://www.example.com"]
ad.final_urls = urls

Thông báo 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

Tin nhắn trống

Đôi khi, bạn nên biết liệu một thực thể thông báo có chứa thông tin nào hay không hoặc có bất kỳ trường nào được đặt hay không.

Thông báo proto-plus

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

Thông báo Protobuf

is_empty = campaign.ByteSize() == 0

Sao chép tin nhắn

Đối với cả thông báo proto-plus và protobuf, hãy sử dụng phương thức hỗ trợ copy_from trên GoogleAdsClient:

client.copy_from(campaign, other_campaign)

Trường nội dung trống

Quy trình thiết lập các trường thông báo trống là như nhau, bất kể loại thông báo mà bạn đang sử dụng. Bạn sao chép một tin nhắn trống vào trường có vấn đề. Xem phần Nội dung tin nhắn cũng như hướng dẫn về Trường tin nhắn trống. Ví dụ sau đây cho thấy cách thiết lập một trường thông báo trống:

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

Tên trường là các từ dành riêng

Khi sử dụng thông báo proto-plus, tên trường sẽ tự động xuất hiện với dấu gạch dưới ở cuối nếu tên đó cũng là một từ dành riêng trong Python. Ví dụ sau đây minh hoạ cách hoạt động với một thực thể Asset:

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

Danh sách đầy đủ các tên dành riêng được tạo trong mô-đun trình tạo gapic. Bạn cũng có thể truy cập vào trang này theo phương thức lập trình.

Trước tiên, hãy cài đặt mô-đun:

python -m pip install gapic-generator

Sau đó, trong một REPL hoặc tập lệnh Python:

import gapic.utils

print(gapic.utils.reserved_names.RESERVED_NAMES)

Mức độ hiện diện tại địa điểm

Vì các trường trên các thực thể thông báo protobuf có giá trị mặc định, nên không phải lúc nào bạn cũng biết được liệu một trường đã được đặt hay chưa.

Thông báo proto-plus

# Use the "in" operator.
has_field = "name" in campaign

Thông báo Protobuf

campaign = client.get_type("Campaign")
# Determines whether "name" is set and not just an empty string.
campaign.HasField("name")

Giao diện lớp Message protobuf có một phương thức HasField để xác định xem một trường con, trường oneof hoặc trường vô hướng optional trên một thông báo đã được đặt hay chưa, ngay cả khi trường đó được đặt thành giá trị mặc định. (Việc gọi HasField trên các trường vô hướng không bắt buộc trong proto3 sẽ làm tăng ValueError.)

Phương thức thông báo Protobuf

Giao diện thông báo protobuf bao gồm một số phương thức tiện lợi không thuộc giao diện proto-plus; tuy nhiên, bạn có thể truy cập vào các phương thức này bằng cách chuyển đổi thông báo proto-plus thành thông báo protobuf tương ứng:

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

Công cụ theo dõi lỗi

Nếu bạn có thắc mắc về những thay đổi này hoặc gặp vấn đề khi di chuyển sang phiên bản mới nhất của thư viện, hãy gửi vấn đề trên trình theo dõi lỗi.