Package google.rpc

ดัชนี

BadRequest

อธิบายการละเมิดในคำขอของไคลเอ็นต์ ข้อผิดพลาดประเภทนี้มุ่งเน้นที่ด้านไวยากรณ์ของคำขอ

ช่อง
field_violations[]

FieldViolation

อธิบายการละเมิดทั้งหมดในคำขอของไคลเอ็นต์

FieldViolation

ประเภทข้อความที่ใช้เพื่ออธิบายฟิลด์คำขอที่ไม่ถูกต้องรายการเดียว

ช่อง
field

string

เส้นทางที่นำไปยังฟิลด์ในเนื้อหาคำขอ ค่าจะเป็นลำดับของตัวระบุที่คั่นด้วยจุดซึ่งระบุฟิลด์ Protocol Buffer

ลองพิจารณาสิ่งเหล่านี้

message CreateContactRequest {
  message EmailAddress {
    enum Type {
      TYPE_UNSPECIFIED = 0;
      HOME = 1;
      WORK = 2;
    }

    optional string email = 1;
    repeated EmailType type = 2;
  }

  string full_name = 1;
  repeated EmailAddress email_addresses = 2;
}

ในตัวอย่างนี้ field ใน Proto อาจมีค่าใดค่าหนึ่งต่อไปนี้

  • full_name สำหรับการละเมิดในค่า full_name
  • email_addresses[1].email สำหรับการละเมิดในฟิลด์ email ของข้อความ email_addresses แรก
  • email_addresses[3].type[2] สำหรับการละเมิดในค่า type ที่สองในข้อความ email_addresses ที่สาม

ใน JSON ค่าเดียวกันจะแสดงเป็น

  • fullName สำหรับการละเมิดในค่า fullName
  • emailAddresses[1].email สำหรับการละเมิดในฟิลด์ email ของข้อความ emailAddresses แรก
  • emailAddresses[3].type[2] สำหรับการละเมิดในค่า type ที่สองในข้อความ emailAddresses ที่สาม
description

string

คำอธิบายว่าเหตุใดองค์ประกอบคำขอจึงไม่ถูกต้อง
reason

string

เหตุผลของข้อผิดพลาดระดับฟิลด์ นี่คือค่าคงที่ที่ระบุสาเหตุที่ใกล้ที่สุดของข้อผิดพลาดระดับฟิลด์ โดยควรระบุประเภท FieldViolation ภายในขอบเขตของ google.rpc.ErrorInfo.domain โดยไม่ซ้ำกัน ควรมีอักขระไม่เกิน 63 ตัวและตรงกับนิพจน์ทั่วไปของ [A-Z][A-Z0-9_]+[A-Z0-9] ซึ่งแสดงถึง UPPER_SNAKE_CASE
localized_message

LocalizedMessage

แสดงข้อความแสดงข้อผิดพลาดที่แปลเป็นภาษาท้องถิ่นสำหรับข้อผิดพลาดระดับฟิลด์ซึ่งส่งคืนให้ผู้ใช้ API ได้อย่างปลอดภัย

รหัส

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

ไม่พร้อมให้บริการนี้ในขณะนี้ ซึ่งมักจะเป็นเงื่อนไขชั่วคราวที่แก้ไขได้โดยการลองอีกครั้งด้วยการหยุดชั่วคราว โปรดทราบว่าการลองดำเนินการที่ไม่ใช่แบบ Idempotent อีกครั้งอาจไม่ปลอดภัยเสมอไป

ดูหลักเกณฑ์ด้านบนเพื่อเลือกระหว่าง FAILED_PRECONDITION, ABORTED และ UNAVAILABLE

การแมป HTTP: 503 ไม่พร้อมให้บริการ
DATA_LOSS

ข้อมูลสูญหายโดยกู้คืนไม่ได้หรือข้อมูลเสียหาย

การแมป HTTP: 500 ข้อผิดพลาดภายในเซิร์ฟเวอร์

ErrorInfo

อธิบายสาเหตุของข้อผิดพลาดพร้อมรายละเอียดที่มีโครงสร้าง

ตัวอย่างข้อผิดพลาดเมื่อติดต่อ API "pubsub.googleapis.com" เมื่อไม่ได้เปิดใช้

{ "reason": "API_DISABLED"
  "domain": "googleapis.com"
  "metadata": {
    "resource": "projects/123",
    "service": "pubsub.googleapis.com"
  }
}

การตอบกลับนี้บ่งชี้ว่าไม่ได้เปิดใช้ API pubsub.googleapis.com

