Package google.rpc

Chỉ mục

• BadRequest (thông báo)
• BadRequest.FieldViolation (thông báo)
• Code (enum)
• ErrorInfo (thông báo)
• Help (thông báo)
• Help.Link (thông báo)
• LocalizedMessage (thông báo)
• PreconditionFailure (thông báo)
• PreconditionFailure.Violation (thông báo)
• QuotaFailure (thông báo)
• QuotaFailure.Violation (thông báo)
• RequestInfo (thông báo)
• ResourceInfo (thông báo)
• RetryInfo (thông báo)
• Status (thông báo)

BadRequest

Mô tả các lỗi vi phạm trong yêu cầu của ứng dụng. Loại lỗi này tập trung vào các khía cạnh cú pháp của yêu cầu.

Trường
field_violations[]	FieldViolation Mô tả tất cả các lỗi vi phạm trong một yêu cầu của máy khách.

FieldViolation

Một loại thông báo dùng để mô tả một trường yêu cầu không hợp lệ.

Trường
field	string Đường dẫn dẫn đến một trường trong nội dung yêu cầu. Giá trị này sẽ là một chuỗi các giá trị nhận dạng được phân tách bằng dấu chấm để xác định một trường vùng đệm giao thức. Hãy cân nhắc thực hiện những bước sau: 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; } Trong ví dụ này, trong proto field có thể nhận một trong các giá trị sau: full_name cho lỗi vi phạm trong giá trị full_name email_addresses[1].email cho một lỗi vi phạm trong trường email của tin nhắn email_addresses đầu tiên email_addresses[3].type[2] cho lỗi vi phạm ở giá trị type thứ hai trong thông báo email_addresses thứ ba. Trong JSON, các giá trị tương tự được biểu thị như sau: fullName cho lỗi vi phạm trong giá trị fullName emailAddresses[1].email cho một lỗi vi phạm trong trường email của tin nhắn emailAddresses đầu tiên emailAddresses[3].type[2] cho lỗi vi phạm ở giá trị type thứ hai trong thông báo emailAddresses thứ ba.
description	string Nội dung mô tả lý do khiến phần tử yêu cầu không hợp lệ.
reason	string Lý do gây ra lỗi ở cấp trường. Đây là một giá trị hằng số xác định nguyên nhân gần nhất gây ra lỗi ở cấp trường. Giá trị này phải xác định duy nhất loại FieldViolation trong phạm vi của google.rpc.ErrorInfo.domain. Tên này chỉ được dài tối đa 63 ký tự và phải khớp với biểu thức chính quy [A-Z][A-Z0-9_]+[A-Z0-9], biểu thị UPPER_SNAKE_CASE.
localized_message	LocalizedMessage Cung cấp thông báo lỗi đã bản địa hoá cho các lỗi ở cấp trường mà người dùng API có thể nhận được một cách an toàn.

Mã

Mã lỗi chuẩn cho các API gRPC.

Đôi khi, nhiều mã lỗi có thể áp dụng. Các dịch vụ phải trả về mã lỗi cụ thể nhất có thể áp dụng. Ví dụ: ưu tiên OUT_OF_RANGE hơn FAILED_PRECONDITION nếu cả hai mã đều áp dụng. Tương tự, hãy ưu tiên NOT_FOUND hoặc ALREADY_EXISTS hơn FAILED_PRECONDITION.

