rpc: new message ErrorInfo, other comment updates
PiperOrigin-RevId: 290781668
This commit is contained in:
Google APIs
Copybara-Service
parent
26420ef4e4
commit
a3b23dcb2e
|
|
@ -1,4 +1,4 @@
|
|||
// Copyright 2017 Google Inc.
|
||||
// Copyright 2019 Google LLC.
|
||||
//
|
||||
// Licensed under the Apache License, Version 2.0 (the "License");
|
||||
// you may not use this file except in compliance with the License.
|
||||
|
|
@ -11,6 +11,7 @@
|
|||
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
// See the License for the specific language governing permissions and
|
||||
// limitations under the License.
|
||||
//
|
||||
|
||||
syntax = "proto3";
|
||||
|
||||
|
|
@ -22,7 +23,7 @@ option java_outer_classname = "CodeProto";
|
|||
option java_package = "com.google.rpc";
|
||||
option objc_class_prefix = "RPC";
|
||||
|
||||
// The canonical error codes for Google APIs.
|
||||
// The canonical error codes for gRPC APIs.
|
||||
//
|
||||
//
|
||||
// Sometimes multiple error codes may apply. Services should return
|
||||
|
|
@ -170,7 +171,8 @@ enum Code {
|
|||
|
||||
// The service is currently unavailable. This is most likely a
|
||||
// transient condition, which can be corrected by retrying with
|
||||
// a backoff.
|
||||
// a backoff. Note that it is not always safe to retry
|
||||
// non-idempotent operations.
|
||||
//
|
||||
// See the guidelines above for deciding between `FAILED_PRECONDITION`,
|
||||
// `ABORTED`, and `UNAVAILABLE`.
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
// Copyright 2017 Google Inc.
|
||||
// Copyright 2019 Google LLC.
|
||||
//
|
||||
// Licensed under the Apache License, Version 2.0 (the "License");
|
||||
// you may not use this file except in compliance with the License.
|
||||
|
|
@ -11,6 +11,7 @@
|
|||
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
// See the License for the specific language governing permissions and
|
||||
// limitations under the License.
|
||||
//
|
||||
|
||||
syntax = "proto3";
|
||||
|
||||
|
|
@ -35,7 +36,7 @@ option objc_class_prefix = "RPC";
|
|||
// receiving the error response before retrying. If retrying requests also
|
||||
// fail, clients should use an exponential backoff scheme to gradually increase
|
||||
// the delay between retries based on `retry_delay`, until either a maximum
|
||||
// number of retires have been reached or a maximum retry delay cap has been
|
||||
// number of retries have been reached or a maximum retry delay cap has been
|
||||
// reached.
|
||||
message RetryInfo {
|
||||
// Clients should wait at least this long between retrying the same request.
|
||||
|
|
@ -60,7 +61,7 @@ message DebugInfo {
|
|||
// a service could respond with the project id and set `service_disabled`
|
||||
// to true.
|
||||
//
|
||||
// Also see RetryDetail and Help types for other details about handling a
|
||||
// Also see RetryInfo and Help types for other details about handling a
|
||||
// quota failure.
|
||||
message QuotaFailure {
|
||||
// A message type used to describe a single quota violation. For example, a
|
||||
|
|
@ -85,6 +86,53 @@ message QuotaFailure {
|
|||
repeated Violation violations = 1;
|
||||
}
|
||||
|
||||
// Describes the cause of the error with structured details.
|
||||
//
|
||||
// Example of an error when contacting the "pubsub.googleapis.com" API when it
|
||||
// is not enabled:
|
||||
// { "type": "API_DISABLED"
|
||||
// "domain": "googleapis.com"
|
||||
// "metadata": {
|
||||
// "resource": "projects/123",
|
||||
// "service": "pubsub.googleapis.com"
|
||||
// }
|
||||
// }
|
||||
// This response indicates that the pubsub.googleapis.com API is not enabled.
|
||||
//
|
||||
// Example of an error that is returned when attempting to create a Spanner
|
||||
// instance in a region that is out of stock:
|
||||
// { "type": "STOCKOUT"
|
||||
// "domain": "spanner.googleapis.com",
|
||||
// "metadata": {
|
||||
// "availableRegions": ""us-central1,us-east2"
|
||||
// }
|
||||
// }
|
||||
//
|
||||
message ErrorInfo {
|
||||
// The type of the error. This is a constant value that identifies the
|
||||
// proximate cause of the error. Error types are unique within a particular
|
||||
// source of errors. This should be at most 63 characters and match
|
||||
// /[A-Z0-9_]+/.
|
||||
string type = 1;
|
||||
|
||||
// The logical grouping to which the "type" belongs. Often "domain" will
|
||||
// contain the registered service name of the tool or product that is the
|
||||
// source of the error. Example: "pubsub.googleapis.com". If the error is
|
||||
// common across many APIs, the first segment of the example above will be
|
||||
// omitted. The value will be, "googleapis.com".
|
||||
string domain = 2;
|
||||
|
||||
// Additional structured details about this error.
|
||||
//
|
||||
// Keys should match /[a-zA-Z0-9-_]/ and be limited to 64 characters in
|
||||
// length. When identifying the current value of an exceeded limit, the units
|
||||
// should be contained in the key, not the value. For example, rather than
|
||||
// {"instanceLimit": "100/request"}, should be returned as,
|
||||
// {"instanceLimitPerRequest": "100"}, if the client exceeds the number of
|
||||
// instances that can be created in a single (batch) request.
|
||||
map<string, string> metadata = 3;
|
||||
}
|
||||
|
||||
// Describes what preconditions have failed.
|
||||
//
|
||||
// For example, if an RPC failed because it required the Terms of Service to be
|
||||
|
|
@ -94,13 +142,13 @@ message PreconditionFailure {
|
|||
// A message type used to describe a single precondition failure.
|
||||
message Violation {
|
||||
// The type of PreconditionFailure. We recommend using a service-specific
|
||||
// enum type to define the supported precondition violation types. For
|
||||
// enum type to define the supported precondition violation subjects. For
|
||||
// example, "TOS" for "Terms of Service violation".
|
||||
string type = 1;
|
||||
|
||||
// The subject, relative to the type, that failed.
|
||||
// For example, "google.com/cloud" relative to the "TOS" type would
|
||||
// indicate which terms of service is being referenced.
|
||||
// For example, "google.com/cloud" relative to the "TOS" type would indicate
|
||||
// which terms of service is being referenced.
|
||||
string subject = 2;
|
||||
|
||||
// A description of how the precondition failed. Developers can use this
|
||||
|
|
@ -153,8 +201,7 @@ message ResourceInfo {
|
|||
|
||||
// The name of the resource being accessed. For example, a shared calendar
|
||||
// name: "example.com_4fghdhgsrgh@group.calendar.google.com", if the current
|
||||
// error is
|
||||
// [google.rpc.Code.PERMISSION_DENIED][google.rpc.Code.PERMISSION_DENIED].
|
||||
// error is [google.rpc.Code.PERMISSION_DENIED][google.rpc.Code.PERMISSION_DENIED].
|
||||
string resource_name = 2;
|
||||
|
||||
// The owner of the resource (optional).
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
// Copyright 2017 Google Inc.
|
||||
// Copyright 2019 Google LLC.
|
||||
//
|
||||
// Licensed under the Apache License, Version 2.0 (the "License");
|
||||
// you may not use this file except in compliance with the License.
|
||||
|
|
@ -11,6 +11,7 @@
|
|||
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
// See the License for the specific language governing permissions and
|
||||
// limitations under the License.
|
||||
//
|
||||
|
||||
syntax = "proto3";
|
||||
|
||||
|
|
@ -18,6 +19,7 @@ package google.rpc;
|
|||
|
||||
import "google/protobuf/any.proto";
|
||||
|
||||
option cc_enable_arenas = true;
|
||||
option go_package = "google.golang.org/genproto/googleapis/rpc/status;status";
|
||||
option java_multiple_files = true;
|
||||
option java_outer_classname = "StatusProto";
|
||||
|
|
@ -26,66 +28,18 @@ option objc_class_prefix = "RPC";
|
|||
|
||||
// The `Status` type defines a logical error model that is suitable for
|
||||
// different programming environments, including REST APIs and RPC APIs. It is
|
||||
// used by [gRPC](https://github.com/grpc). The error model is designed to be:
|
||||
// used by [gRPC](https://github.com/grpc). Each `Status` message contains
|
||||
// three pieces of data: error code, error message, and error details.
|
||||
//
|
||||
// - Simple to use and understand for most users
|
||||
// - Flexible enough to meet unexpected needs
|
||||
//
|
||||
// # Overview
|
||||
//
|
||||
// The `Status` message contains three pieces of data: error code, error
|
||||
// message, and error details. The error code should be an enum value of
|
||||
// [google.rpc.Code][google.rpc.Code], but it may accept additional error codes
|
||||
// if needed. The error message should be a developer-facing English message
|
||||
// that helps developers *understand* and *resolve* the error. If a localized
|
||||
// user-facing error message is needed, put the localized message in the error
|
||||
// details or localize it in the client. The optional error details may contain
|
||||
// arbitrary information about the error. There is a predefined set of error
|
||||
// detail types in the package `google.rpc` that can be used for common error
|
||||
// conditions.
|
||||
//
|
||||
// # Language mapping
|
||||
//
|
||||
// The `Status` message is the logical representation of the error model, but it
|
||||
// is not necessarily the actual wire format. When the `Status` message is
|
||||
// exposed in different client libraries and different wire protocols, it can be
|
||||
// mapped differently. For example, it will likely be mapped to some exceptions
|
||||
// in Java, but more likely mapped to some error codes in C.
|
||||
//
|
||||
// # Other uses
|
||||
//
|
||||
// The error model and the `Status` message can be used in a variety of
|
||||
// environments, either with or without APIs, to provide a
|
||||
// consistent developer experience across different environments.
|
||||
//
|
||||
// Example uses of this error model include:
|
||||
//
|
||||
// - Partial errors. If a service needs to return partial errors to the client,
|
||||
// it may embed the `Status` in the normal response to indicate the partial
|
||||
// errors.
|
||||
//
|
||||
// - Workflow errors. A typical workflow has multiple steps. Each step may
|
||||
// have a `Status` message for error reporting.
|
||||
//
|
||||
// - Batch operations. If a client uses batch request and batch response, the
|
||||
// `Status` message should be used directly inside batch response, one for
|
||||
// each error sub-response.
|
||||
//
|
||||
// - Asynchronous operations. If an API call embeds asynchronous operation
|
||||
// results in its response, the status of those operations should be
|
||||
// represented directly using the `Status` message.
|
||||
//
|
||||
// - Logging. If some API errors are stored in logs, the message `Status` could
|
||||
// be used directly after any stripping needed for security/privacy reasons.
|
||||
// You can find out more about this error model and how to work with it in the
|
||||
// [API Design Guide](https://cloud.google.com/apis/design/errors).
|
||||
message Status {
|
||||
// The status code, which should be an enum value of
|
||||
// [google.rpc.Code][google.rpc.Code].
|
||||
// The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
|
||||
int32 code = 1;
|
||||
|
||||
// A developer-facing error message, which should be in English. Any
|
||||
// user-facing error message should be localized and sent in the
|
||||
// [google.rpc.Status.details][google.rpc.Status.details] field, or localized
|
||||
// by the client.
|
||||
// [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
|
||||
string message = 2;
|
||||
|
||||
// A list of messages that carry the error details. There is a common set of
|
||||
|
|
|
|||
Loading…
Reference in New Issue