Status

Status 유형은 REST API 및 RPC API를 포함한 다양한 프로그래밍 환경에 적합한 논리적 오류 모델을 정의합니다. gRPC 에서 사용됩니다. 오류 모델은 다음과 같이 설계되었습니다.

  • 대부분의 사용자가 사용하고 이해하기 쉽습니다.
  • 예상치 못한 요구 사항을 충족할 수 있을 만큼 유연함

개요

Status 메시지에는 오류 코드, 오류 메시지, 오류 세부정보라는 세 가지 데이터가 포함되어 있습니다. 오류 코드는 google.rpc.Code 의 열거형 값이어야 하지만 필요한 경우 추가 오류 코드를 허용할 수도 있습니다. 오류 메시지는 개발자가 오류를 이해 하고 해결하는 데 도움이 되는 개발자용 영어 메시지여야 합니다. 사용자에게 표시되는 현지화된 오류 메시지가 필요한 경우 현지화된 메시지를 오류 세부정보에 넣거나 클라이언트에서 현지화하세요. 선택적 오류 세부정보에는 오류에 대한 임의의 정보가 포함될 수 있습니다. google.rpc 패키지에는 일반적인 오류 조건에 사용할 수 있는 사전 정의된 오류 세부 유형 집합이 있습니다.

언어 매핑

Status 메시지는 오류 모델의 논리적 표현이지만 반드시 실제 연결 형식은 아닙니다. Status 메시지가 다양한 클라이언트 라이브러리 및 다양한 유선 프로토콜에 노출되면 다르게 매핑될 수 있습니다. 예를 들어 Java의 일부 예외에 매핑될 가능성이 높지만 C의 일부 오류 코드에 매핑될 가능성이 더 높습니다.

기타 용도

오류 모델과 Status 메시지는 API 유무에 관계없이 다양한 환경에서 사용되어 다양한 환경에서 일관된 개발자 경험을 제공할 수 있습니다.

이 오류 모델의 사용 예는 다음과 같습니다.

  • 부분적인 오류. 서비스가 부분 오류를 클라이언트에 반환해야 하는 경우 부분 오류를 나타내기 위해 일반 응답에 Status 포함할 수 있습니다.

  • 워크플로 오류. 일반적인 작업 흐름에는 여러 단계가 있습니다. 각 단계에는 오류 보고를 위한 Status 메시지가 있을 수 있습니다.

  • 일괄 작업. 클라이언트가 일괄 요청 및 일괄 응답을 사용하는 경우 Status 메시지는 각 오류 하위 응답에 대해 하나씩 일괄 응답 내에서 직접 사용되어야 합니다.

  • 비동기 작업. API 호출이 응답에 비동기 작업 결과를 포함하는 경우 해당 작업의 상태는 Status 메시지를 사용하여 직접 표시되어야 합니다.

  • 벌채 반출. 일부 API 오류가 로그에 저장되면 보안/개인 정보 보호상의 이유로 필요한 제거 후에 Status 메시지를 직접 사용할 수 있습니다.

JSON 표현
{
  "code": number,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
필드
code

number

google.rpc.Code 의 열거형 값이어야 하는 상태 코드입니다.

message

string

개발자에게 표시되는 오류 메시지는 영어로 작성되어야 합니다. 사용자에게 표시되는 모든 오류 메시지는 현지화되어 google.rpc.Status.details 필드로 전송되거나 클라이언트에서 현지화되어야 합니다.

details[]

object

오류 세부정보를 전달하는 메시지 목록입니다. API에서 사용할 수 있는 공통 메시지 유형 세트가 있습니다.

임의 유형의 필드를 포함하는 객체입니다. 추가 필드 "@type" 에는 유형을 식별하는 URI가 포함되어 있습니다. 예: { "id": 1234, "@type": "types.example.com/standard/id" } .