Enum
OK	Không phải là lỗi; được trả về khi thành công. Ánh xạ HTTP: 200 OK
CANCELLED	Thao tác đã bị huỷ, thường là do người gọi. Ánh xạ HTTP: 499 Ứng dụng đã đóng yêu cầu
UNKNOWN	Lỗi không xác định. Ví dụ: lỗi này có thể được trả về khi giá trị Status nhận được từ một không gian địa chỉ khác thuộc về một không gian lỗi không xác định trong không gian địa chỉ này. Ngoài ra, những lỗi do các API không trả về đủ thông tin lỗi cũng có thể được chuyển đổi thành lỗi này. Ánh xạ HTTP: 500 Lỗi máy chủ nội bộ
INVALID_ARGUMENT	Ứng dụng khách chỉ định đối số không hợp lệ. Xin lưu ý rằng thuộc tính này khác với FAILED_PRECONDITION. INVALID_ARGUMENT cho biết các đối số có vấn đề bất kể trạng thái của hệ thống (ví dụ: tên tệp bị lỗi). Ánh xạ HTTP: 400 Yêu cầu không hợp lệ
DEADLINE_EXCEEDED	Đã hết thời hạn trước khi thao tác có thể hoàn tất. Đối với các thao tác thay đổi trạng thái của hệ thống, lỗi này có thể được trả về ngay cả khi thao tác đã hoàn tất thành công. Ví dụ: phản hồi thành công từ một máy chủ có thể bị trì hoãn đủ lâu để thời hạn kết thúc. Ánh xạ HTTP: 504 Hết thời gian chờ của cổng nối
NOT_FOUND	Không tìm thấy một số thực thể được yêu cầu (ví dụ: tệp hoặc thư mục). Lưu ý cho nhà phát triển máy chủ: nếu một yêu cầu bị từ chối đối với toàn bộ một nhóm người dùng, chẳng hạn như việc triển khai tính năng từng bước hoặc danh sách cho phép không có trong tài liệu, thì bạn có thể sử dụng NOT_FOUND. Nếu một số người dùng trong một nhóm người dùng bị từ chối yêu cầu, chẳng hạn như kiểm soát quyền truy cập dựa trên người dùng, thì bạn phải sử dụng PERMISSION_DENIED. Ánh xạ HTTP: 404 Not Found
ALREADY_EXISTS	Đã tồn tại thực thể mà ứng dụng khách tìm cách tạo (ví dụ: tệp hoặc thư mục). Ánh xạ HTTP: 409 Xung đột
PERMISSION_DENIED	Người gọi không có quyền thực thi thao tác đã chỉ định. Bạn không được dùng PERMISSION_DENIED cho các trường hợp từ chối do hết tài nguyên (thay vào đó, hãy dùng RESOURCE_EXHAUSTED cho những lỗi đó). Bạn không được dùng PERMISSION_DENIED nếu không xác định được phương thức gọi (thay vào đó, hãy dùng UNAUTHENTICATED cho những lỗi đó). Mã lỗi này không ngụ ý rằng yêu cầu là hợp lệ hoặc thực thể được yêu cầu tồn tại hoặc đáp ứng các điều kiện tiên quyết khác. Ánh xạ HTTP: 403 Bị cấm
UNAUTHENTICATED	Yêu cầu không có thông tin xác thực hợp lệ cho thao tác. Ánh xạ HTTP: 401 Không được phép
RESOURCE_EXHAUSTED	Một số tài nguyên đã cạn kiệt, có thể là hạn mức cho mỗi người dùng hoặc có thể toàn bộ hệ thống tệp đã hết dung lượng. Ánh xạ HTTP: 429 Quá nhiều yêu cầu
FAILED_PRECONDITION	Thao tác bị từ chối vì hệ thống không ở trạng thái cần thiết để thực hiện thao tác. Ví dụ: thư mục cần xoá không phải là thư mục trống, thao tác rmdir được áp dụng cho một thư mục không phải là thư mục, v.v. Người triển khai dịch vụ có thể sử dụng các nguyên tắc sau để quyết định giữa FAILED_PRECONDITION, ABORTED và UNAVAILABLE: (a) Sử dụng UNAVAILABLE nếu máy khách chỉ có thể thử lại lệnh gọi không thành công. (b) Sử dụng ABORTED nếu ứng dụng nên thử lại ở cấp độ cao hơn. Ví dụ: khi một thao tác kiểm tra và thiết lập do ứng dụng chỉ định không thành công, cho biết ứng dụng nên khởi động lại một chuỗi đọc-sửa đổi-ghi. (c) Sử dụng FAILED_PRECONDITION nếu ứng dụng không được thử lại cho đến khi trạng thái hệ thống được sửa chữa rõ ràng. Ví dụ: nếu "rmdir" không thành công vì thư mục không trống, thì FAILED_PRECONDITION sẽ được trả về vì máy khách không được thử lại trừ phi các tệp bị xoá khỏi thư mục. Ánh xạ HTTP: 400 Yêu cầu không hợp lệ
ABORTED	Thao tác bị huỷ bỏ, thường là do vấn đề về tính đồng thời, chẳng hạn như lỗi kiểm tra trình tự hoặc huỷ giao dịch. Hãy xem các nguyên tắc ở trên để quyết định giữa FAILED_PRECONDITION, ABORTED và UNAVAILABLE. Ánh xạ HTTP: 409 Xung đột
OUT_OF_RANGE	Thao tác được thực hiện ngoài phạm vi hợp lệ. Ví dụ: tìm kiếm hoặc đọc quá cuối tệp. Không giống như INVALID_ARGUMENT, lỗi này cho biết có một vấn đề có thể được khắc phục nếu trạng thái hệ thống thay đổi. Ví dụ: hệ thống tệp 32 bit sẽ tạo INVALID_ARGUMENT nếu được yêu cầu đọc ở một độ lệch không nằm trong phạm vi [0, 2^32-1], nhưng sẽ tạo OUT_OF_RANGE nếu được yêu cầu đọc từ một độ lệch vượt quá kích thước tệp hiện tại. Có một số điểm trùng lặp giữa FAILED_PRECONDITION và OUT_OF_RANGE. Bạn nên sử dụng OUT_OF_RANGE (lỗi cụ thể hơn) khi lỗi này áp dụng để những người gọi đang lặp lại qua một không gian có thể dễ dàng tìm kiếm lỗi OUT_OF_RANGE để phát hiện thời điểm họ hoàn tất. Ánh xạ HTTP: 400 Yêu cầu không hợp lệ
UNIMPLEMENTED	Thao tác này chưa được triển khai hoặc không được hỗ trợ/bật trong dịch vụ này. Liên kết HTTP: 501 Chưa triển khai
INTERNAL	Lỗi nội bộ. Điều này có nghĩa là một số bất biến mà hệ thống cơ bản dự kiến đã bị phá vỡ. Mã lỗi này dành riêng cho các lỗi nghiêm trọng. Ánh xạ HTTP: 500 Lỗi máy chủ nội bộ
UNAVAILABLE	Dịch vụ này hiện không dùng được. Đây thường là một điều kiện tạm thời và bạn có thể khắc phục bằng cách thử lại với độ trễ. Xin lưu ý rằng không phải lúc nào bạn cũng nên thử lại các thao tác không có tính chất luỹ đẳng. Hãy xem các nguyên tắc ở trên để quyết định giữa FAILED_PRECONDITION, ABORTED và UNAVAILABLE. Ánh xạ HTTP: 503 Không có dịch vụ
DATA_LOSS	Mất hoặc hư hỏng dữ liệu và không phục hồi được. Ánh xạ HTTP: 500 Lỗi máy chủ nội bộ

