หมายเหตุ: เว็บไซต์นี้เลิกใช้งานแล้ว เราจะปิดให้บริการหลังจากวันที่ 31 มกราคม 2023 และการเข้าชมจะเปลี่ยนเส้นทางไปยังเว็บไซต์ใหม่ที่ https://protobuf.dev ในระหว่างนี้ระบบจะอัปเดตไปยัง protobuf.dev เท่านั้น

Package google.protobuf

ดัชนี

ตามแต่ละประเทศ

Any มีข้อความต่อเนื่องตามลําดับที่กําหนดเองพร้อม URL ที่อธิบายประเภทของข้อความที่มีการจัดเรียง

JSON

การแสดงค่า JSON ของค่า Any จะใช้การนําเสนอข้อความที่ฝังและทําการถอดรหัสตามปกติ โดยมีช่อง @type เพิ่มเติมซึ่งมี URL ของประเภท เช่น

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 ที่มี JSON ที่กําหนดเองนอกเหนือจากช่อง @type ตัวอย่าง (สําหรับข้อความ google.protobuf.Duration):

{
  "@type": "type.googleapis.com/google.protobuf.Duration",
  "value": "1.212s"
}
ชื่อช่อง ประเภท คำอธิบาย
type_url string

URL/ชื่อทรัพยากรที่เนื้อหาอธิบายประเภทของข้อความที่หมายเลขซีเรียล

ข้อจํากัดและการตีความต่อไปนี้มีผลกับ URL ที่ใช้สคีมา http, https หรือไม่มีสคีมา

  • หากไม่ได้ระบุสคีมา ระบบจะถือว่า https
  • กลุ่มสุดท้ายของเส้นทาง URL ต้องแสดงชื่อที่สมบูรณ์ในประเภท (เช่น path/google.protobuf.Duration)
  • HTTP GET บน URL ต้องแสดงผลค่า google.protobuf.Type ในรูปแบบไบนารี หรือสร้างข้อผิดพลาด
  • แอปพลิเคชันได้รับอนุญาตให้แคชผลการค้นหาตาม URL หรือให้มีการคอมไพล์ล่วงหน้าเป็นไบนารีเพื่อหลีกเลี่ยงการค้นหาใดๆ ดังนั้น จึงต้องมีความเข้ากันได้แบบไบนารีกับการเปลี่ยนแปลงประเภท (ใช้ชื่อประเภทที่มีเวอร์ชันเพื่อจัดการการเปลี่ยนแปลงที่ส่งผลกับส่วนอื่นในระบบ)

สคีมาอื่นที่ไม่ใช่ 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 รายการต้องใช้สําหรับ API การทดสอบที่ไม่ใช่ GA เท่านั้น

source_context SourceContext บริบทต้นทางสําหรับบริการบัฟเฟอร์โปรโตคอลที่แสดงโดยข้อความนี้
mixins Mixin รวม API ดูMixin
syntax Syntax ไวยากรณ์แหล่งที่มาของบริการ

ค่าบูลีน

Wrapper ของข้อความสําหรับ bool

การแสดง JSON ของ BoolValue คือ JSON true และ false

ชื่อช่อง ประเภท คำอธิบาย
value bool ค่าบูลีน

ค่าไบต์

Wrapper ของข้อความสําหรับ bytes

การแสดง JSON ของ BytesValue คือสตริง JSON

ชื่อช่อง ประเภท คำอธิบาย
value bytes ค่าไบต์

ค่า Double

Wrapper ของข้อความสําหรับ double

การแสดง JSON ของ DoubleValue คือหมายเลข JSON

ชื่อช่อง ประเภท คำอธิบาย
value double ค่า Double

ระยะเวลา

ระยะเวลาหมายถึงช่วงเวลาที่ยาวและคงที่ที่ลงนามแล้ว ซึ่งแสดงเป็นวินาทีและเสี้ยววินาทีที่ความละเอียดนาโนวินาที ไม่เกี่ยวข้องกับปฏิทินและแนวคิดต่างๆ เช่น "วัน" หรือ "เดือน" ค่านี้จะเกี่ยวข้องกับการประทับเวลาโดยการประทับเวลาระหว่างค่า "การประทับเวลา" 2 ค่าเป็น "ระยะเวลา" และสามารถเพิ่มหรือลบการประทับเวลาได้ ช่วงโดยประมาณคือ +-10,000 ปี

