Checkpoint 기록 API (V2)
Checkpoint 기록은 사용자가 제출한 사유나 확인 내용과 당시의 상호작용 맥락을 담습니다. 이 API는 기록을 조회하며, 조회 요청으로 해당 작업을 다시 실행하거나 승인을 발급하지 않습니다.
조회 방식 선택
| 필요한 조회 | API | 조건 |
|---|---|---|
| RID를 아는 기록 하나 | Get Record | 찾을 수 없는 기록과 접근 권한 오류를 구분 |
| RID를 아는 여러 기록 | Get Records Batch | 최대 100개, 없거나 접근할 수 없는 기록은 응답에서 제외 |
| 조건에 맞는 기록 | Search Records | 생성 시각의 기본 정렬은 DESC, 기본 페이지 크기는 100 |
세 엔드포인트는 모두 미리보기 기능으로 preview=true가 필요하며 언제든 변경되거나 제거될 수 있습니다. OAuth2로 호출하는 타사 애플리케이션에는 api:checkpoints-read 권한 범위가 필요합니다. 배치 조회와 검색은 POST이지만 기록을 읽는 작업입니다.
기록에서 확인할 내용
기록 자료형의 actingUser는 체크포인트 작업을 수행한 사용자이고 delegateUserId는 선택 필드입니다. scope는 USER_SCOPED와 RESOURCE_SCOPED를 구분하며, createdAt은 기록 생성 시각입니다. 구성, 프로젝트, 조직, 네임스페이스 및 상호작용의 식별자가 함께 제공될 수 있습니다.
checkpointedItems는 대상 스냅샷의 목록입니다. 리소스뿐 아니라 객체 집합, 액션 유형, 역할, 보안 표지, 모델과 사용자 또는 그룹 주체 등의 정보를 담을 수 있습니다. 각 항목의 type에 맞는 필드를 읽습니다.
justification은 사용자가 제출한 사유 또는 확인 내용입니다. 자유 형식의 응답, 드롭다운 선택과 추가 응답, 재인증, 확인란 선택을 구분합니다. 이름이나 경로는 개인정보 보호를 위해 가려질 수 있으므로 value가 없는 문자열 객체를 빈 값이나 원래 값의 추정치로 바꾸지 않습니다.
검색 조건과 페이지 처리
검색 필터는 동등 비교, 생성 시각 범위, 근거 텍스트 및 대상 식별자 조건을 제공합니다. and, or, not으로 조건을 결합합니다. 대상 식별자 필터와 응답의 대상 스냅샷은 서로 다른 자료형입니다.
검색의 첫 요청에서는 pageToken을 생략하고 다음 요청의 본문에 직전 nextPageToken을 넣습니다. 토큰이 JSON 문자열처럼 보여도 내부 구조를 해석하지 않고 반환된 문자열 전체를 전달합니다. 배치 조회 결과는 RID를 키로 하는 맵이므로 검색 결과의 배열 처리와 구분합니다.
애플리케이션에서 기록을 검토할 때 필요한 역할과 표시 제한은 사유 확인 기록의 조회와 권한을 따릅니다.