注意：這個網站已不適用。網站將在 2023 年 1 月 31 日後關閉，而流量會重新導向至 https://protobuf.dev。在此同時，系統只會將資料更新至 protobuf.dev。

Package google.protobuf

索引

不限

Any 包含任意序列化訊息，以及一個有關序列化訊息類型的網址。

JSON

Any 值的 JSON 表示法使用反序列化嵌入訊息的一般表示法，以及包含包含類型網址的額外欄位 @type。例子：

package google.profile;
message Person {
  string first_name = 1;
  string last_name = 2;
}

{
  "@type": "type.googleapis.com/google.profile.Person",
  "firstName": <string>,
  "lastName": <string>
}

如果內嵌的訊息類型是已知的，且具有自訂 JSON 表示法，系統就會嵌入該表示法，新增 value 欄位，除了 @type 欄位之外，還包含自訂 JSON。範例 (針對訊息 google.protobuf.Duration)：

{
  "@type": "type.googleapis.com/google.protobuf.Duration",
  "value": "1.212s"
}
欄位名稱 類型 說明
type_url string

內容/資源名稱，其內容會描述序列化訊息的類型。

如果網址使用 http、https 或無結構定義，則適用以下限制和解釋：

  • 如未提供結構定義，系統會採用 https。
  • 網址路徑的最後一個部分必須是該類型的完整名稱 (例如 path/google.protobuf.Duration)。
  • 網址上的 HTTP GET 必須採用二進位格式的 google.protobuf.Type 值，或是產生錯誤。
  • 應用程式可以根據網址快取查詢結果，或讓應用程式預先編譯為二進位檔，以避免任何查詢。因此，變更類型時必須保留二進位檔相容性。(使用版本類型名稱來管理破壞性變更)。

http、https (或空白的結構定義) 以外的結構定義可以與實作特定的語意搭配使用。
value bytes 必須是上述指定類型的有效序列化資料。

Api

API 是一種通訊協定緩衝區服務的輕量描述元。

欄位名稱 類型 說明
name string 這個 API 的完整名稱，包括套件名稱和 API 的簡易名稱。
methods Method 這個 API 的方法，按未指定順序排列。
options Option 附加至 API 的任何中繼資料。
version string

這個 API 的版本字串。指定時，必須採用 major-version.minor-version 的形式，如 1.10。如果省略次要版本，預設值為 0。如果整個版本欄位為空白，則主要版本會從套件名稱取得，如下所示。如果此欄位沒有內容，系統會驗證套件名稱中的版本是否與此處提供的內容一致。

版本管理架構使用語意化版本管理，主要版本編號表示破壞性變更，次要版本則是新增且非破壞性變更。這兩個版本編號都會向使用者提供不同版本的期望信號，請根據產品方案謹慎選擇。

主要版本也會反映在 API 的套件名稱中，且名稱必須以 v<major-version> 結尾，例如 google.feature.v1。如果是主要版本 0 和 1，則可省略後置字串。0 個主要版本只能用於實驗性 Google Analytics (分析) API。
source_context SourceContext 此訊息代表的通訊協定緩衝區服務來源內容。
mixins Mixin 包含的 API。詳情請參閱《Mixin》。
syntax Syntax 服務的來源語法。

BoolValue

bool的包裝訊息。

BoolValue 的 JSON 表示法是 JSON true 和 false。

欄位名稱 類型 說明
value bool 布林值。

BytesValue

bytes的包裝訊息。

BytesValue 的 JSON 表示法為 JSON 字串。

欄位名稱 類型 說明
value bytes 位元組值。

DoubleValue

double的包裝訊息。

DoubleValue 的 JSON 表示法為 JSON 號碼。

欄位名稱 類型 說明
value double 雙精度值。

時間長度

「時間長度」代表經過簽署的固定時間長度，代表以奈秒解析度為秒數和秒數的分數。不受任何日曆與概念影響，例如「日」或「月」。與時間戳記相關範圍約為 +-10,000 年。

範例 1：虛擬程式碼中兩個時間戳記的運算時間長度。

Timestamp start = ...;
Timestamp end = ...;
Duration duration = ...;