ตัวอย่างที่ 1: ระยะเวลาประมวลผลจากการประทับเวลา 2 ครั้งในโค้ดเทียม

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: Compute Timestamp จากการประทับเวลา + ระยะเวลาในโค้ดเทียม

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;
}

การแทน JSON สําหรับ Duration คือ String ที่ลงท้ายด้วย s เพื่อระบุวินาทีและอยู่ข้างหน้าด้วยจํานวนวินาที โดยมีนาโนวินาทีแสดงเป็นเศษส่วนเป็นวินาที

ชื่อช่อง ประเภท คำอธิบาย
seconds int64 วินาทีที่ลงนามของระยะเวลา ต้องมีค่าตั้งแต่ -315,576,000,000 ถึง +315,576,000,000
nanos int32 เศษของวินาทีที่ลงนามที่ความละเอียดระดับนาโนวินาทีของช่วงเวลา ระยะเวลาน้อยกว่า 1 วินาทีจะแสดงด้วยช่อง seconds จํานวน 0 ช่องและช่อง nanos เป็นบวกหรือลบ สําหรับระยะเวลา 1 วินาทีขึ้นไป ค่าที่ไม่ใช่ 0 สําหรับช่อง nanos ต้องเป็นเครื่องหมายเดียวกับช่อง seconds ต้องมีค่าตั้งแต่ -999,999,999 ถึง +999,999,999

ว่าง

ข้อความทั่วไปทั่วไปที่นํามาใช้ซ้ําได้เพื่อหลีกเลี่ยงการกําหนดข้อความว่างที่ซ้ํากันใน API ตัวอย่างทั่วไปคือการใช้เป็นคําขอหรือประเภทการตอบกลับของเมธอด API ตัวอย่างเช่น

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

การแสดง JSON ของ Empty เป็นออบเจ็กต์ JSON ที่ว่างเปล่า {}

ค่าแจกแจง

คําจํากัดความของประเภท Enum

ชื่อช่อง ประเภท คำอธิบาย
name string ชื่อประเภท Enum
enumvalue EnumValue คําจํากัดความของค่า Enum
options Option ตัวเลือกบัฟเฟอร์โปรโตคอล
source_context SourceContext บริบทต้นทาง
syntax Syntax ไวยากรณ์ต้นทาง

ค่า Enum

คําจํากัดความของค่า Enum

ชื่อช่อง ประเภท คำอธิบาย
name string ชื่อค่า Enum
number int32 หมายเลขค่า Enum
options Option ตัวเลือกบัฟเฟอร์โปรโตคอล

ช่อง

ช่องเดียวของประเภทข้อความ

ชื่อช่อง ประเภท คำอธิบาย
kind Kind ประเภทของช่อง
cardinality Cardinality จํานวนสมาชิกในเซ็ตของช่อง
number int32 หมายเลขช่อง
name string ชื่อช่อง
type_url string URL ของประเภทช่องที่ไม่มีรูปแบบสําหรับประเภทข้อความหรือการแจกแจง ตัวอย่าง: "type.googleapis.com/google.protobuf.Timestamp"
oneof_index int32 ดัชนีประเภทช่องใน Type.oneofs สําหรับประเภทข้อความหรือการแจกแจง ประเภทแรกมีดัชนี 1 และศูนย์หมายถึงประเภทนั้นไม่อยู่ในรายการ
packed bool จะใช้การแสดงแทนแบบใช้บรรจุภัณฑ์อื่นหรือไม่
options Option ตัวเลือกบัฟเฟอร์โปรโตคอล
json_name string ชื่อ JSON ของช่อง
default_value string ค่าสตริงของค่าเริ่มต้นของช่องนี้ ไวยากรณ์ Proto2 เท่านั้น

จำนวนสมาชิกในเซ็ต

