Status

ประเภท Status กำหนดโมเดลข้อผิดพลาดเชิงตรรกะที่เหมาะกับสภาพแวดล้อมในการเขียนโปรแกรมแบบต่างๆ ซึ่งรวมถึง REST API และ RPC API gRPC ใช้ รูปแบบข้อผิดพลาดได้รับการออกแบบดังนี้

  • ใช้งานง่ายและเข้าใจสำหรับผู้ใช้ส่วนใหญ่
  • ยืดหยุ่นพอที่จะตอบสนองความต้องการที่ไม่คาดคิด

ภาพรวม

ข้อความ Status มีข้อมูล 3 อย่าง ได้แก่ รหัสข้อผิดพลาด ข้อความแสดงข้อผิดพลาด และรายละเอียดข้อผิดพลาด รหัสข้อผิดพลาดควรเป็นค่า enum ของ google.rpc.Code แต่อาจยอมรับรหัสข้อผิดพลาดเพิ่มเติมได้หากต้องการ ข้อความแสดงข้อผิดพลาดควรเป็นข้อความภาษาอังกฤษที่นักพัฒนาแอปพบเพื่อช่วยให้นักพัฒนาแอปเข้าใจและแก้ปัญหาข้อผิดพลาดได้ หากต้องการข้อความแสดงข้อผิดพลาดที่แสดงต่อผู้ใช้ที่แปลแล้ว ให้ใส่ข้อความที่แปลแล้วไว้ในรายละเอียดข้อผิดพลาดหรือแปลเป็นภาษาท้องถิ่นในไคลเอ็นต์ รายละเอียดข้อผิดพลาดที่ไม่บังคับอาจมีข้อมูลที่กำหนดเองเกี่ยวกับข้อผิดพลาด มีชุดประเภทรายละเอียดข้อผิดพลาดที่กำหนดไว้ล่วงหน้าในแพ็กเกจ google.rpc ซึ่งใช้ได้กับเงื่อนไขข้อผิดพลาดทั่วไป

การแมปภาษา

ข้อความ Status เป็นการนำเสนอแบบตรรกะของโมเดลข้อผิดพลาด แต่ก็อาจไม่ใช่รูปแบบสายไฟจริงเสมอไป เมื่อข้อความ Status แสดงในไลบรารีของไคลเอ็นต์ที่แตกต่างกันและโปรโตคอลการใช้สายที่ต่างกัน ระบบจึงแมปข้อความได้ต่างกัน ตัวอย่างเช่น อาจแมปกับข้อยกเว้นบางอย่างใน Java แต่อาจแมปกับรหัสข้อผิดพลาดบางรายการใน C

การใช้งานอื่นๆ

โมเดลข้อผิดพลาดและข้อความ Status ใช้ได้ในหลายสภาพแวดล้อม ไม่ว่าจะมีหรือไม่มี API ก็ตาม เพื่อให้ประสบการณ์ของนักพัฒนาแอปที่สอดคล้องกันในสภาพแวดล้อมต่างๆ

ตัวอย่างการใช้โมเดลข้อผิดพลาดนี้ ได้แก่

  • ข้อผิดพลาดบางส่วน หากบริการจำเป็นต้องแสดงข้อผิดพลาดบางส่วนให้ไคลเอ็นต์ บริการอาจฝัง Status ไว้ในการตอบสนองปกติเพื่อระบุข้อผิดพลาดบางส่วน

  • ข้อผิดพลาดของเวิร์กโฟลว์ เวิร์กโฟลว์ทั่วไปมีหลายขั้นตอน แต่ละขั้นตอนอาจมีข้อความ Status สำหรับรายงานข้อผิดพลาด

  • การทำงานเป็นแบตช์ ถ้าไคลเอ็นต์ใช้คำขอแบบกลุ่มและการตอบกลับแบบกลุ่ม ควรใช้ข้อความ Status โดยตรงภายในการตอบกลับแบบกลุ่ม โดยใช้ข้อความ 1 ข้อความต่อการตอบกลับย่อยข้อผิดพลาดแต่ละรายการ

  • การทำงานแบบไม่พร้อมกัน หากการเรียก API มีการฝังการดำเนินการแบบไม่พร้อมกันไว้ในการตอบสนอง สถานะของการดำเนินการเหล่านั้นควรแสดงโดยใช้ข้อความ Status โดยตรง

  • การบันทึก หากเกิดข้อผิดพลาดบางอย่างเกี่ยวกับ API ในบันทึก ระบบอาจใช้ข้อความ Status ได้โดยตรงหลังจากที่มีการตัดข้อความด้วยเหตุผลด้านความปลอดภัย/ความเป็นส่วนตัว

การแสดง JSON 
{
  "code": number,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
ช่อง
code

number

รหัสสถานะ ซึ่งควรเป็นค่า enum ของ google.rpc.Code

message

string

ข้อความแสดงข้อผิดพลาดที่นักพัฒนาแอปเห็น ซึ่งควรเป็นภาษาอังกฤษ ข้อความแสดงข้อผิดพลาดที่แสดงต่อผู้ใช้ควรแปลและส่งในช่อง google.rpc.Status.details หรือแปลโดยไคลเอ็นต์

details[]

object

รายการข้อความที่มีรายละเอียดข้อผิดพลาด API จะใช้ชุดประเภทข้อความที่พบได้ทั่วไป

ออบเจ็กต์ที่มีช่องประเภทที่กำหนดเอง ช่องเพิ่มเติม "@type" จะมี URI ที่ระบุประเภท ตัวอย่างเช่น { "id": 1234, "@type": "types.example.com/standard/id" }