duration.seconds = end.seconds - start.seconds;
duration.nanos = end.nanos - start.nanos;

if (duration.seconds < 0 && duration.nanos > 0) {
  duration.seconds += 1;
  duration.nanos -= 1000000000;
} else if (duration.seconds > 0 && duration.nanos < 0) {
  duration.seconds -= 1;
  duration.nanos += 1000000000;
}

範例 2：透過虛擬程式碼計算時間戳記 + 持續時間的時間戳記。

Timestamp start = ...;
Duration duration = ...;
Timestamp end = ...;

end.seconds = start.seconds + duration.seconds;
end.nanos = start.nanos + duration.nanos;

if (end.nanos < 0) {
  end.seconds -= 1;
  end.nanos += 1000000000;
} else if (end.nanos >= 1000000000) {
  end.seconds += 1;
  end.nanos -= 1000000000;
}

Duration 的 JSON 表示法是以 String 結尾的 String，表示秒，前面加上秒，其中秒以分秒表示。

欄位名稱 類型 說明
seconds int64 時長的已簽署秒數。必須介於 -315,576,000,000 到 +315,576,000,000 (含) 之間。
nanos int32 以分鐘為單位的解析度，以一定比例呈現已取得的秒數。時間長度不到 1 秒的值為 seconds 的 0 欄位，以及正或負的 nanos 欄位。時間長度在一秒以上的值時，nanos 欄位的非零值必須與 seconds 欄位具有相同的符號。必須介於 -999,999,999 到 +999,999,999 之間 (含首尾值)。

空白

一般的空白訊息，可重複使用，避免在 API 中定義重複的空白訊息。常見的例子是將其做為 API 方法的要求或回應類型。例如：

service Foo {
  rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);
}

Empty 的 JSON 表示法是空的 JSON 物件 {}。

列舉

列舉類型定義。

欄位名稱 類型 說明
name string 列舉類型名稱。
enumvalue EnumValue 列舉值定義。
options Option 通訊協定緩衝區選項。
source_context SourceContext 來源內容。
syntax Syntax 來源語法。

EnumValue

列舉值定義。

欄位名稱 類型 說明
name string 列舉值名稱。
number int32 列舉值：
options Option 通訊協定緩衝區選項。

欄位

單一訊息類型欄位。

欄位名稱 類型 說明
kind Kind 欄位類型。
cardinality Cardinality 欄位基數。
number int32 欄位編號。
name string 欄位名稱。
type_url string 訊息或列舉類型的欄位類型網址，沒有配置。範例："type.googleapis.com/google.protobuf.Timestamp"。
oneof_index int32 Type.oneofs 中欄位類型的索引，適用於訊息或列舉類型。第一個類型的索引 1；0 表示類型不在清單中。
packed bool 是否使用替代接線線表示法。
options Option 通訊協定緩衝區選項。
json_name string 欄位 JSON 名稱。
default_value string 這個欄位預設值的字串值。僅限 Proto2 語法。

基數

欄位是否為選填、必要或重複欄位。

列舉值 說明
CARDINALITY_UNKNOWN 不明基數的欄位。
CARDINALITY_OPTIONAL 選填欄位。
CARDINALITY_REQUIRED 必填欄位。僅限 Proto2 語法。
CARDINALITY_REPEATED 重複欄位。

種類

基本欄位類型。

列舉值 說明
TYPE_UNKNOWN 欄位類型不明。
TYPE_DOUBLE 欄位類型為雙倍。
TYPE_FLOAT 欄位類型 float。
TYPE_INT64 欄位類型 int64。
TYPE_UINT64 欄位類型：uint64。
TYPE_INT32 欄位類型 int32。
TYPE_FIXED64 欄位類型固定：64。
TYPE_FIXED32 欄位類型固定 32：
TYPE_BOOL 欄位類型布林值。
TYPE_STRING 欄位類型字串。
TYPE_GROUP 欄位類型群組。僅限 Proto2 語法，且已淘汰。
TYPE_MESSAGE 欄位類型訊息。
TYPE_BYTES 欄位類型位元組。
TYPE_UINT32 欄位類型 uint32。
TYPE_ENUM 欄位類型列舉。
TYPE_SFIXED32 欄位類型 sfixed32。
TYPE_SFIXED64 欄位類型 sfixed64。
TYPE_SINT32 欄位類型 sint32。
TYPE_SINT64 欄位類型 sint64。

