Code

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

บางครั้งอาจมีรหัสข้อผิดพลาดหลายรายการ บริการควรจะแสดงรหัสข้อผิดพลาดที่เกี่ยวข้องที่สุด เช่น ต้องการ OUT_OF_RANGE มากกว่า FAILED_PRECONDITION หากใช้รหัสทั้ง 2 รหัส ในทำนองเดียวกัน ให้ใช้ 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 โปรดทราบว่าการลองใหม่กับการดำเนินการที่ไม่ใช่ ID ชั่วคราวอาจไม่ปลอดภัยเสมอไป ดูหลักเกณฑ์ด้านบนเพื่อตัดสินใจระหว่าง FAILED_PRECONDITION, ABORTED และ UNAVAILABLE การแมป HTTP: บริการ 503 ไม่พร้อมใช้งาน
DATA_LOSS	ข้อมูลสูญหายหรือเสียหายโดยกู้คืนไม่ได้ การแมป HTTP: 500 ข้อผิดพลาดภายในเซิร์ฟเวอร์