작업

이 리소스는 네트워크 API 호출의 결과인 장기 실행 작업을 나타냅니다.

JSON 표현

{
  "name": string,
  "metadata": {
    "@type": string,
    field1: ...,
    ...
  },
  "done": boolean,

  // Union field result can be only one of the following:
  "error": {
    object(Status)
  },
  "response": {
    "@type": string,
    field1: ...,
    ...
  }
  // End of list of possible types for union field result.
}
필드
name

string

서버에 할당된 이름으로, 해당 이름을 최초로 반환한 서비스 내에서만 고유합니다. 기본 HTTP 매핑을 사용하는 경우 nameoperations/some/unique/name 형식이어야 합니다.

metadata

object

작업과 관련된 서비스별 메타데이터입니다. 일반적으로 진행률 정보 및 생성 시간과 같은 일반 메타데이터가 포함됩니다. 일부 서비스는 이러한 메타데이터를 제공하지 않을 수 있습니다. 장기 실행 작업을 반환하는 메소드는 메타데이터 유형이 있는 경우 이를 문서화해야 합니다.

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

done

boolean

값이 false이면 작업이 아직 진행 중이라는 의미입니다. true이면 작업이 완료된 것이며, error 또는 response를 사용할 수 있습니다.

공용체 필드 result는 작업 결과로 error 또는 유효한 response일 수 있습니다. done == false이면 errorresponse도 설정되지 않습니다. done == true이면 error 또는 response 중 하나만 설정됩니다. result는 다음 중 하나여야 합니다.
error

object(Status)

실패하거나 취소된 작업의 오류 결과입니다.

response

object

성공한 작업의 일반적인 응답입니다. Delete와 같이 원래 메소드가 성공 시 데이터를 반환하지 않는 경우 응답은 google.protobuf.Empty입니다. 원래 메소드가 표준 Get/Create/Update인 경우 응답은 리소스여야 합니다. 다른 메소드의 경우 응답은 XxxResponse 유형이어야 하며, 여기에서 Xxx는 원래 메소드의 이름입니다. 예를 들어 원래 메소드의 이름이 TakeSnapshot()이면 응답 유형은 TakeSnapshotResponse로 예상할 수 있습니다.

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

상태

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

  • 대부분의 사용자가 쉽게 사용하고 이해할 수 있는 단순성
  • 예기치 않은 요구사항에 대응할 수 있는 유연성

개요

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

언어 매핑

Status 메시지는 오류 모델의 논리적 표현이지만 실제 전송 형식이 아닐 수도 있습니다. Status 메시지는 다양한 클라이언트 라이브러리 및 다양한 전송 프로토콜에 노출됨에 따라 서로 다르게 매핑될 수 있습니다. 예를 들어 자바에서는 특정한 예외에 매핑되고, 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" }