Package google.rpc

ดัชนี

• Code (enum)
• Status (ข้อความ)

รหัส

รหัสข้อผิดพลาดตามรูปแบบบัญญัติสำหรับ gRPC API

บางครั้งอาจมีรหัสข้อผิดพลาดหลายอย่าง บริการควรส่งคืนรหัสข้อผิดพลาดที่เฉพาะเจาะจงที่สุดที่เกี่ยวข้อง เช่น โปรดเลือก OUT_OF_RANGE มากกว่า FAILED_PRECONDITION หากรหัสทั้งสองแบบมีผล ใช้ NOT_FOUND หรือ ALREADY_EXISTS มากกว่า FAILED_PRECONDITION ในทำนองเดียวกัน

Enum
OK	ไม่ใช่ข้อผิดพลาด ส่งคืนความสำเร็จ การจับคู่ HTTP: 200 OK
CANCELLED	โดยปกติผู้โทรจะยกเลิกการดำเนินการแล้ว การแมป HTTP: 499 คำขอปิดของไคลเอ็นต์
UNKNOWN	ข้อผิดพลาดที่ไม่รู้จัก ตัวอย่างเช่น ข้อผิดพลาดนี้อาจแสดงขึ้นเมื่อค่า Status ที่ได้รับจากพื้นที่ที่อยู่อื่นเป็นของพื้นที่ข้อผิดพลาดที่ไม่รู้จักในพื้นที่ที่อยู่นี้ นอกจากนี้ ข้อผิดพลาดที่เกิดจาก API ที่แสดงข้อมูลข้อผิดพลาดไม่มากพออาจแปลงเป็นข้อผิดพลาดนี้ได้ การจับคู่ HTTP: 500 ข้อผิดพลาดภายในเซิร์ฟเวอร์
INVALID_ARGUMENT	ไคลเอ็นต์ระบุอาร์กิวเมนต์ไม่ถูกต้อง โปรดทราบว่าจำนวนนี้จะแตกต่างจาก FAILED_PRECONDITION INVALID_ARGUMENT จะระบุอาร์กิวเมนต์ที่มีปัญหาโดยไม่คำนึงถึงสถานะของระบบ (เช่น ชื่อไฟล์มีรูปแบบไม่ถูกต้อง) การแมป HTTP: 400 คำขอไม่ถูกต้อง
DEADLINE_EXCEEDED	กำหนดเวลาหมดอายุก่อนที่การดำเนินการจะเสร็จสิ้น สำหรับการดำเนินการที่เปลี่ยนสถานะของระบบ อาจมีการแสดงข้อผิดพลาดนี้แม้ว่าการดำเนินการจะเสร็จเรียบร้อยแล้วก็ตาม เช่น การตอบกลับที่สําเร็จจากเซิร์ฟเวอร์อาจล่าช้านานพอให้กําหนดเวลาหมดอายุ การจับคู่ HTTP: 504 เกตเวย์หมดเวลา
NOT_FOUND	ไม่พบเอนทิตีที่ขอ (เช่น ไฟล์หรือไดเรกทอรี) บางรายการ หมายเหตุถึงนักพัฒนาเซิร์ฟเวอร์: หากคำขอถูกปฏิเสธสำหรับผู้ใช้ทั้งกลุ่ม เช่น การทยอยเปิดตัวฟีเจอร์หรือรายการที่อนุญาตที่ไม่มีเอกสารประกอบ ระบบอาจใช้ NOT_FOUND หากผู้ใช้บางรายภายในกลุ่มผู้ใช้บางรายปฏิเสธคำขอ เช่น การควบคุมการเข้าถึงตามผู้ใช้ คุณจะต้องใช้ PERMISSION_DENIED การแมป HTTP: 404 ไม่พบ
ALREADY_EXISTS	มีเอนทิตีที่ไคลเอ็นต์พยายามสร้าง (เช่น ไฟล์หรือไดเรกทอรี) อยู่แล้ว การจับคู่ HTTP: 409 เกิดความขัดแย้ง
PERMISSION_DENIED	ผู้โทรไม่มีสิทธิ์ดำเนินการที่ระบุ ต้องไม่ใช้ PERMISSION_DENIED สำหรับการปฏิเสธที่เกิดจากการใช้ทรัพยากรบางส่วนจนหมด (ใช้ RESOURCE_EXHAUSTED แทนสำหรับข้อผิดพลาดเหล่านั้น) และต้องไม่ใช้ PERMISSION_DENIED หากระบบระบุผู้โทรไม่ได้ (ใช้ UNAUTHENTICATED แทนสำหรับข้อผิดพลาดเหล่านั้น) รหัสข้อผิดพลาดนี้ไม่ได้บอกเป็นนัยว่าคำขอถูกต้องหรือมีเอนทิตีที่ขออยู่หรือเป็นไปตามเงื่อนไขเบื้องต้นอื่นๆ การแมป HTTP: 403 Forbidden
UNAUTHENTICATED	คำขอไม่มีข้อมูลเข้าสู่ระบบการตรวจสอบสิทธิ์ที่ถูกต้องสำหรับการดำเนินการ การแมป HTTP: 401 ไม่ได้รับอนุญาต
RESOURCE_EXHAUSTED	มีการใช้ทรัพยากรบางรายการจนหมดแล้ว อาจเป็นโควต้าสำหรับผู้ใช้แต่ละราย หรือทรัพยากรทั้งระบบไม่มีพื้นที่เหลือ การแมป HTTP: 429 มีคำขอมากเกินไป
FAILED_PRECONDITION	การดำเนินการถูกปฏิเสธเนื่องจากระบบไม่อยู่ในสถานะที่จำเป็นสำหรับการดำเนินการ เช่น ไดเรกทอรีที่จะลบจะไม่ว่างเปล่า มีการใช้การดำเนินการ rmdir กับไดเรกทอรีที่ไม่ใช่ไดเรกทอรี เป็นต้น ผู้ให้บริการสามารถใช้หลักเกณฑ์ต่อไปนี้ในการตัดสินใจระหว่าง FAILED_PRECONDITION, ABORTED และ UNAVAILABLE (ก) ใช้ UNAVAILABLE หากลูกค้าลองเรียกที่ไม่สำเร็จอีกครั้ง (ข) ใช้ ABORTED หากลูกค้าควรลองอีกครั้งในระดับที่สูงกว่า ตัวอย่างเช่น เมื่อการทดสอบและชุดที่ระบุโดยไคลเอ็นต์ล้มเหลว การบ่งชี้ว่าไคลเอ็นต์ควรรีสตาร์ทลำดับ Read-modify-write (ค) ใช้ FAILED_PRECONDITION หากไคลเอ็นต์ไม่ควรลองอีกครั้งจนกว่าสถานะของระบบจะได้รับการแก้ไขอย่างชัดเจน เช่น ถ้าใช้ "rmdir" ไม่สำเร็จเนื่องจากไดเรกทอรีไม่ว่างเปล่า ควรส่งกลับ FAILED_PRECONDITION เนื่องจากไคลเอ็นต์จะไม่ลองใหม่จนกว่าจะลบไฟล์ออกจากไดเรกทอรีแล้ว การแมป HTTP: 400 คำขอไม่ถูกต้อง
ABORTED	ล้มเลิกการดำเนินการแล้ว ซึ่งมักเกิดจากปัญหาการเกิดขึ้นพร้อมกัน เช่น การตรวจสอบตัวจัดลำดับไม่สำเร็จหรือล้มเลิกธุรกรรม ดูหลักเกณฑ์ด้านบนในการตัดสินใจเลือก FAILED_PRECONDITION, ABORTED หรือ UNAVAILABLE การจับคู่ HTTP: 409 เกิดความขัดแย้ง
OUT_OF_RANGE	ดำเนินการเกินช่วงที่ถูกต้อง เช่น การกรอวิดีโอหรือการอ่านส่วนท้ายของไฟล์ ข้อผิดพลาดนี้ต่างจาก INVALID_ARGUMENT ตรงที่ข้อผิดพลาดนี้บ่งบอกถึงปัญหาที่อาจได้รับการแก้ไขหากสถานะของระบบเปลี่ยนแปลง ตัวอย่างเช่น ระบบไฟล์ 32 บิตจะสร้าง INVALID_ARGUMENT หากมีการขอให้อ่านค่าในออฟเซ็ตที่ไม่ได้อยู่ในช่วง [0,2^32-1] แต่จะสร้าง OUT_OF_RANGE หากระบบขอให้อ่านค่าจากออฟเซ็ตหลังจากขนาดไฟล์ปัจจุบัน FAILED_PRECONDITION กับ OUT_OF_RANGE มีซ้อนทับกันเล็กน้อย เราขอแนะนำให้ใช้ OUT_OF_RANGE (ยิ่งมีข้อผิดพลาดที่เจาะจงมากขึ้น) เมื่อดำเนินการดังกล่าว เพื่อให้ผู้โทรที่ปรับปรุงพื้นที่ทำงานค้นหาข้อผิดพลาด OUT_OF_RANGE ได้โดยง่ายเมื่อดำเนินการเสร็จแล้ว การแมป HTTP: 400 คำขอไม่ถูกต้อง
UNIMPLEMENTED	บริการนี้ยังไม่มีผลหรือไม่รองรับ/เปิดใช้การดำเนินการนี้ การแมป HTTP: 501 ไม่ได้นำมาใช้
INTERNAL	ข้อผิดพลาดภายใน ซึ่งหมายความว่าตัวแปรบางอย่างที่คาดไว้โดยระบบพื้นฐานขัดข้อง รหัสข้อผิดพลาดนี้ใช้สำหรับข้อผิดพลาดร้ายแรงเท่านั้น การจับคู่ HTTP: 500 ข้อผิดพลาดภายในเซิร์ฟเวอร์
UNAVAILABLE	ไม่พร้อมให้บริการนี้ในขณะนี้ เหตุการณ์นี้น่าจะเป็นเงื่อนไขชั่วคราว ซึ่งแก้ไขได้ด้วยการลองอีกครั้งโดยใช้ Backoff โปรดทราบว่าการลองดำเนินการที่ไม่ใช่แบบกำหนดอีกครั้งอาจไม่ปลอดภัยเสมอไป ดูหลักเกณฑ์ด้านบนในการตัดสินใจเลือก FAILED_PRECONDITION, ABORTED หรือ UNAVAILABLE การแมป HTTP: 503 บริการไม่พร้อมใช้งาน
DATA_LOSS	ข้อมูลเสียหายหรือสูญหายโดยกู้คืนไม่ได้ การจับคู่ HTTP: 500 ข้อผิดพลาดภายในเซิร์ฟเวอร์

สถานะ

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

ดูข้อมูลเพิ่มเติมเกี่ยวกับรูปแบบข้อผิดพลาดนี้และวิธีทำงานกับรูปแบบดังกล่าวได้ในคู่มือการออกแบบ API

ช่อง
code	int32 รหัสสถานะ ซึ่งควรเป็นค่า enum ของ google.rpc.Code
message	string ข้อความแสดงข้อผิดพลาดที่ส่งถึงนักพัฒนาซอฟต์แวร์ ซึ่งควรเป็นภาษาอังกฤษ ข้อความแสดงข้อผิดพลาดที่แสดงต่อผู้ใช้ควรแปลและส่งในช่อง google.rpc.Status.details หรือไคลเอ็นต์แปล
details[]	Any รายการข้อความที่มีรายละเอียดข้อผิดพลาด มีชุดประเภทข้อความที่ใช้กันโดยทั่วไปสำหรับ API