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 | |
message | 개발자에게 표시되는 오류 메시지는 영어로 작성되어야 합니다. 사용자에게 표시되는 모든 오류 메시지는 현지화되어 |
details[] | 오류 세부정보를 전달하는 메시지 목록입니다. API에서 사용할 수 있는 공통 메시지 유형 세트가 있습니다. 임의 유형의 필드를 포함하는 객체입니다. 추가 필드 |