ErrorInfo

Mô tả nguyên nhân gây ra lỗi kèm theo thông tin chi tiết có cấu trúc.

Ví dụ về lỗi khi liên hệ với API "pubsub.googleapis.com" khi API này chưa được bật:

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

Phản hồi này cho biết API pubsub.googleapis.com chưa được bật.

Ví dụ về lỗi được trả về khi cố gắng tạo một phiên bản Spanner ở một khu vực hết hàng:

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

Trường
reason	string Lý do xảy ra lỗi. Đây là một giá trị hằng số xác định nguyên nhân gần nhất gây ra lỗi. Lý do gây ra lỗi là duy nhất trong một miền lỗi cụ thể. Tên này chỉ được dài tối đa 63 ký tự và phải khớp với biểu thức chính quy [A-Z][A-Z0-9_]+[A-Z0-9], biểu thị UPPER_SNAKE_CASE.
domain	string Nhóm logic mà "lý do" thuộc về. Miền lỗi thường là tên dịch vụ đã đăng ký của công cụ hoặc sản phẩm tạo ra lỗi. Ví dụ: "pubsub.googleapis.com". Nếu lỗi do một số cơ sở hạ tầng phổ biến tạo ra, thì miền lỗi phải là một giá trị duy nhất trên toàn cầu để xác định cơ sở hạ tầng đó. Đối với cơ sở hạ tầng API của Google, miền lỗi là "googleapis.com".
metadata	map<string, string> Thông tin chi tiết có cấu trúc bổ sung về lỗi này. Khoá phải khớp với biểu thức chính quy [a-z][a-zA-Z0-9-_]+ nhưng tốt nhất nên là lowerCamelCase. Ngoài ra, tên phải có độ dài tối đa là 64 ký tự. Khi xác định giá trị hiện tại của một hạn mức vượt quá, các đơn vị phải nằm trong khoá chứ không phải giá trị. Ví dụ: thay vì {"instanceLimit": "100/request"}, bạn nên trả về {"instanceLimitPerRequest": "100"} nếu ứng dụng khách vượt quá số lượng phiên bản có thể được tạo trong một yêu cầu (hàng loạt).

