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

หน้านี้ได้รับการแปลโดย Cloud Translation API

Switch to English

Package google.protobuf

ดัชนี

Any (ข้อความ)
Api (ข้อความ)
BoolValue (ข้อความ)
BytesValue (ข้อความ)
DoubleValue (ข้อความ)
Duration (ข้อความ)
Empty (ข้อความ)
Enum (ข้อความ)
EnumValue (ข้อความ)
Field (ข้อความ)
Field.Cardinality (enum)
Field.Kind (enum)
FieldMask (ข้อความ)
FloatValue (ข้อความ)
Int32Value (ข้อความ)
Int64Value (ข้อความ)
ListValue (ข้อความ)
Method (ข้อความ)
Mixin (ข้อความ)
NullValue (enum)
Option (ข้อความ)
SourceContext (ข้อความ)
StringValue (ข้อความ)
Struct (ข้อความ)
Syntax (enum)
Timestamp (ข้อความ)
Type (ข้อความ)
UInt32Value (ข้อความ)
UInt64Value (ข้อความ)
Value (ข้อความ)

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

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`	ต้องเป็นข้อมูลแบบอนุกรมที่ถูกต้องของประเภทที่ระบุข้างต้น

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` ที่ซ้ํากัน