ช่องเป็นแบบไม่บังคับ ต้องกรอก หรือกําหนดให้ซ้ํา

ค่า Enum คำอธิบาย
CARDINALITY_UNKNOWN สําหรับช่องที่มีจํานวนสมาชิกในเซ็ตที่ไม่รู้จัก
CARDINALITY_OPTIONAL สําหรับช่องที่ไม่บังคับ
CARDINALITY_REQUIRED สําหรับช่องที่ต้องระบุ ไวยากรณ์ Proto2 เท่านั้น
CARDINALITY_REPEATED สําหรับช่องที่ซ้ํา

ชนิด

ประเภทช่องพื้นฐาน

ค่า Enum คำอธิบาย
TYPE_UNKNOWN ไม่รู้จักประเภทช่อง
TYPE_DOUBLE ประเภทช่องคู่
TYPE_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 Enum ของประเภทช่อง
TYPE_SFIXED32 ประเภทช่อง sfixed32
TYPE_SFIXED64 ประเภทช่อง sfixed64
TYPE_SINT32 ประเภทช่อง sint32
TYPE_SINT64 ประเภทช่อง sint64

มาส์กหน้ากาก

FieldMask แสดงถึงชุดเส้นทางช่องสัญลักษณ์ เช่น

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

ในที่นี้ f จะแสดงช่องในข้อความราก ช่อง a และ b ในข้อความที่พบใน f รวมถึงช่อง d ที่พบในข้อความ f.b

มาสก์ช่องใช้เพื่อระบุช่องย่อยที่ควรจะแสดงโดยการดําเนินการดาวน์โหลด (การคาดการณ์) หรือแก้ไขโดยการดําเนินการอัปเดต นอกจากนี้ มาสก์ช่องยังมีการเข้ารหัส JSON ที่กําหนดเองด้วย (ดูด้านล่าง)

มาสก์ฟิลด์ในการคาดการณ์

เมื่อ FieldMask ระบุการคาดคะเน API จะกรองข้อความตอบกลับ (หรือข้อความย่อย) เพื่อแสดงเฉพาะช่องที่ระบุไว้ในมาสก์ ลองพิจารณาข้อความตอบกลับ "การมาสก์"

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

หลังจากใช้มาสก์ในตัวอย่างก่อนหน้านี้แล้ว การตอบกลับ API จะไม่มีค่าเฉพาะสําหรับช่อง x, y หรือ z (ค่าจะแสดงเป็นค่าเริ่มต้น และไม่แสดงในเอาต์พุตข้อความต้นแบบ) ดังนี้

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

ไม่อนุญาตให้มีช่องที่ซ้ํา ยกเว้นในตําแหน่งสุดท้ายของมาสก์ช่อง

หากไม่มีออบเจ็กต์ FieldMask อยู่ในการดําเนินการรับ การดําเนินการจะมีผลกับทุกช่อง (เหมือนกับว่าได้ระบุ FieldMask ของช่องทั้งหมด)

โปรดทราบว่ามาสก์ช่องไม่จําเป็นต้องใช้กับข้อความการตอบกลับระดับบนสุดเสมอไป ในกรณีที่มีการดําเนินการ REST ระบบจะมาสก์มาสก์โดยตรงกับการตอบกลับ แต่ในกรณีที่ดําเนินการรายการ REST มาสก์จะมีผลกับแต่ละข้อความในรายการทรัพยากรที่แสดงแทน ในกรณีของเมธอด REST ที่กําหนดเอง อาจมีการใช้คําจํากัดความอื่นๆ อยู่ ในกรณีที่มาสก์มีผลมีการระบุไว้อย่างชัดเจนร่วมกับการประกาศใน API ไม่ว่าในกรณีใดก็ตาม ผลกระทบต่อทรัพยากร/ทรัพยากรที่ส่งคืนจะเป็นลักษณะการทํางานสําหรับ API

มาสก์ช่องในการดําเนินการอัปเดต