ตัวอย่างข้อผิดพลาดที่แสดงเมื่อพยายามสร้างอินสแตนซ์ Spanner ในภูมิภาคที่สินค้าหมด

{ "reason": "STOCKOUT"
  "domain": "spanner.googleapis.com",
  "metadata": {
    "availableRegions": "us-central1,us-east2"
  }
}
ช่อง
reason

string

สาเหตุของข้อผิดพลาด นี่คือค่าคงที่ที่ระบุสาเหตุที่ใกล้ที่สุดของข้อผิดพลาด เหตุผลของข้อผิดพลาดจะแตกต่างกันภายในโดเมนของข้อผิดพลาดที่เฉพาะเจาะจง ควรมีอักขระไม่เกิน 63 ตัวและตรงกับนิพจน์ทั่วไปของ [A-Z][A-Z0-9_]+[A-Z0-9] ซึ่งแสดงถึง UPPER_SNAKE_CASE
domain

string

การจัดกลุ่มเชิงตรรกะที่ "เหตุผล" อยู่ โดยทั่วไป โดเมนข้อผิดพลาดคือชื่อบริการที่ลงทะเบียนของเครื่องมือหรือผลิตภัณฑ์ที่สร้างข้อผิดพลาด เช่น "pubsub.googleapis.com" หากข้อผิดพลาดเกิดจากโครงสร้างพื้นฐานทั่วไปบางอย่าง โดเมนข้อผิดพลาดต้องเป็นค่าที่ไม่ซ้ำกันทั่วโลกซึ่งระบุโครงสร้างพื้นฐาน สำหรับโครงสร้างพื้นฐานของ Google API โดเมนข้อผิดพลาดคือ "googleapis.com"
metadata

map<string, string>

รายละเอียดเพิ่มเติมที่มีโครงสร้างเกี่ยวกับข้อผิดพลาดนี้

คีย์ต้องตรงกับนิพจน์ทั่วไปของ [a-z][a-zA-Z0-9-_]+ แต่ควรเป็น lowerCamelCase นอกจากนี้ ยังต้องมีความยาวไม่เกิน 64 อักขระ เมื่อระบุค่าปัจจุบันของขีดจํากัดที่เกิน หน่วยควรอยู่ในคีย์ ไม่ใช่ค่า เช่น แทนที่จะเป็น {"instanceLimit": "100/request"} ควรแสดงเป็น {"instanceLimitPerRequest": "100"} หากไคลเอ็นต์สร้างอินสแตนซ์เกินจำนวนที่สร้างได้ในคำขอเดียว (แบบกลุ่ม)

ความช่วยเหลือ

ระบุลิงก์ไปยังเอกสารประกอบหรือสำหรับการดำเนินการนอกแบนด์

ตัวอย่างเช่น หากการตรวจสอบโควต้าล้มเหลวโดยมีข้อผิดพลาดที่ระบุว่าโปรเจ็กต์ที่เรียกใช้ไม่ได้เปิดใช้บริการที่เข้าถึงอยู่ ข้อความนี้อาจมี URL ที่นำไปยังส่วนที่ถูกต้องในคอนโซลนักพัฒนาแอปโดยตรงเพื่อเปลี่ยนบิต

ช่อง

LocalizedMessage

แสดงข้อความแสดงข้อผิดพลาดที่แปลแล้วซึ่งส่งคืนให้ผู้ใช้ได้อย่างปลอดภัยและแนบไปกับข้อผิดพลาด RPC ได้

ช่อง
locale

string

ภาษาที่ใช้ตามข้อกำหนดที่ระบุไว้ที่ https://www.rfc-editor.org/rfc/bcp/bcp47.txt เช่น "en-US", "fr-CH", "es-MX"
message

string

ข้อความแสดงข้อผิดพลาดที่แปลแล้วในภาษาข้างต้น

RequestInfo

มีข้อมูลเมตาเกี่ยวกับคำขอที่ไคลเอ็นต์สามารถแนบเมื่อรายงานข้อบกพร่องหรือให้ความคิดเห็นในรูปแบบอื่นๆ

ช่อง
request_id

string

สตริงทึบแสงที่บริการที่สร้างสตริงนี้เท่านั้นที่ควรตีความ เช่น ใช้เพื่อระบุคำขอในบันทึกของบริการได้
serving_data

string

ข้อมูลใดๆ ที่ใช้ในการแสดงคำขอนี้ เช่น สแต็กเทรซที่เข้ารหัสซึ่งส่งกลับไปยังผู้ให้บริการเพื่อการแก้ไขข้อบกพร่องได้

สถานะ

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

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

ช่อง
code

int32

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

string

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

Any

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