FieldMask

FieldMask 代表一組符號欄位欄位路徑，例如：

paths: "f.a"
paths: "f.b.d"

這裡 f 代表部分根訊息中的欄位，a 和 b 在 f 訊息中找到的欄位以及 d 在 f.b 訊息中找到的欄位。

欄位遮罩可用來指定應由 get 作業 (「投影」) 傳回或由更新作業修改的欄位欄位。欄位遮罩也包含自訂的 JSON 編碼 (請見下文說明)。

投影中的面膜

當 FieldMask 指定「投影」時，API 會篩選回應訊息 (或子訊息)，僅包含遮罩中指定的這些欄位。以這則「預先遮蓋」回應訊息為例：

f {
  a : 22
  b {
    d : 1
    x : 2
  }
  y : 13
}
z: 8

在套用上例中的遮罩後，API 回應將不會包含 x、y 或 z 欄位的特定值 (系統會將其值設為預設值，且在 proto text 輸出中予以忽略)：

f {
  a : 22
  b {
    d : 1
  }
}

欄位重複，不得在欄位遮罩的最後位置顯示。

如果 get 作業中沒有 FieldMask 物件，則作業會套用到所有欄位 (就像所有欄位的 FieldMask 都一樣)。

請注意，欄位遮罩不一定適用於頂層回應訊息。在 REST get 作業中，欄位遮罩會直接套用至回應，但在 REST 清單作業的情況下，遮罩也會套用至傳回資源清單中的每則訊息。如果是 REST 自訂方法，可使用其他定義。在 API 中，宣告的適用範圍和宣告都會清楚列出。在任何情況下，API 的行為都需要對傳回的資源/資源產生影響。

更新作業中的欄位遮罩

更新作業中的欄位遮罩會指定要將指定資源更新的欄位。此 API 只需要變更遮罩中指定的欄位值，其他欄位則保持不變。如果將資源傳入說明來描述更新的值，API 會忽略所有不在遮罩中的欄位值。

如要將欄位的值重設為預設值，該欄位必須存在於遮罩中，並設為指定資源中的預設值。因此，如要重設資源的所有欄位，請提供資源的預設例項，並設定遮罩中的所有欄位，或是按照下列說明提供遮罩。

如果更新時沒有任何欄位遮罩，作業會套用至所有欄位 (就像所有欄位的欄位遮罩一樣)。請注意，在結構定義演變時，這可能表示用戶端不知道，因此未填入要求的欄位會重設為預設值。如果這是不必要的行為，特定服務可能會要求用戶端一律指定欄位遮罩，否則會造成錯誤。

與 get 作業一樣，要求訊息中描述更新值的資源位置取決於作業種類。在任何情況下，欄位遮罩的效果都需要 API 予以尊重。

HTTP REST 的注意事項

使用欄位遮罩的更新作業 HTTP 種類必須設為 PATCH 而非 PUT，才符合 HTTP 語意 (PUT 只能用於完整更新)。

欄位遮罩的 JSON 編碼

在 JSON 中，欄位遮罩是以單一字串編碼，其中路徑會以逗號分隔。每個路徑中的欄位名稱都會轉換為低駝峰命名慣例。

舉例來說，請參考以下訊息宣告：

message Profile {
  User user = 1;
  Photo photo = 2;
}
message User {
  string display_name = 1;
  string address = 2;
}

在 proto 中，Profile 的欄位遮罩可能如下所示：

mask {
  paths: "user.display_name"
  paths: "photo"
}

在 JSON 中，相同的遮罩如下所示：

{
  mask: "user.displayName,photo"
}
欄位名稱 類型 說明
paths string 欄位遮罩路徑組合。

FloatValue

float的包裝訊息。

FloatValue 的 JSON 表示法為 JSON 號碼。

欄位名稱 類型 說明
value float 浮點值。

Int32Value

int32的包裝訊息。

Int32Value 的 JSON 表示法為 JSON 號碼。

欄位名稱 類型 說明
value int32 int32 的值。

Int64Value

