Protobuf 訊息

版本 14.0.0敬上 的 Python 用戶端程式庫導入了新的必要設定參數 稱為 use_proto_plus，用於指定是否要傳回程式庫 proto-plus 訊息或 protobuf 訊息。如要進一步瞭解 想知道如何設定此參數，請參閱設定文件。

本節說明選擇 Pod 的 使用訊息，因此建議您詳閱並瞭解 讓您做出明智的決定不過，如果您想要 不必變更程式碼，升級至 14.0.0 版即可 use_proto_plus 至 True，以免破壞介面變更。

Proto Plus 與 protobuf 訊息

在 10.0.0 版中，Python 用戶端程式庫遷移至新的程式碼產生器 經整合的 proto-plus 計劃 通訊協定緩衝區訊息介面的人體工學 例如原生 Python 物件這項改進的缺點是， 會產生效能負擔

卓越效能

proto-plus 的主要優點之一是能將 protobuf 訊息 和常見類型 透過名為 type 的處理程序 管理

在 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 欄位時，這個值會從原生端轉換 設為 string 類型的 Python str 類型 該值與 protobuf 執行階段相容。

自 10.0.0 版發布以來，我們進行了一項分析 發現這類轉換花費的時間夠長 讓使用者選擇使用 protobuf 訊息。

proto-plus 和 protobuf 訊息的用途

Proto Plus 訊息用途

相較於 protobuf 訊息，Proto Plus 提供了多項符合人體工學的改進項目。 因此適合用於編寫可維護且可讀的程式碼。由於 Pod 而且更容易使用及理解。

Protobuf 訊息用途

使用通訊協定緩衝區處理著重效能的用途 (尤其是針對應用程式) 以便快速處理大型報表，或者使用 執行大量作業，例如有 BatchJobService 或 OfflineUserDataJobService。

動態變更訊息類型

為應用程式選取適當的訊息類型後，您可能會看到 而您需要針對特定工作流程使用其他類型。在這個例子中 只要使用 用戶端程式庫使用上述相同的 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 訊息時，請轉換為 protobuf 訊息使用輔助程式：

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)

列舉

proto-plus 訊息公開的列舉是 Python 原生應用程式 enum 類型， 繼承許多便利的方法

列舉類型擷取

使用 GoogleAdsClient.get_type 方法擷取列舉時，訊息 視您使用 IP 位址時的狀態而定 proto-plus 或 protobuf 訊息。例如：

Proto Plus 訊息

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

Protobuf 訊息

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

為了簡化擷取列舉的流程，我們在 GoogleAdsClient 執行個體擁有一致的介面 (無論何者為何) 你使用的訊息類型：

val = client.enums.CampaignStatusEnum.PAUSED

擷取列舉值

有時瞭解指定列舉的值或欄位 ID 有時會很實用 例如，CampaignStatusEnum 上的 PAUSED 對應 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))

列舉名稱擷取

有時候，瞭解列舉欄位的名稱會有幫助。舉例來說 讀取 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 幾乎相同。

附加到重複的純量欄位

將值新增至重複的純量時 type 欄位，例如 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)

空白郵件欄位

設定空白訊息欄位的程序，並不會改變 訊息類型您只要將空白訊息複製到欄位中 一些問題。請參閱「郵件複製」一節和「Empty 郵件」 欄位指南。以下範例將說明 如何設定空白訊息欄位：

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

保留字詞的欄位名稱

使用 proto-plus 訊息時，欄位名稱會自動顯示 。以下是 使用 Asset 執行個體的範例：

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

完整的保留清單 名稱 是由宇宙構成 產生器模組。可以 也可透過程式存取

首先，請安裝模組：

python -m pip install gapic-generator

接著在 Python REPL 或指令碼中：

import gapic.utils
print(gapic.utils.reserved_names.RESERVED_NAMES)

注意： 以保留字詞名稱做為欄位的擴增功能不會影響 GAQL 查詢。因此，如果要求 Search 中的 Asset.type 欄位或 SearchStream 要求，請勿在查詢字串中加入結尾的底線。

欄位是否存在

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

通訊協定緩衝區 Message敬上 類別介面具有 HasField 方法，可判斷 訊息已被設定，即使原為預設值也一樣。

Protobuf 訊息方法

protobuf 訊息介麵包含一些便利的方法， 也就是 proto-plus 介面的一部分；但只要透過 Google Cloud 控制台 將 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())

Issue Tracker

如果您對本次異動有任何疑問，或將資料遷移至 Google 帳戶時遇到任何問題， 程式庫 14.0.0 版本，請 問題 追蹤器