Trợ giúp

Cung cấp đường liên kết đến tài liệu hoặc để thực hiện một hành động ngoài băng tần.

Ví dụ: nếu một quy trình kiểm tra hạn mức không thành công và có lỗi cho biết dự án gọi chưa bật dịch vụ được truy cập, thì lỗi này có thể chứa một URL trỏ trực tiếp đến đúng vị trí trong bảng điều khiển dành cho nhà phát triển để chuyển đổi bit.

Trường
links[]	Link (Các) URL trỏ đến thông tin bổ sung về cách xử lý lỗi hiện tại.

Đường liên kết

Mô tả một đường liên kết URL.

Trường
description	string Mô tả nội dung mà đường liên kết cung cấp.
url	string URL của đường liên kết.

LocalizedMessage

Cung cấp một thông báo lỗi đã được bản địa hoá và an toàn để trả về cho người dùng, thông báo này có thể được đính kèm vào một lỗi RPC.

Trường
locale	string Ngôn ngữ được dùng theo quy cách được xác định tại https://www.rfc-editor.org/rfc/bcp/bcp47.txt. Ví dụ: "en-US", "fr-CH", "es-MX"
message	string Thông báo lỗi được bản địa hoá theo ngôn ngữ ở trên.

PreconditionFailure

Mô tả những điều kiện tiên quyết không đáp ứng được.

Ví dụ: nếu một RPC không thành công vì yêu cầu người dùng xác nhận Điều khoản dịch vụ, thì RPC đó có thể liệt kê lỗi vi phạm điều khoản dịch vụ trong thông báo PreconditionFailure.

Trường
violations[]	Violation Mô tả tất cả các lỗi vi phạm điều kiện tiên quyết.

Vi phạm

Một loại thông báo dùng để mô tả một lỗi duy nhất về điều kiện tiên quyết.

Trường
type	string Loại PreconditionFailure. Bạn nên sử dụng một loại enum dành riêng cho dịch vụ để xác định các đối tượng vi phạm điều kiện tiên quyết được hỗ trợ. Ví dụ: "TOS" cho "Vi phạm Điều khoản dịch vụ".
subject	string Đối tượng (so với loại) không thành công. Ví dụ: "google.com/cloud" so với loại "TOS" sẽ cho biết điều khoản dịch vụ nào đang được tham chiếu.
description	string Nội dung mô tả về lý do điều kiện tiên quyết không đáp ứng được. Nhà phát triển có thể sử dụng nội dung mô tả này để biết cách khắc phục lỗi. Ví dụ: "Chưa chấp nhận Điều khoản dịch vụ".

QuotaFailure

Mô tả lý do kiểm tra hạn mức không thành công.

Ví dụ: nếu một dự án gọi vượt quá hạn mức hằng ngày, thì một dịch vụ có thể phản hồi bằng thông tin chi tiết QuotaFailure chứa mã dự án và nội dung mô tả về hạn mức đã vượt quá. Nếu dự án gọi chưa bật dịch vụ trong bảng điều khiển dành cho nhà phát triển, thì một dịch vụ có thể phản hồi bằng mã dự án và đặt service_disabled thành true.

