124 lines
13 KiB
Markdown
124 lines
13 KiB
Markdown
---
|
||
title: "official-doc / Google AIP-151 — Long-Running Operations"
|
||
source_type: official-doc
|
||
url: https://google.aip.dev/151
|
||
archive_url:
|
||
vendor: Google
|
||
related_branches: [feature-api-contract-baseline]
|
||
related_projects: [ca-skeleton]
|
||
tags: [official-doc, ca-skeleton, api-design, long-running-operation]
|
||
status: raw
|
||
confidence: high
|
||
created: 2026-05-31
|
||
last_reviewed: 2026-05-31
|
||
---
|
||
|
||
# official-doc / Google AIP-151 — Long-Running Operations
|
||
|
||
> Layer: `raw/official-docs/` — 외부 공식 문서의 원문 발췌·출처 기록.
|
||
> 검증된 요약은 `/ingest` 후 `wiki/concepts/`에 `source-summary-template` 형식으로 별도 작성. 원본은 raw에 영구 보관.
|
||
|
||
## Parent / 활용 branch
|
||
|
||
> 이 자료는 **혼자 존재하지 않는다.** 어느 branch 의 구현 결정의 **근거**로서 보관됨.
|
||
|
||
| Branch | 이 자료가 정당화하는 결정 |
|
||
|---|---|
|
||
| [[raw/branch-notes/feature-api-contract-baseline]] | D17: Long-running operation (LRO) 응답 = 202 Accepted + `Location: /v1/operations/{id}` + envelope `data.{operationId,statusUrl}` · polling endpoint `GET /v1/operations/{id}` 의 status enum {PENDING, RUNNING, SUCCEEDED, FAILED, CANCELLED} — 현재 UNSUPPORTED_DECISION 라벨을 본 raw 의 normative reference 로 해소 |
|
||
|
||
## 출처 / Source
|
||
|
||
- 원본 URL: https://google.aip.dev/151
|
||
- 아카이브 URL: (미등록)
|
||
- 저자 / 조직: Google (API Improvement Proposals 커뮤니티)
|
||
- 발행일: 2019-07-25
|
||
- 마지막 수정일: 2025-02-04 (Changelog 기준 — errors 섹션 명료화)
|
||
- 마지막 확인일: 2026-05-31
|
||
|
||
## 왜 저장했는지 / Why archived
|
||
|
||
`feature-api-contract-baseline` 의 D17 결정(LRO 응답 패턴 — 202 Accepted + Location + polling)이 `UNSUPPORTED_DECISION` 상태였으며, Google AIP-151 이 해당 결정의 1차 normative reference 로 지목되었다. AIP-151 은 비동기 long-running operation 의 응답 형식(`google.longrunning.Operation`)·done/result/error 분기·polling 방식을 정의하며, 본 branch 의 HTTP REST 매핑의 설계 근거로 활용된다.
|
||
|
||
## 핵심 인용 / Key quotes (verbatim)
|
||
|
||
> Self-Grep 통과 — 모든 인용은 `/tmp/source-fetch-1780186240.txt` 에서 `grep -nF` 로 존재 확인됨.
|
||
|
||
> [§Preamble, line 792] "Occasionally, an API may need to expose a method that takes a significant amount of time to complete."
|
||
|
||
> [§Preamble, line 798–799] "Essentially, the user is given a token that can be used to track progress and retrieve the result."
|
||
|
||
> [§Guidance, line 803–805] "Individual API methods that might take a significant amount of time to complete should return a `google.longrunning.Operation` object instead of the ultimate response message."
|
||
|
||
> [§Guidance / validate-only, line 857–859] "A successful response with an Operation which is already complete, with the `done` field set to `true`, and a valid (but potentially empty) response message in the `response` field, wrapped in a `google.protobuf.Any` message."
|
||
|
||
> [§Guidance / validate-only, line 865–867] "An Operation with the `done` field set to `false`, to indicate long-running validation. In this case, the `name` field must be set, to allow clients to poll the long-running validation operation until it has completed."
|
||
|
||
> [§Guidance / validate-only, line 870–872] "Unsuccessful validation must eventually be represented by an operation with `done=true` and the error details provided in the `error` field."
|
||
|
||
> [§Errors, line 926–928] "Operations that fail during their execution phase must return an error response (AIP-193), placed in the `Operation.error` `google.rpc.Status` field."
|
||
|
||
> [§Note / thumb rule, line 877–879] "User expectations can vary on what is considered 'a significant amount of time' depending on what work is being done. A good rule of thumb is 10 seconds."
|
||
|
||
> [§Guidance, line 829–830] "The method must include a `google.longrunning.operation_info` annotation, which must define both response and metadata types."
|
||
|
||
## Claims Extracted / 추출된 주장
|
||
|
||
> 이 자료가 **직접 말하는 것만** claim 으로 분리한다. 내 프로젝트에 적용한 결론은 여기 쓰지 않는다.
|
||
|
||
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
||
|---|---|---|---|---|---|
|
||
| AIP151-C1 | 처리 시간이 "significant"한 메서드는 최종 응답 대신 `google.longrunning.Operation` 객체를 반환해야 한다 | [§Guidance, line 803–805] "Individual API methods that might take a significant amount of time to complete should return a `google.longrunning.Operation` object instead of the ultimate response message." | `official-reference` | Google API Design Guide 를 따르는 protobuf/gRPC 기반 API | "significant"의 threshold 를 직접 숫자로 normative 정의하지 않음 (thumb rule 10초는 참고값). REST API 에 그대로 적용 시 HTTP 202 + Location 매핑은 본 문서 외 별도 결정 필요 |
|
||
| AIP151-C2 | `google.longrunning.operation_info` annotation 에 `response_type` 과 `metadata_type` 양쪽 모두 정의해야 한다 | [§Guidance, line 829–830] "The method must include a `google.longrunning.operation_info` annotation, which must define both response and metadata types." | `official-reference` | Google protobuf/gRPC API | `response_type` / `metadata_type` 의 구체적 내용(필드명, 구조)은 각 API가 정의. REST 매핑에서 이 annotation 이 없어도 기능은 동작할 수 있음 — 규약 준수 여부 문제 |
|
||
| AIP151-C3 | Operation 이 완료(`done=true`)되면 `response` 필드에 유효한 응답 메시지가 있어야 한다 | [§Guidance/validate-only, line 857–859] "A successful response with an Operation which is already complete, with the `done` field set to `true`, and a valid (but potentially empty) response message in the `response` field, wrapped in a `google.protobuf.Any` message." | `official-reference` | `done=true` 인 Operation 의 성공 분기 | `response` 필드의 구체적 shape 는 API 별로 다름. HTTP REST 전환 시 `result` 객체의 JSON 표현 방식은 본 AIP 외 별도 결정 |
|
||
| AIP151-C4 | 진행 중인 Operation 은 `done=false` 이며, `name` 필드가 반드시 설정되어야 클라이언트가 polling 할 수 있다 | [§Guidance/validate-only, line 865–867] "An Operation with the `done` field set to `false`, to indicate long-running validation. In this case, the `name` field must be set, to allow clients to poll the long-running validation operation until it has completed." | `official-reference` | 진행 중(`done=false`) Operation 의 polling 패턴 | `name` 필드의 구체적 형식(예: `operations/{id}`)은 AIP-122 (Resource names) 가 별도 정의. REST HTTP 응답의 `Location` header 와 `name` 필드의 매핑은 본 AIP 가 normative 하게 규정하지 않음 |
|
||
| AIP151-C5 | 실패한 Operation 은 최종적으로 `done=true` + `error` 필드에 오류 상세가 담겨야 한다 | [§Guidance/validate-only, line 870–872] "Unsuccessful validation must eventually be represented by an operation with `done=true` and the error details provided in the `error` field." | `official-reference` | `done=true` 인 Operation 의 실패 분기 | `error` 필드의 구조는 `google.rpc.Status` — REST 매핑 시 HTTP 상태 코드와의 관계는 AIP-193 (Errors) 가 별도 정의. `FAILED`/`CANCELLED` 같은 상태 enum 어휘는 본 AIP 에 없음 |
|
||
| AIP151-C6 | 실행 단계에서 실패한 Operation 의 오류는 `Operation.error` 의 `google.rpc.Status` 필드에 위치해야 한다 | [§Errors, line 926–928] "Operations that fail during their execution phase must return an error response (AIP-193), placed in the `Operation.error` `google.rpc.Status` field." | `official-reference` | Operation 실행 중 발생한 terminal error | non-terminal error(중간 경고 등)는 `metadata` 에 위치 가능. HTTP REST 전환 시 `google.rpc.Status` → JSON error 객체 매핑은 별도 작업 |
|
||
| AIP151-C7 | 'significant amount of time' 의 참고 기준은 10초이며, 이 기준은 사용자 기대치와 작업 종류에 따라 달라질 수 있다 | [§Note, line 877–879] "User expectations can vary on what is considered 'a significant amount of time' depending on what work is being done. A good rule of thumb is 10 seconds." | `official-reference` | LRO 적용 여부 판단 시 참고 기준 | 10초는 thumb rule(참고값)이며 normative threshold 아님. API 설계자가 컨텍스트에 따라 다른 기준 적용 가능 |
|
||
|
||
## Usage Boundaries / 적용 경계
|
||
|
||
### 이 자료가 직접 증명하는 것
|
||
|
||
- `AIP151-C1`: 장시간 처리 메서드는 최종 응답 대신 `google.longrunning.Operation` 을 반환해야 함 (Google API Design Guide 기준)
|
||
- `AIP151-C2`: `operation_info` annotation 에 `response_type` + `metadata_type` 양쪽 정의 의무
|
||
- `AIP151-C3`: 성공 완료(`done=true`) 시 `response` 필드에 유효한 응답 메시지 존재
|
||
- `AIP151-C4`: 진행 중(`done=false`) 시 `name` 필드 MUST 설정 (polling 가능 조건)
|
||
- `AIP151-C5`: 실패 완료(`done=true`) 시 `error` 필드에 오류 상세 존재
|
||
- `AIP151-C6`: 실행 단계 실패 오류는 `Operation.error` (`google.rpc.Status`) 에 위치
|
||
- `AIP151-C7`: "significant time" 의 참고 기준 = 10초 (thumb rule, non-normative threshold)
|
||
|
||
### 이 자료가 증명하지 않는 것
|
||
|
||
- **AIP-151 은 IETF/W3C 표준이 아님**: Google API design community guideline (`official-reference` strength). 특정 HTTP 표준이나 REST 규범을 대체하지 않음. 다른 API 설계 조직이 이를 따를 의무 없음.
|
||
- **Protobuf 컨텍스트 우선**: AIP-151 의 `Operation` resource, `done/result/error`, `operation_info` annotation 은 protobuf 정의. REST/JSON API 에 적용 시 다음은 normative 하지 않음:
|
||
- HTTP 202 응답 상태 코드 (RFC 9110 §15.3.3 영역)
|
||
- `Location` response header (RFC 9110 §10.2.2 영역)
|
||
- JSON envelope `data.operationId` / `data.statusUrl` 필드 명명
|
||
- polling endpoint URL 패턴 (`/v1/operations/{id}`)
|
||
- **`name` 필드 형식**: AIP-151 은 `name` 이 설정되어야 한다고만 명시. 구체적 형식(`operations/{id}` 등)은 AIP-122 (Resource names) 가 정의.
|
||
- **status enum 어휘**: 본 branch 의 `{PENDING, RUNNING, SUCCEEDED, FAILED, CANCELLED}` 5종 enum 은 **AIP-151 에 없음**. AIP-151 은 `done` (boolean) + `result` (oneof response/error) 의 이진 완료 모델만 정의. 5종 enum 은 project-internal 매핑 — AIP-151 이 직접 보증하지 않음.
|
||
- **Operation 간 선후 관계**: AIP-151 의 `name` field 가 resource name 기반임을 시사하지만 operation 의 순서/큐잉은 본 문서 범위 밖.
|
||
- **Cancellation method**: AIP-151 HTML 본문에서 cancellation (`operations/{id}:cancel`) 에 대한 명시적 normative 진술 추출 불가 — 별도 확인 필요 (`needs-confirmation`).
|
||
|
||
### 내 프로젝트에 적용하려면 추가 확인이 필요한 것
|
||
|
||
- **REST HTTP 매핑의 normative 근거 보강**: 202 Accepted + `Location` header 의 정규 근거는 RFC 9110 §15.3.3 (202) + §10.2.2 (Location) — `feature-api-contract-baseline` 의 RFC9110-C22 (§15.3.3) + RFC9110-C21 (§10.2.3 Retry-After) 발췌 완료 후 D17 의 나머지 HTTP 계층 근거 채움.
|
||
- **status enum 5종의 별도 설계 근거**: PENDING/RUNNING/SUCCEEDED/FAILED/CANCELLED 가 AIP-151 의 done/error 이진 모델과 매핑되는 방식은 ca-skeleton project-internal 결정 — project note 또는 별도 decision record 로 명시 필요.
|
||
- **envelope 형식(`data.operationId`, `data.statusUrl`) 매핑**: AIP-151 의 `Operation.name` / `done` / `result` 와 본 branch envelope 간 매핑은 `feature-schema-serialization-contract` 또는 project note 에서 별도 결정 필요.
|
||
- **polling endpoint URL pattern(`/v1/operations/{id}`)의 근거**: AIP-122 (Resource names) + AIP-151 `name` field 의 형식 정의를 추가로 확인 필요.
|
||
|
||
## 메모 / Notes
|
||
|
||
- AIP-151 의 `Operation` resource 는 `google.longrunning.Operation` proto 정의로 `name` (string), `metadata` (Any), `done` (bool), `error` (google.rpc.Status), `response` (Any) 필드로 구성. HTML 파싱에서 proto 정의 코드 블록 추출이 부분적으로 이루어졌고, 필드 목록 전체는 공식 proto reference (https://cloud.google.com/apis/design/design_patterns#long_running_operations) 에서 추가 확인 권장.
|
||
- AIP-151 의 Changelog 에서 2025-02-04 업데이트가 errors 섹션 명료화 — 본 발췌의 `AIP151-C6` 근거 섹션.
|
||
- Cancellation (`operations/{id}:cancel`) 은 AIP-151 본문 텍스트에서 verbatim 발췌 불가 (파싱된 plain text 에 미포함 가능). 공식 proto reference 또는 AIP 원문 직접 확인 필요.
|
||
- AIP 의 `official-reference` strength: Google AIP 는 Google 내부 + 커뮤니티 guideline 이며 IETF/W3C 수준의 국제 표준 아님. 단 Google Cloud API, gRPC, Protobuf 를 활용하는 프로젝트에서는 사실상 표준 (de facto). `official-vendor-doc` 보다 약하고 `official-standard` 보다 확실히 약함.
|
||
|
||
## Related / 관련
|
||
|
||
- [[raw/official-docs/api-versioning-google-aip-180]] — AIP-180 (backward compatibility), 같은 AIP 시리즈
|
||
- [[raw/official-docs/google-aip-185-resource-versioning]] — AIP-185 (resource versioning), 같은 AIP 시리즈
|
||
- [[raw/official-docs/rfc9110-http-semantics]] — RFC 9110 §15.3.3 202 Accepted + §10.2.2 Location + §10.2.3 Retry-After — D17 LRO 의 HTTP 계층 normative 근거
|
||
- (미등록, 예정) [[raw/official-docs/google-aip-122-resource-names]] — Operation `name` 필드 형식 규칙
|
||
- (미등록, 예정) `wiki/concepts/long-running-operation-pattern` — 본 raw 를 인용한 canonical 요약 (생성 시)
|