Package google.rpc

ดัชนี

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

รหัส

รหัสข้อผิดพลาดตามมาตรฐานสําหรับ 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 หากไคลเอ็นต์ควรลองอีกครั้งที่ระดับที่สูงขึ้น เช่น เมื่อการทดสอบและการตั้งค่าที่ไคลเอ็นต์ระบุไม่สําเร็จ ซึ่งบ่งชี้ว่าไคลเอ็นต์ควรเริ่มลําดับการอ่าน แก้ไข และเขียนอีกครั้ง (ค) ใช้ 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 ข้อผิดพลาดภายในเซิร์ฟเวอร์

สถานะ

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

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

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