มาสก์ของช่องในการดําเนินการอัปเดตจะระบุช่องของทรัพยากรเป้าหมายที่จะอัปเดต ต้องใช้ API เพื่อเปลี่ยนเฉพาะค่าของช่องที่ระบุไว้ในมาสก์และปล่อยช่องอื่นๆ ไว้เหมือนเดิม หากมีการส่งทรัพยากรเพื่ออธิบายค่าที่อัปเดตแล้ว API จะไม่สนใจค่าของช่องทั้งหมดที่ไม่ครอบคลุมการมาสก์

หากต้องการรีเซ็ตค่าในช่องเป็นค่าเริ่มต้น ช่องต้องอยู่ในมาสก์และตั้งค่าเป็นค่าเริ่มต้นในทรัพยากรที่ระบุ ดังนั้น หากต้องการรีเซ็ตช่องทั้งหมดของทรัพยากร ให้ระบุอินสแตนซ์เริ่มต้นของทรัพยากรและตั้งค่าช่องทั้งหมดในมาสก์ หรืออย่ามาสก์มาสก์ตามที่อธิบายไว้ด้านล่าง

หากไม่มีการอัปเดตมาสก์ของช่อง การดําเนินการจะมีผลกับทุกช่อง (เช่น โดยระบุมาสก์ของช่องทั้งหมด) โปรดทราบว่าเมื่อมีวิวัฒนาการของสคีมาอาจหมายความว่าช่องที่ลูกค้าไม่รู้จัก แล้วระบบจึงไม่ได้กรอกคําขอเป็นค่าเริ่มต้น หากนี่เป็นลักษณะการทํางานที่ไม่พึงประสงค์ บริการหนึ่งๆ อาจต้องการให้ลูกค้าระบุมาสก์ของช่องเสมอ ซึ่งจะทําให้เกิดข้อผิดพลาดหากไม่ใช่

เช่นเดียวกับการดําเนินการ ตําแหน่งทรัพยากรที่อธิบายค่าที่อัปเดตแล้วในข้อความคําขอจะขึ้นอยู่กับประเภทของการดําเนินการ ไม่ว่ากรณีใด เอฟเฟกต์ API มาสก์มาสก์จะต้องทําตาม

ข้อควรพิจารณาสําหรับ HTTP REST

ประเภท HTTP ของการดําเนินการอัปเดตที่ใช้มาสก์ของช่องต้องตั้งค่าเป็น PWatch แทน PUT เพื่อให้สอดคล้องกับความหมาย HTTP (PUT ต้องใช้สําหรับการอัปเดตแบบเต็มเท่านั้น)

การเข้ารหัส JSON ของมาสก์ช่อง

ใน JSON มาสก์ของช่องจะเข้ารหัสเป็นสตริงเดียวโดยคั่นด้วยคอมมา ชื่อช่องในเส้นทางแต่ละรายการจะแปลงเป็น/จากรูปแบบการตั้งชื่ออูฐล่าง

ลองดูตัวอย่างการประกาศข้อความต่อไปนี้

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

ในโมเดลหน้ากากมาสก์สําหรับ Profile อาจมีลักษณะเช่นนี้

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

ใน JSON มาสก์เดิมจะแสดงเป็นด้านล่าง

{
  mask: "user.displayName,photo"
}
ชื่อช่อง ประเภท คำอธิบาย
paths string ชุดเส้นทางมาสก์ช่อง

ค่าทศนิยม

Wrapper ของข้อความสําหรับ float

การแสดง JSON ของ FloatValue คือหมายเลข JSON

ชื่อช่อง ประเภท คำอธิบาย
value float ค่าทศนิยม

ค่า Int32

Wrapper ของข้อความสําหรับ int32

การแสดง JSON ของ Int32Value คือหมายเลข JSON

ชื่อช่อง ประเภท คำอธิบาย
value int32 ค่า int32

ค่า Int64

Wrapper ของข้อความสําหรับ int64

การแสดง JSON ของ Int64Value คือสตริง JSON

ชื่อช่อง ประเภท คำอธิบาย
value int64 ค่า int64

ค่ารายการ

ListValue เป็น Wrapper เกี่ยวกับช่องค่าซ้ํา

