Code

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