Bạn cũng có thể xem các loại RetryInfo và Help để biết thêm thông tin về cách xử lý lỗi liên quan đến hạn mức.

Trường
violations[]	Violation Mô tả tất cả các lỗi vi phạm hạn mức.

Vi phạm

Một loại thông báo dùng để mô tả một trường hợp vi phạm hạn mức. Ví dụ: vượt quá hạn mức hằng ngày hoặc hạn mức tuỳ chỉnh.

Trường
subject	string Đối tượng mà bạn không kiểm tra được hạn mức. Ví dụ: "clientip:" hoặc "project:".
description	string Nội dung mô tả về lý do kiểm tra hạn mức không thành công. Khách hàng có thể sử dụng nội dung mô tả này để tìm hiểu thêm về cấu hình hạn mức trong tài liệu công khai của dịch vụ hoặc tìm hạn mức liên quan để điều chỉnh thông qua bảng điều khiển dành cho nhà phát triển. Ví dụ: "Dịch vụ bị vô hiệu hoá" hoặc "Vượt quá giới hạn hằng ngày cho các thao tác đọc".
api_service	string Dịch vụ API mà QuotaFailure.Violation bắt nguồn. Trong một số trường hợp, vấn đề về hạn mức bắt nguồn từ một Dịch vụ API khác với dịch vụ đã được gọi. Nói cách khác, một phần phụ thuộc của Dịch vụ API được gọi có thể là nguyên nhân gây ra QuotaFailure và trường này sẽ có tên dịch vụ API phụ thuộc. Ví dụ: nếu API được gọi là Kubernetes Engine API (container.googleapis.com) và một lỗi vi phạm hạn mức xảy ra trong chính Kubernetes Engine API, thì trường này sẽ là "container.googleapis.com". Mặt khác, nếu lỗi vi phạm hạn mức xảy ra khi Kubernetes Engine API tạo máy ảo trong Compute Engine API (compute.googleapis.com), thì trường này sẽ là "compute.googleapis.com".
quota_metric	string Chỉ số của hạn mức bị vi phạm. Chỉ số hạn mức là một bộ đếm có tên dùng để đo lường mức sử dụng, chẳng hạn như yêu cầu API hoặc CPU. Khi một hoạt động xảy ra trong một dịch vụ, chẳng hạn như việc phân bổ Máy ảo, một hoặc nhiều chỉ số hạn mức có thể bị ảnh hưởng. Ví dụ: "compute.googleapis.com/cpus_per_vm_family", "storage.googleapis.com/internet_egress_bandwidth".
quota_id	string Mã của hạn mức bị vi phạm. Còn được gọi là "tên giới hạn", đây là giá trị nhận dạng duy nhất của một hạn mức trong bối cảnh của một dịch vụ API. Ví dụ: "CPUS-PER-VM-FAMILY-per-project-region".
quota_dimensions	map<string, string> Các phương diện của hạn mức bị vi phạm. Mỗi hạn mức không phải là hạn mức toàn cầu đều được áp dụng cho một nhóm phương diện. Mặc dù chỉ số hạn mức xác định những gì cần tính, nhưng phương diện sẽ chỉ định những khía cạnh mà bộ đếm cần tăng. Ví dụ: hạn mức "Số CPU trên mỗi khu vực cho mỗi họ VM" áp dụng một giới hạn cho chỉ số "compute.googleapis.com/cpus_per_vm_family" trên các phương diện "region" và "vm_family". Nếu lỗi vi phạm xảy ra ở khu vực "us-central1" và đối với họ VM "n1", thì quota_dimensions sẽ là: { "region": "us-central1", "vm_family": "n1", } Khi hạn mức được áp dụng trên toàn cầu, quota_dimensions sẽ luôn trống.
quota_value	int64 Giá trị hạn mức được thực thi tại thời điểm QuotaFailure. Ví dụ: nếu giá trị hạn mức bắt buộc tại thời điểm QuotaFailure trên số lượng CPU là "10", thì giá trị của trường này sẽ phản ánh số lượng này.
future_quota_value	int64 Giá trị hạn mức mới được triển khai tại thời điểm xảy ra lỗi vi phạm. Khi quá trình triển khai hoàn tất, giá trị này sẽ được thực thi thay cho quota_value. Nếu không có quy trình triển khai nào đang diễn ra tại thời điểm vi phạm, thì trường này sẽ không được đặt. Ví dụ: nếu tại thời điểm vi phạm, một quy trình triển khai đang diễn ra và thay đổi hạn mức số lượng CPU từ 10 thành 20, thì 20 sẽ là giá trị của trường này.

