Status

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

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

ภาพรวม

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

การทำแผนที่ภาษา

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

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

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

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

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

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

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

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

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

การเป็นตัวแทน JSON
{
  "code": number,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
เขตข้อมูล
code

number

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

message

string

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

details[]

object

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

วัตถุที่มีฟิลด์ประเภทใดก็ได้ ฟิลด์เพิ่มเติม "@type" มี URI ที่ระบุประเภท ตัวอย่าง: { "id": 1234, "@type": "types.example.com/standard/id" }