llm-wiki/raw/official-docs/google-aip-151-long-running-operations.md

title, source_type, url, archive_url, vendor, related_branches, related_projects, tags, status, confidence, created, last_reviewed

title	source_type	url	archive_url	vendor	related_branches	related_projects	tags	status	confidence	created	last_reviewed
official-doc / Google AIP-151 — Long-Running Operations	official-doc	https://google.aip.dev/151		Google	feature-api-contract-baseline	ca-skeleton	official-doc ca-skeleton api-design long-running-operation	raw	high	2026-05-31	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 요약 (생성 시)