Protobuf 訊息

Python 用戶端程式庫的 14.0.0 版本推出了名為 use_proto_plus 的新必要設定參數，用於指定您要程式庫傳回 proto-plus 訊息或 protobuf 訊息。如要進一步瞭解如何設定此參數，請參閱設定文件。

本節說明選擇要使用的訊息類型對效能的影響，因此建議您詳閱並瞭解各種選項，再做出明智的決定。不過，如果您想在不變更程式碼的情況下升級至 14.0.0 版，可以將 use_proto_plus 設為 True，以免破壞介面變更。

Proto-plus 與 protobuf 訊息

在 10.0.0 版中，Python 用戶端程式庫已遷移至新的程式碼產生器管道。這個管道整合了 proto-plus，目的是透過使其行為更像原生 Python 物件，改善 protobuf 訊息介面的人體工學。這項改善的缺點是，proto-Plus 會帶來效能負擔。

Proto Plus 效能

proto-plus 的核心優點之一，就是會透過名為類型管理的程序，將protobuf 訊息和已知類型轉換為原生 Python 類型。

破壞性會發生在

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 發布以來，我們進行分析時，我們發現執行這些類型轉換的時間會大幅影響效能，因此請務必為使用者提供使用 protobuf 訊息的選項。

proto-plus 和 protobuf 訊息的用途

Proto Plus 訊息用途

Proto Plus 針對 protobuf 訊息提供了多項人體工學改善，因此非常適合用於編寫可維護且容易閱讀的程式碼。這些類別會公開原生 Python 物件，因此更容易使用及理解。

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 方法擷取列舉時，根據您使用的是 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 讀取物件時，您可能會想瞭解整合 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 訊息，建議您對 GoogleAdsClient 使用 copy_from 輔助方法：

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

接著在 Python REPL 或指令碼中：

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

Issue tracker

如果對這些變更有任何疑問，或無法順利遷移至程式庫 14.0.0 版本，請透過我們的追蹤工具回報問題。