RequestInfo

Chứa siêu dữ liệu về yêu cầu mà các ứng dụng có thể đính kèm khi gửi lỗi hoặc cung cấp các hình thức phản hồi khác.

Trường
request_id	string Một chuỗi không rõ ràng mà chỉ dịch vụ tạo ra chuỗi đó mới diễn giải được. Ví dụ: bạn có thể dùng mã này để xác định các yêu cầu trong nhật ký của dịch vụ.
serving_data	string Mọi dữ liệu được dùng để xử lý yêu cầu này. Ví dụ: một dấu vết ngăn xếp được mã hoá có thể được gửi lại cho nhà cung cấp dịch vụ để gỡ lỗi.

ResourceInfo

Mô tả tài nguyên đang được truy cập.

Trường
resource_type	string Tên của loại tài nguyên đang được truy cập, ví dụ: "bảng sql", "thùng lưu trữ đám mây", "tệp", "Lịch Google"; hoặc URL loại của tài nguyên: ví dụ: "type.googleapis.com/google.pubsub.v1.Topic".
resource_name	string Tên của tài nguyên đang được truy cập. Ví dụ: tên lịch được chia sẻ: "[e-mail]", nếu lỗi hiện tại là google.rpc.Code.PERMISSION_DENIED.
owner	string Chủ sở hữu tài nguyên (không bắt buộc). Ví dụ: "user:" hoặc "project:".
description	string Mô tả lỗi gặp phải khi truy cập vào tài nguyên này. Ví dụ: việc cập nhật một dự án trên đám mây có thể yêu cầu quyền writer đối với dự án trên bảng điều khiển dành cho nhà phát triển.

RetryInfo

Mô tả thời điểm mà các ứng dụng có thể thử lại một yêu cầu không thành công. Các ứng dụng có thể bỏ qua đề xuất này hoặc thử lại khi thông tin này bị thiếu trong các phản hồi lỗi.

Khách hàng luôn nên sử dụng thuật toán thời gian đợi luỹ thừa khi thử lại.

Các ứng dụng nên đợi cho đến khi hết retry_delay thời gian kể từ khi nhận được phản hồi lỗi trước khi thử lại. Nếu yêu cầu thử lại cũng không thành công, thì các ứng dụng nên sử dụng một lược đồ thời gian đợi tăng theo cấp số nhân để tăng dần độ trễ giữa các lần thử lại dựa trên retry_delay, cho đến khi đạt đến số lần thử lại tối đa hoặc đạt đến giới hạn độ trễ tối đa của lần thử lại.

Trường
retry_delay	Duration Các ứng dụng nên đợi ít nhất khoảng thời gian này giữa các lần thử lại cùng một yêu cầu.

Trạng thái

Loại Status xác định một mô hình lỗi logic phù hợp với nhiều môi trường lập trình, trong đó có API REST và API RPC. gRPC sử dụng loại này. Mỗi thông báo Status chứa 3 phần dữ liệu: mã lỗi, thông báo lỗi và thông tin cụ thể về lỗi.

Bạn có thể tìm hiểu thêm về mô hình lỗi này và cách xử lý mô hình này trong Hướng dẫn thiết kế API.

Trường
code	int32 Mã trạng thái, phải là giá trị enum của google.rpc.Code.
message	string Thông báo lỗi dành cho nhà phát triển, phải bằng tiếng Anh. Mọi thông báo lỗi mà người dùng thấy đều phải được bản địa hoá và gửi trong trường google.rpc.Status.details hoặc được ứng dụng khách bản địa hoá.
details[]	Any Danh sách các thông báo chứa thông tin cụ thể về lỗi. Có một nhóm gồm nhiều loại thông báo chung để API sử dụng.