int64的包裝訊息。

Int64Value 的 JSON 表示法為 JSON 字串。

欄位名稱 類型 說明
value int64 int64 值。

ListValue

ListValue 是重複值欄位的包裝函式。

ListValue 的 JSON 表示法為 JSON 陣列。

欄位名稱 類型 說明
values Value 動態輸入值的重複欄位。

方法

方法代表 API 的方法，

欄位名稱 類型 說明
name string 這個方法的簡單名稱。
request_type_url string 輸入訊息類型的網址。
request_streaming bool 如果為 true，系統會串流要求。
response_type_url string 輸出訊息類型的網址。
response_streaming bool 如為 true，則系統會串流回應。
options Option 附加至該方法的任何中繼資料。
syntax Syntax 這個方法的來源語法。

Mixin

宣告要納入此 API 的 API。納入的 API 必須重新宣告內含 API 的所有方法，但說明文件和選項會沿用如下：

  • 如果註解和空白字元移除後，已宣告方法的說明文件字串為空白，系統將沿用原始方法。

  • 系統會沿用每個在已宣告的方法中未設定的服務設定 (http、瀏覽權限) 的註解。

  • 如果繼承了 HTTP 註解，則會依照以下方式修改路徑模式：任何版本前置字串都會由包含 API 的版本加上 root 路徑 (如有指定)。

簡易混合型的範例：

package google.acl.v1;
service AccessControl {
  // Get the underlying ACL object.
  rpc GetAcl(GetAclRequest) returns (Acl) {
    option (google.api.http).get = "/v1/{resource=**}:getAcl";
  }
}

package google.storage.v2;
service Storage {
  //       rpc GetAcl(GetAclRequest) returns (Acl);

  // Get a data record.
  rpc GetData(GetDataRequest) returns (Data) {
    option (google.api.http).get = "/v2/{resource=**}";
  }
}

混合型設定範例：

apis:
- name: google.storage.v2.Storage
  mixins:
  - name: google.acl.v1.AccessControl

這個混合型結構表示 AccessControl 中的所有方法也會在 Storage 中宣告相同的名稱和要求/回應類型。說明文件和註解處理工具會在處理說明文件和註解之後看到有效的 Storage.GetAcl 方法，如下所示：

service Storage {
  // Get the underlying ACL object.
  rpc GetAcl(GetAclRequest) returns (Acl) {
    option (google.api.http).get = "/v2/{resource=**}:getAcl";
  }
  ...
}

請注意，路徑模式中的版本已從 v1 變更為 v2。

如果混合器中的 root 欄位已指定，則應為放置相對 HTTP 路徑的相對路徑。例子：

apis:
- name: google.storage.v2.Storage
  mixins:
  - name: google.acl.v1.AccessControl
    root: acls

這意味著下列繼承的 HTTP 註解：

service Storage {
  // Get the underlying ACL object.
  rpc GetAcl(GetAclRequest) returns (Acl) {
    option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";
  }
  ...
}
欄位名稱 類型 說明
name string 包含的 API 完整名稱。
root string 如果非空白指定了指定繼承 HTTP 路徑的路徑。

NullValue

NullValue 是單例列舉，代表 Value 類型聯集的空值。

NullValue 的 JSON 表示法是 JSON null。

列舉值 說明
NULL_VALUE 空值。

選項

通訊協定緩衝區選項，可附加到訊息、欄位、列舉等中。

欄位名稱 類型 說明
name string 選項的名稱。例如 "java_package"。
value Any 選項的值。例如 "com.google.protobuf"。

SourceContext

SourceContext 代表 protobuf 元素的來源相關資訊，例如其定義的檔案。

欄位名稱 類型 說明
file_name string 包含相關 protobuf 元素的 .proto 檔案路徑有效名稱。例如 "google/protobuf/source.proto"。

StringValue

string的包裝訊息。

StringValue 的 JSON 表示法為 JSON 字串。

欄位名稱 類型 說明
value string 字串值。

結構

Struct 代表結構化資料值，由可對應至動態輸入值的欄位組成。在部分語言中，Struct 可能支援原生表示法。舉例來說，在 JS 等指令碼語言中，結構表示為物件。該表示法的詳細資訊以及該語言的 proto 支援。

