Package google.rpc

ดัชนี

รหัส

รหัสข้อผิดพลาดตามรูปแบบบัญญัติสำหรับ 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 ข้อผิดพลาดภายในเซิร์ฟเวอร์

สถานะ

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

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

ช่อง
code

int32

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

string

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

Any

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