การแสดง JSON สําหรับ ListValue คืออาร์เรย์ JSON

ชื่อช่อง ประเภท คำอธิบาย
values Value ช่องที่ซ้ําของค่าที่พิมพ์แบบไดนามิก

วิธีการ

เมธอดแสดงถึงเมธอดของ API

ชื่อช่อง ประเภท คำอธิบาย
name string ชื่อแบบง่ายของวิธีนี้
request_type_url string URL ของประเภทข้อความที่ป้อน
request_streaming bool หากเป็น "จริง" ระบบจะสตรีมคําขอ
response_type_url string URL ของประเภทข้อความเอาต์พุต
response_streaming bool หากเป็น "จริง" ระบบจะสตรีมการตอบกลับ
options Option ข้อมูลเมตาที่แนบอยู่กับวิธีการ
syntax Syntax ชุดคําสั่งตามรูปแบบไวยากรณ์ของวิธีการนี้

มิกซ์

ประกาศ 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 หาก URL ที่ไม่ว่างเปล่าระบุเส้นทางที่มีเส้นทาง HTTP ที่รับช่วงมา

ค่าว่าง

NullValue เป็นการแจกแจงเดี่ยวเพื่อแทนค่า Null สําหรับการรวมประเภท Value

การแสดง JSON ของ NullValue คือ JSON null

ค่า Enum คำอธิบาย
NULL_VALUE ค่าว่าง

ตัวเลือก

ตัวเลือกบัฟเฟอร์โปรโตคอล ซึ่งสามารถแนบไปกับข้อความ ช่อง การแจกแจง ฯลฯ

ชื่อช่อง ประเภท คำอธิบาย
name string ชื่อของตัวเลือก เช่น "java_package"
value Any ค่าของตัวเลือก เช่น "com.google.protobuf"

บริบทของแหล่งที่มา

SourceContext จะแสดงข้อมูลเกี่ยวกับแหล่งที่มาขององค์ประกอบต้นแบบ เช่น ไฟล์ที่มีการกําหนดองค์ประกอบ

ชื่อช่อง ประเภท คำอธิบาย
file_name string ชื่อเส้นทางที่ถูกต้องของไฟล์ .proto ที่มีองค์ประกอบ protobuf ที่เกี่ยวข้อง เช่น "google/protobuf/source.proto"

ค่าสตริง

Wrapper ของข้อความสําหรับ string

การแสดง JSON ของ StringValue คือสตริง JSON

ชื่อช่อง ประเภท คำอธิบาย
value string ค่าสตริง

โครงสร้าง

Struct แสดงถึงค่า Structured Data ซึ่งประกอบด้วยช่องที่แมปกับค่าที่พิมพ์แบบไดนามิก ในบางภาษา ตัวแทนภาษาอาจรองรับภาษาStruct ตัวอย่างเช่น ในภาษาสคริปต์ เช่น JS โครงสร้างจะแสดงเป็นออบเจ็กต์ รายละเอียดดังกล่าวแสดงถึงการสนับสนุนต้นแบบของภาษานั้น

การแสดง JSON ของ Struct คือออบเจ็กต์ JSON

ชื่อช่อง ประเภท คำอธิบาย
fields map<string, Value> แผนที่ค่าที่พิมพ์แบบไดนามิก

ไวยากรณ์

ไวยากรณ์ที่มีการกําหนดองค์ประกอบบัฟเฟอร์โปรโตคอล

ค่า Enum คำอธิบาย
SYNTAX_PROTO2 ไวยากรณ์ proto2
SYNTAX_PROTO3 ไวยากรณ์ proto3

การประทับเวลา