Struct 的 JSON 表示法為 JSON 物件。

欄位名稱 類型 說明
fields map<string, Value> 動態輸入值的對應。

語法

通訊協定緩衝區元素的定義語法。

列舉值 說明
SYNTAX_PROTO2 語法 proto2。
SYNTAX_PROTO3 語法 proto3。

時間戳記

時間戳記代表與任何時區或日曆無關的時間點，以 UTC 紀元時間 (奈秒) 的秒數或秒的分數表示。「編碼」日曆是「Google 日曆」的「Google 日曆」它進行編碼時，假設所有分鐘數都為 60 秒，也就是「記憶體秒數」為「雜訊」，以不需解釋秒資訊。範圍從 0001-01-01T00:00:00Z 到 9999-12-31T23:59:59.999999999Z。透過將該範圍限制在範圍之外，我們會確保使用者可以轉換 RFC 3339 日期字串。請參閱 https://www.ietf.org/rfc/rfc3339.txt。

範例 1：來自 POSIX time() 的運算時間戳記。

Timestamp timestamp;
timestamp.set_seconds(time(NULL));
timestamp.set_nanos(0);

範例 2：POSIX gettimeofday() 的運算時間戳記。

struct timeval tv;
gettimeofday(&tv, NULL);

Timestamp timestamp;
timestamp.set_seconds(tv.tv_sec);
timestamp.set_nanos(tv.tv_usec * 1000);

範例 3：從 Win32 GetSystemTimeAsFileTime() 計算時間戳記。

FILETIME ft;
GetSystemTimeAsFileTime(&ft);
UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime;

// A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z
// is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z.
Timestamp timestamp;
timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL));
timestamp.set_nanos((INT32) ((ticks % 10000000) * 100));

範例 4：從 Java System.currentTimeMillis() 計算時間戳記。

long millis = System.currentTimeMillis();

Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000)
    .setNanos((int) ((millis % 1000) * 1000000)).build();

範例 5：使用 Python 目前時間計算時間戳記。

now = time.time()
seconds = int(now)
nanos = int((now - seconds) * 10**9)
timestamp = Timestamp(seconds=seconds, nanos=nanos)
欄位名稱 類型 說明
seconds int64 代表自 Unix 紀元 1970-01-01T00:00:00Z 以分 UTC 時間的秒數。這個值必須介於 0001-01-01T00:00:00Z 到 9999-12-31T23:59:59Z (含) 之間。
nanos int32 以奈秒解析度為一秒的非負分數。具有分數的負第二個負數值仍須具有非負數的正負號 nanos 值。必須介於 0 到 999,999,999 之間 (含首尾值)。

類型

通訊協定緩衝區訊息類型。

欄位名稱 類型 說明
name string 完整訊息名稱。
fields Field 欄位清單。
oneofs string 此類型 oneof 定義中顯示的類型清單。
options Option 通訊協定緩衝區選項。
source_context SourceContext 來源內容。
syntax Syntax 來源語法。

UInt32Value

uint32的包裝訊息。

UInt32Value 的 JSON 表示法為 JSON 號碼。

欄位名稱 類型 說明
value uint32 uint32 值。

UInt64Value

uint64的包裝訊息。

UInt64Value 的 JSON 表示法為 JSON 字串。

欄位名稱 類型 說明
value uint64 uint64 值。

值

Value 表示動態輸入值，可以是空值、數字、字串、布林值、遞迴結構值或值清單。值的製作者應設定其中任何一個變數，如果沒有任何變化版本，就會發生錯誤。

Value 的 JSON 表示法為 JSON 值。

欄位名稱 類型 說明
欄位的值，只能填入下列其中一個值：
null_value NullValue 代表空值。
number_value double 代表雙精度值。請注意，嘗試對 NaN 或 Infinity 序列化序列化會導致錯誤。(我們無法像一般欄位一樣，將這些字串序列化為字串「NaN」或「Infinity」值，因為它們會剖析為 string_value，而不是數字_value)。
string_value string 代表字串值。
bool_value bool 表示布林值。
struct_value Struct 代表結構化值。
list_value ListValue 代表重複的 Value。