การประทับเวลาจะแสดงช่วงเวลาหนึ่งที่ไม่ใช่เขตเวลาหรือปฏิทิน โดยจะแสดงเป็นวินาทีและเศษส่วนวินาทีที่ความละเอียดนาโนวินาทีในเขตเวลา UTC ส่วนรหัสนี้จะเข้ารหัสโดยใช้ปฏิทิน Proleptic Gregorian ซึ่งจะขยายปฏิทิน Gregorian ให้ย้อนกลับไปยังปีที่ 1 การเข้ารหัสจะเข้ารหัสโดยสมมติว่านาทีทั้งหมดมีความยาว 60 วินาที เช่น "วินาทีอธิกสุรทิน" มีการ "กลั่น" เพื่อไม่ให้เกิดตารางที่เปลี่ยนแปลงอย่างรวดเร็วสําหรับการแปลความหมาย ช่วงตั้งแต่ 0001-01-01T00:00:00Z ถึง 9999-12-31T23:59:59.999999999Z การจํากัดช่วงดังกล่าวช่วยให้มั่นใจว่าเราสามารถแปลงเป็นและจากสตริงวันที่ RFC 3339 ดู https://www.ietf.org/rfc/rfc3339.txt

ตัวอย่างที่ 1: การประทับเวลาของ Compute จาก POSIX time()

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

ตัวอย่างที่ 2: การประทับเวลาของ Compute จาก POSIX gettimeofday()

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

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

ตัวอย่างที่ 3: การประทับเวลาของ Compute จาก 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 แสดงเวลา UTC ในหน่วยวินาทีนับตั้งแต่ Unix epoch 1970-01-01T00:00:00Z ต้องตั้งแต่ 0001-01-01T00:00:00Z ถึง 9999-12-31T23:59:59Z
nanos int32 เศษส่วนที่ไม่เป็นลบวินาทีที่ความละเอียดนาโนวินาที ค่าวินาทีเชิงลบที่มีเศษส่วนยังคงมีค่านาโนที่ไม่ใช่จํานวนลบที่จะนับต่อไปในอนาคต ต้องมีตั้งแต่ 0 ถึง 999,999,999

ประเภท

ประเภทข้อความบัฟเฟอร์ของโปรโตคอล

ชื่อช่อง ประเภท คำอธิบาย
name string ชื่อข้อความที่สมบูรณ์ในตัวเอง
fields Field รายการช่อง
oneofs string รายการประเภทที่ปรากฏในคําจํากัดความ oneof ในประเภทนี้
options Option ตัวเลือกบัฟเฟอร์โปรโตคอล
source_context SourceContext บริบทต้นทาง
syntax Syntax ไวยากรณ์ต้นทาง

ค่า UInt32

Wrapper ของข้อความสําหรับ uint32

การแสดง JSON ของ UInt32Value คือหมายเลข JSON

ชื่อช่อง ประเภท คำอธิบาย
value uint32 ค่า uint32

UInt64ค่า

Wrapper ของข้อความสําหรับ uint64

การแสดง JSON ของ UInt64Value คือสตริง JSON

ชื่อช่อง ประเภท คำอธิบาย
value uint64 ค่า uint64

ค่า

Value แสดงถึงค่าที่พิมพ์แบบไดนามิก ซึ่งอาจมีค่าเป็น Null, ตัวเลข, สตริง, บูลีน, ค่าโครงสร้างแบบเกิดซ้ํา หรือรายการค่าได้ ควรสร้างผู้ผลิตค่าให้กับตัวแปรตัวใดตัวหนึ่ง โดยไม่มีตัวแปรใดๆ ที่บ่งบอกถึงข้อผิดพลาด

การแสดง JSON ของ Value คือค่า JSON

ชื่อช่อง ประเภท คำอธิบาย
ช่อง Union เพียงช่องใดช่องหนึ่งต่อไปนี้
null_value NullValue แสดงค่า Null
number_value double แสดงค่า Double โปรดทราบว่าการพยายามทําผลการค้นหา NaN หรือ Infinity ให้เป็นข้อผิดพลาด (เราเรียงลําดับค่าเหล่านี้เป็นสตริง "NaN" หรือ "Infinity" ไม่ได้เหมือนกับที่เราทํากับช่องปกติ เนื่องจากจะแยกวิเคราะห์เป็น string_value ไม่ใช่ number_value)
string_value string แสดงค่าสตริง
bool_value bool แสดงค่าบูลีน
struct_value Struct แสดงค่าที่มีโครงสร้าง
list_value ListValue แสดงถึง Value ที่ซ้ํากัน