아티팩트 및 카탈로그
게시된 아티팩트: 목록, 세부 정보, 콘텐츠, 주석, 참조, 검색, 카탈로그 감사와 변경 피드.
이 그룹의 작업과 각 작업의 액세스 규칙, 재시도 규칙, 매개 변수, 응답입니다. 모든 요청에는 키가 포함됩니다: Authorization: Bearer <키>(“인증” 참조).
작업
아티팩트 어노테이션 조회
GET HEAD /api/v1/repositories/{repository}/artifacts/{id}/annotations
액세스: 리포지토리 권한: annotation.read; 파일 키: read · 재시도: 반복해도 안전함(읽기)
게시된 아티팩트의 현재 레이블, 메타데이터, 컬렉션을 revision과 함께 반환합니다. 리비전 0은 아직 교체한 적이 없다는 뜻으로, 레이블과 메타데이터는 업로드를 만들 때 지정한 값이고 컬렉션은 비어 있습니다. 이 리비전을 setAnnotations에 expectedRevision으로 전달합니다.
매개 변수
| 이름 | 위치 | 형식 | 필수 | 규칙 |
|---|---|---|---|---|
repository | 경로 | string | 예 | ^[a-z0-9][a-z0-9_-]{0,63}$ 패턴과 일치 |
id | 경로 | string (uuid) | 예 | — |
응답 200
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
revision | integer | 예 | 0–2147483647 |
labels | string 배열 | 예 | 요소 32개 이하 |
metadata | string 맵 | 예 | 항목 32개 이하 |
collections | string 배열 | 예 | 요소 32개 이하 |
응답: 200, 400, 401, 403, 404, 409, 422, 503, 507
예제
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/annotations" \
-H "Authorization: Bearer $ARKVORY_TOKEN"아티팩트 어노테이션 교체
PUT /api/v1/repositories/{repository}/artifacts/{id}/annotations
액세스: 리포지토리 권한: annotation.write, artifact.read; 파일 키: read, write · 재시도: 예상 리비전으로만 반복(compare-and-swap)
게시된 아티팩트의 labels, metadata, collections 필드를 한 번에 교체하며, value에서 생략한 필드는 비게 됩니다. expectedRevision은 현재 리비전(첫 변경이면 0)이어야 하며, 그렇지 않으면 409 revision_mismatch이므로 어노테이션을 다시 읽고 변경을 다시 적용합니다. 레이블과 컬렉션은 각각 32개까지(1–64자의 문자, 숫자, _.:-), 메타데이터 항목은 32개까지(값은 1,024자까지) 허용되며, 바이트와 원래의 디스크립터는 바뀌지 않습니다.
매개 변수
| 이름 | 위치 | 형식 | 필수 | 규칙 |
|---|---|---|---|---|
repository | 경로 | string | 예 | ^[a-z0-9][a-z0-9_-]{0,63}$ 패턴과 일치 |
id | 경로 | string (uuid) | 예 | — |
요청 본문 (application/json)
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
expectedRevision | integer | 예 | 0–2147483646 |
value | object | 예 | — |
value.labels | string 배열 | 아니요 | 요소 32개 이하 |
value.metadata | string 맵 | 아니요 | 항목 32개 이하 |
value.collections | string 배열 | 아니요 | 요소 32개 이하 |
응답 200
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
revision | integer | 예 | 0–2147483647 |
labels | string 배열 | 예 | 요소 32개 이하 |
metadata | string 맵 | 예 | 항목 32개 이하 |
collections | string 배열 | 예 | 요소 32개 이하 |
응답: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
예제
curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/annotations" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"expectedRevision":0,"value":{}}'아티팩트를 UPack 패키지로 등록
POST /api/v1/repositories/{repository}/artifacts/{id}/package
액세스: 리포지토리 권한: package.publish, artifact.read; 파일 키: read, write · 재시도: 반복해도 안전함: 같은 요청은 같은 결과를 냄
게시된 아티팩트를 UPack ZIP으로 열어 루트의 upack.json(name, 선택 사항인 group, SemVer version)을 읽고, 그 패키지 버전을 아티팩트에 등록합니다. 안전하지 않거나 올바르지 않은 아카이브는 400으로 거부됩니다. 버전은 변경할 수 없습니다. 같은 아티팩트를 다시 등록하면 같은 항목을 반환하고, 이미 있는 그룹, 이름, 버전(대소문자 구분 없이 비교)에 다른 아티팩트를 등록하면 409 version_exists입니다. 등록 후 이 버전은 listPackages에 나타나며 이름, 범위, 스테이지로 확인할 수 있습니다.
매개 변수
| 이름 | 위치 | 형식 | 필수 | 규칙 |
|---|---|---|---|---|
repository | 경로 | string | 예 | ^[a-z0-9][a-z0-9_-]{0,63}$ 패턴과 일치 |
id | 경로 | string (uuid) | 예 | — |
응답 200
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
group | string | 아니요 | — |
name | string | 아니요 | — |
version | string | 아니요 | — |
artifactId | string (uuid) | 아니요 | — |
manifest | object | 아니요 | — |
응답: 200, 400, 401, 403, 404, 405, 409, 422, 503, 507
예제
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/package" \
-H "Authorization: Bearer $ARKVORY_TOKEN"아티팩트 검색
GET HEAD /api/v1/repositories/{repository}/search
액세스: 리포지토리 권한: artifact.list; 파일 키: read · 재시도: 반복해도 안전함(읽기)
게시된 아티팩트를 다음 조건으로 찾습니다. q(이름 또는 현재 메타데이터 값에 포함된 부분 문자열, 대소문자 구분 없음), 현재 label과 정확히 일치하는 값, collection, 함께 지정해야 하는 metadataKey/metadataValue 쌍입니다. 지정한 필터는 모두 일치해야 합니다. 결과는 ID 순으로 100개씩 페이지로 나뉘고, 각 항목에 크기, 생성·게시 시각, 현재 레이블, 승격 스테이지가 있으며 after에 next 값을 넣어 이어서 조회합니다. 메타데이터와 컬렉션은 반환되지 않으므로 getAnnotations로 읽습니다.
매개 변수
| 이름 | 위치 | 형식 | 필수 | 규칙 |
|---|---|---|---|---|
repository | 경로 | string | 예 | ^[a-z0-9][a-z0-9_-]{0,63}$ 패턴과 일치 |
q | 쿼리 | string | 아니요 | — |
label | 쿼리 | string | 아니요 | — |
collection | 쿼리 | string | 아니요 | — |
after | 쿼리 | string | 아니요 | — |
metadataKey | 쿼리 | string | 아니요 | ^[a-zA-Z][a-zA-Z0-9_.-]{0,63}$ 패턴과 일치; 64자 이하; Exact metadata key; requires metadataValue. |
metadataValue | 쿼리 | string | 아니요 | 1024자 이하; Exact case-sensitive value; requires metadataKey. Empty string is allowed. |
응답 200
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
items | object 배열 | 예 | 요소 100개 이하 |
items[].id | string (uuid) | 예 | — |
items[].name | string | 예 | — |
items[].size | string | 예 | 10진수 숫자로 쓴 정수이며 문자열로 전송; 바이트 크기, 10진 문자열 |
items[].createdAt | string (date-time) | 예 | 업로드 예약 시각 |
items[].publishedAt | string (date-time) | 예 | null일 수 있음; 게시 시각. 기록된 것이 없을 때만 null |
items[].labels | string 배열 | 예 | 요소 32개 이하; 현재 레이블: 교체된 경우 어노테이션, 그렇지 않으면 업로드 디스크립터 |
items[].stages | string 배열 | 예 | 요소 16개 이하; 각 요소: ^[a-z0-9][a-z0-9_.-]{0,31}$ 패턴과 일치; 현재 승격 스테이지, 바이트 순서 |
next | string (uuid) | 예 | null일 수 있음; 가득 찬 페이지의 마지막 ID. after로 전달합니다 |
응답: 200, 400, 401, 403, 404, 409, 422, 503, 507
예제
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/search" \
-H "Authorization: Bearer $ARKVORY_TOKEN"리포지토리 카탈로그 감사 기록 조회
GET HEAD /api/v1/repositories/{repository}/audit
액세스: 리포지토리 권한: audit.read; 파일 키: write · 재시도: 반복해도 안전함(읽기)
순번 after(기본 0) 이후의 리포지토리 카탈로그 변경을 오래된 순으로 최대 100개 반환합니다. 변경에는 게시, 삭제, 어노테이션과 첨부 파일 변경, 패키지 등록, 파일 경로 변경, 참조, 스테이지와 승격이 있으며 각각 행위자, 작업, 아티팩트, 시각을 담습니다. 이어서 읽으려면 페이지의 마지막 sequence를 after로 전달하며 next 필드는 없습니다. 다운로드와 로그인은 포함되지 않으며, 미러는 행위자를 생략하는 listCatalogChanges를 따라갑니다.
매개 변수
| 이름 | 위치 | 형식 | 필수 | 규칙 |
|---|---|---|---|---|
repository | 경로 | string | 예 | ^[a-z0-9][a-z0-9_-]{0,63}$ 패턴과 일치 |
after | 쿼리 | string | 아니요 | — |
응답 200
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
items | object 배열 | 아니요 | — |
items[].sequence | string | 아니요 | — |
items[].actor | string | 아니요 | — |
items[].action | string | 아니요 | — |
items[].artifactId | string | 아니요 | — |
items[].occurredAt | string (date-time) | 아니요 | — |
응답: 200, 400, 401, 403, 404, 409, 422, 503, 507
예제
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/audit" \
-H "Authorization: Bearer $ARKVORY_TOKEN"아티팩트에 참조 추가
POST /api/v1/repositories/{repository}/artifacts/{id}/references
액세스: 리포지토리 권한: reference.write, artifact.read; 파일 키: read, write · 재시도: 반복해도 안전함: 같은 요청은 같은 결과를 냄
Arkvory 밖의 무언가가 이 아티팩트를 사용한다는 사실을 임의로 정한 key(문자, 숫자, _.:/- 1–256자, 예: 배포 이름)로 기록합니다. 참조가 있는 아티팩트는 모든 참조가 사라질 때까지 삭제할 수 없고 보존 규칙으로도 제거할 수 없습니다. 참조는 호출자에게 속하며, 같은 키를 다시 추가해도 아무것도 바뀌지 않습니다.
매개 변수
| 이름 | 위치 | 형식 | 필수 | 규칙 |
|---|---|---|---|---|
repository | 경로 | string | 예 | ^[a-z0-9][a-z0-9_-]{0,63}$ 패턴과 일치 |
id | 경로 | string (uuid) | 예 | — |
요청 본문 (application/json)
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
key | string | 예 | 256자 이하 |
응답: 204, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
예제
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/references" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"key":"<key>"}'아티팩트에서 참조 제거
DELETE /api/v1/repositories/{repository}/artifacts/{id}/references
액세스: 리포지토리 권한: reference.write, artifact.read; 파일 키: read, write · 재시도: 반복해도 안전함: 같은 요청은 같은 결과를 냄
호출자 자신의 참조 key를 아티팩트에서 제거하며 다른 호출자의 참조는 그대로 남습니다. 없는 키를 제거하는 요청도 성공합니다.
매개 변수
| 이름 | 위치 | 형식 | 필수 | 규칙 |
|---|---|---|---|---|
repository | 경로 | string | 예 | ^[a-z0-9][a-z0-9_-]{0,63}$ 패턴과 일치 |
id | 경로 | string (uuid) | 예 | — |
요청 본문 (application/json)
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
key | string | 예 | 256자 이하 |
응답: 204, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
예제
curl -X DELETE "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/references" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"key":"<key>"}'아티팩트 목록
GET HEAD /api/v1/repositories/{repository}/artifacts
액세스: 리포지토리 권한: artifact.list; 파일 키: read · 재시도: 반복해도 안전함(읽기)
리포지토리의 게시된 아티팩트를 ID 순으로 페이지당 limit개(1–100, 기본 50) 나열하며, after에 next 값을 넣어 이어서 조회합니다. 페이지가 가득 찰 때마다 next가 설정되므로 마지막 페이지는 비어 있을 수 있습니다. 각 항목에는 업로드 때 지정한 디스크립터가 있으며, 현재 레이블과 메타데이터는 getAnnotations에 있습니다.
매개 변수
| 이름 | 위치 | 형식 | 필수 | 규칙 |
|---|---|---|---|---|
repository | 경로 | string | 예 | ^[a-z0-9][a-z0-9_-]{0,63}$ 패턴과 일치 |
after | 쿼리 | string (uuid) | 아니요 | — |
limit | 쿼리 | integer | 아니요 | 1–100; 기본값 50 |
응답 200
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
items | object 배열 | 아니요 | — |
items[].id | string (uuid) | 예 | — |
items[].repository | string | 예 | — |
items[].status | string | 예 | pending, available, cancelled 중 하나 |
items[].createdAt | string (date-time) | 예 | — |
items[].expiresAt | string (date-time) | 예 | — |
items[].descriptor | object | 예 | — |
items[].descriptor.name | string | 예 | 1–240자 |
items[].descriptor.size | string | 예 | 10진수 숫자로 쓴 정수이며 문자열로 전송 |
items[].descriptor.sha256 | string | 예 | SHA-256: 소문자 16진수 64자리 |
items[].descriptor.labels | string 배열 | 아니요 | 요소 32개 이하; 각 요소: 64자 이하 |
items[].descriptor.metadata | string 맵 | 아니요 | 항목 32개 이하 |
next | string | 아니요 | null일 수 있음 |
응답: 200, 400, 401, 403, 404, 409, 422, 503, 507
예제
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts" \
-H "Authorization: Bearer $ARKVORY_TOKEN"아티팩트 조회
GET HEAD /api/v1/repositories/{repository}/artifacts/{id}
액세스: 리포지토리 권한: artifact.read; 파일 키: read · 재시도: 반복해도 안전함(읽기)
게시된 아티팩트의 ID, 리포지토리, 상태, 생성 시각, 업로드 때 지정한 디스크립터(이름, 크기, SHA-256, 원래의 레이블과 메타데이터)를 반환합니다. 보류 중, 취소됨, 삭제된 아티팩트는 404로 응답합니다. 바이트를 읽으려면 downloadArtifact를 사용합니다.
매개 변수
| 이름 | 위치 | 형식 | 필수 | 규칙 |
|---|---|---|---|---|
repository | 경로 | string | 예 | ^[a-z0-9][a-z0-9_-]{0,63}$ 패턴과 일치 |
id | 경로 | string (uuid) | 예 | — |
응답 200
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
id | string (uuid) | 예 | — |
repository | string | 예 | — |
status | string | 예 | pending, available, cancelled 중 하나 |
createdAt | string (date-time) | 예 | — |
expiresAt | string (date-time) | 예 | — |
descriptor | object | 예 | — |
descriptor.name | string | 예 | 1–240자 |
descriptor.size | string | 예 | 10진수 숫자로 쓴 정수이며 문자열로 전송 |
descriptor.sha256 | string | 예 | SHA-256: 소문자 16진수 64자리 |
descriptor.labels | string 배열 | 아니요 | 요소 32개 이하; 각 요소: 64자 이하 |
descriptor.metadata | string 맵 | 아니요 | 항목 32개 이하 |
응답: 200, 400, 401, 403, 404, 409, 422, 503, 507
예제
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"아티팩트 삭제
DELETE /api/v1/repositories/{repository}/artifacts/{id}
액세스: 리포지토리 권한: artifact.delete · 재시도: 반복해도 안전함: 같은 요청은 같은 결과를 냄
게시된 아티팩트를 논리적으로 삭제합니다. 목록, 검색, 다운로드에서 즉시 사라지며, 바이트는 유예 기간이 지난 뒤 리포지토리의 온라인 물리적 정리(setCleanup, 기본값은 꺼짐)가 회수합니다. expectedAnnotationRevision은 현재 어노테이션 리비전과 같아야 합니다. 응답은 200이며 outcome은 deleted, already_deleted, changed(리비전이 다름), not_found, 또는 삭제를 막는 blockers(참조, 파일 경로 리비전, 빌드 첨부 파일, 승격 스테이지)를 포함한 protected 중 하나입니다. 사전에 inspectArtifactDeletion으로 확인할 수 있습니다.
매개 변수
| 이름 | 위치 | 형식 | 필수 | 규칙 |
|---|---|---|---|---|
repository | 경로 | string | 예 | ^[a-z0-9][a-z0-9_-]{0,63}$ 패턴과 일치 |
id | 경로 | string (uuid) | 예 | — |
요청 본문 (application/json)
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
expectedAnnotationRevision | integer | 예 | 0–2147483647 |
응답 200
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
id | string (uuid) | 예 | — |
outcome | string | 예 | deleted, already_deleted, protected, changed, not_eligible, not_found 중 하나 |
blockers | string 배열 | 예 | 요소 4개 이하; 중복 항목 없음; 각 요소: reference, asset_history, attachment_history, protected_label, promotion_stage 중 하나 |
응답: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
예제
curl -X DELETE "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"expectedAnnotationRevision":0}'아티팩트 다운로드
GET HEAD /api/v1/repositories/{repository}/artifacts/{id}/content
액세스: 리포지토리 권한: content.read; 파일 키: read · 재시도: 반복해도 안전함(읽기)
원본 바이트를 Content-Length, Content-Disposition(아티팩트 이름), 강한 ETag("sha256:<hex>")와 함께 스트리밍합니다. Range를 하나 지정하면 206이고(만족할 수 없는 범위는 416), ETag와 함께 If-Range를 보내면 안전하게 재개되며, If-None-Match에는 304로 응답합니다. HEAD는 본문 없이 같은 헤더를 반환하며 Range는 무시합니다. Authorization 헤더 대신 createDownloadLink로 만든 다운로드 링크를 token으로 전달할 수도 있습니다. 다운로드는 서버의 다운로드 수용 제어에서 빈 슬롯이 생길 때까지 대기합니다.
매개 변수
| 이름 | 위치 | 형식 | 필수 | 규칙 |
|---|---|---|---|---|
repository | 경로 | string | 예 | ^[a-z0-9][a-z0-9_-]{0,63}$ 패턴과 일치 |
id | 경로 | string (uuid) | 예 | — |
Range | 헤더 | string | 아니요 | — |
If-Range | 헤더 | string | 아니요 | — |
If-None-Match | 헤더 | string | 아니요 | — |
Arkvory-Download-Id | 헤더 | string | 아니요 | ^[A-Za-z0-9_-]{16,64}$ 패턴과 일치; The client own id of one download, the same on every range of it: the queue keys the session by it instead of the client address, answers a waiting request at once with 503 download_queued, and may ask it to yield its place at a range boundary. Without it, a waiting request is held until its turn for a bounded time. |
Arkvory-Queue-Ticket | 헤더 | string | 아니요 | 80자 이하; The last Arkvory-Queue-Ticket the server sent for this download: after a server restart the download takes its old turn. A ticket that is wrong, expired or of another download is ignored. |
Arkvory-Download-Class | 헤더 | string | 아니요 | interactive, release, bulk, background 중 하나; Queue class of the download. Only a class lower than the caller own one applies (people: interactive, services and links: release); an unknown value is 400. The response names the class applied. |
token | 쿼리 | string | 아니요 | ^dtl_[A-Za-z0-9_-]{43}$ 패턴과 일치; Download link from POST …/artifacts/{id}/links, instead of an Authorization header |
응답: 200, 206, 304, 400, 401, 403, 404, 409, 416, 422, 503, 507
예제
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/content" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-o file사이트 개요 읽기
GET HEAD /api/v1/fleet/overview
액세스: 관리자 · 재시도: 반복해도 안전함(읽기)
관리 사이트와 이 설치의 경고(심각한 것부터: critical, warning, info)와 그 사이의 미러 연결. 마지막 백그라운드 읽기로 만들며 최대 5초에 한 번입니다. 어떤 관리 사이트도 그 주소에서 응답하지 않는 소스는 external:<origin>이고, 이 설치는 self이며 ARKVORY_SITE_URL이 설정된 경우에만 이 설치로 향하는 연결이 나타납니다. 쓰기 프로세스만 응답합니다.
응답 200
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
generatedAt | string (date-time) | 예 | — |
self | object | 예 | — |
self.name | string | 예 | — |
self.version | string | 예 | — |
self.url | string | 예 | null일 수 있음 |
alerts | object 배열 | 예 | — |
alerts[].site | string | 예 | — |
alerts[].name | string | 예 | — |
alerts[].kind | string | 예 | unreachable, certificate, revoked, refused, invalid, stale, not-writable, copies, single-copy, mirror-failing, mirror-lag, updates-failed, version-skew 중 하나 |
alerts[].severity | string | 예 | critical, warning, info 중 하나 |
alerts[].subject | string | 예 | null일 수 있음 |
alerts[].since | string (date-time) | 예 | null일 수 있음 |
links | object 배열 | 예 | — |
links[].from | string | 예 | — |
links[].to | string | 예 | — |
links[].repository | string | 예 | — |
links[].sourceRepository | string | 예 | — |
links[].mode | string | 예 | mirror, import 중 하나 |
links[].lagChanges | string | 예 | 10진수 숫자로 쓴 정수이며 문자열로 전송; null일 수 있음 |
links[].failing | boolean | 예 | — |
links[].stale | boolean | 아니요 | — |
external | string 배열 | 예 | — |
응답: 200, 400, 401, 403, 404, 409, 422, 503, 507
예제
curl -X GET "$ARKVORY_URL/api/v1/fleet/overview" \
-H "Authorization: Bearer $ARKVORY_TOKEN"관리되는 사이트 목록
GET HEAD /api/v1/fleet/sites
액세스: 관리자 · 재시도: 반복해도 안전함(읽기)
이 설치가 관리하는 사이트(ADR 0077)와 각 사이트가 마지막으로 보고한 내용: state(ok 또는 읽지 못한 이유: unreachable, certificate, revoked, invalid, refused), 마지막으로 확인된 시각, 마지막 topology. 사이트는 백그라운드에서 30초마다 읽습니다. 사이트 키는 절대 반환하지 않습니다.
응답 200
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
items | object 배열 | 예 | 요소 256개 이하 |
items[].id | string (uuid) | 예 | — |
items[].name | string | 예 | — |
items[].url | string | 예 | — |
items[].fingerprint | string | 예 | ^[0-9a-f]{64}$ 패턴과 일치; null일 수 있음 |
items[].addedBy | string | 예 | — |
items[].addedAt | string (date-time) | 예 | — |
items[].seenAt | string (date-time) | 예 | null일 수 있음 |
items[].state | string | 예 | pending, ok, unreachable, certificate, revoked, invalid, refused 중 하나 |
items[].error | string | 예 | null일 수 있음 |
items[].topology | object | 예 | null일 수 있음 |
items[].topology.collectedAt | string (date-time) | 예 | — |
items[].topology.site | object | 예 | — |
items[].topology.health | object | 예 | — |
items[].topology.replication | object | 예 | null일 수 있음 |
items[].topology.gateways | object 배열 | 예 | 요소 16개 이하 |
items[].topology.mirrors | object 배열 | 예 | 요소 64개 이하 |
items[].topology.updates | object | 예 | null일 수 있음 |
items[].topology.downloads | object | 예 | — |
응답: 200, 400, 401, 403, 404, 409, 422, 503, 507
예제
curl -X GET "$ARKVORY_URL/api/v1/fleet/sites" \
-H "Authorization: Bearer $ARKVORY_TOKEN"사이트와 페어링
POST /api/v1/fleet/sites
액세스: 관리자 · 재시도: 자동으로 반복하지 않음
사이트와 페어링합니다: 컨트롤러가 다시 연결하고, 인증서는 여전히 관리자가 확인한 fingerprint를 가져야 하며(loopback의 HTTP는 null), 사이트에서 만든 페어링 code를 키로 교환하고, 키는 ARKVORY_FLEET_KEY_FILE로 봉인됩니다. 응답 전에 사이트를 한 번 읽습니다. 키 파일이 없으면 응답은 503입니다.
요청 본문 (application/json)
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
url | string | 예 | — |
fingerprint | string | 예 | ^[0-9a-f]{64}$ 패턴과 일치; null일 수 있음 |
code | string | 예 | 32자 이하 |
응답 201
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
id | string (uuid) | 예 | — |
name | string | 예 | — |
url | string | 예 | — |
fingerprint | string | 예 | ^[0-9a-f]{64}$ 패턴과 일치; null일 수 있음 |
addedBy | string | 예 | — |
addedAt | string (date-time) | 예 | — |
seenAt | string (date-time) | 예 | null일 수 있음 |
state | string | 예 | pending, ok, unreachable, certificate, revoked, invalid, refused 중 하나 |
error | string | 예 | null일 수 있음 |
topology | object | 예 | null일 수 있음 |
topology.collectedAt | string (date-time) | 예 | — |
topology.site | object | 예 | — |
topology.site.name | string | 예 | — |
topology.site.version | string | 예 | — |
topology.site.schema | integer | 예 | 0 이상 |
topology.site.role | string | 예 | api, reader 중 하나 |
topology.health | object | 예 | — |
topology.health.available | boolean | 예 | — |
topology.health.writable | boolean | 예 | — |
topology.health.draining | boolean | 예 | — |
topology.replication | object | 예 | null일 수 있음 |
topology.replication.copies | integer | 예 | 0–16 |
topology.replication.required | integer | 예 | 1–16 |
topology.replication.singleCopyUntil | string (date-time) | 예 | null일 수 있음 |
topology.replication.node | string | 아니요 | 63자 이하 |
topology.replication.profile | string | 아니요 | ha-2, ha-3 중 하나 |
topology.replication.peers | object 배열 | 아니요 | 요소 16개 이하 |
topology.gateways | object 배열 | 예 | 요소 16개 이하 |
topology.gateways[].slot | integer | 예 | 0 이상 |
topology.gateways[].active | boolean | 예 | — |
topology.gateways[].expiresAt | string (date-time) | 예 | — |
topology.mirrors | object 배열 | 예 | 요소 64개 이하 |
topology.mirrors[].repository | string | 예 | — |
topology.mirrors[].mode | string | 예 | mirror, import 중 하나 |
topology.mirrors[].upstream | string | 예 | — |
topology.mirrors[].sourceRepository | string | 예 | — |
topology.mirrors[].phase | string | 예 | — |
topology.mirrors[].errorCode | string | 예 | null일 수 있음 |
topology.mirrors[].checkedAt | string (date-time) | 예 | null일 수 있음 |
topology.mirrors[].syncedAt | string (date-time) | 예 | null일 수 있음 |
topology.mirrors[].lagChanges | string | 예 | 10진수 숫자로 쓴 정수이며 문자열로 전송; null일 수 있음 |
topology.mirrors[].copiedArtifacts | integer | 예 | 0 이상 |
topology.mirrors[].copiedBytes | string | 예 | 10진수 숫자로 쓴 정수이며 문자열로 전송 |
topology.updates | object | 예 | null일 수 있음 |
topology.updates.currentVersion | string | 예 | — |
topology.updates.latest | string | 예 | null일 수 있음 |
topology.updates.phase | string | 예 | — |
topology.updates.error | string | 예 | null일 수 있음 |
topology.updates.automatic | boolean | 예 | — |
topology.updates.heartbeatAt | string (date-time) | 예 | — |
topology.downloads | object | 예 | — |
topology.downloads.strategy | string | 예 | ordered, smallest-first, shared 중 하나 |
topology.downloads.sessions | integer | 예 | 0 이상 |
topology.downloads.active | integer | 예 | 0 이상 |
topology.downloads.waiting | integer | 예 | 0 이상 |
topology.downloads.oldestWaitSeconds | integer | 예 | 0 이상 |
topology.downloads.bytesPerSecond | integer | 예 | 0 이상 |
응답: 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
예제
curl -X POST "$ARKVORY_URL/api/v1/fleet/sites" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"url":"<url>","fingerprint":"<fingerprint>","code":"<code>"}'사이트 인증서 읽기
POST /api/v1/fleet/sites/probe
액세스: 관리자 · 재시도: 반복해도 안전함: 같은 요청은 같은 결과를 냄
주소에 연결해 아무것도 보내지 않고 사이트의 인증서를 읽습니다: 페어링 전에 fingerprint를 사이트 관리자가 보는 값과 비교하세요.
요청 본문 (application/json)
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
url | string | 예 | — |
응답 200
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
url | string | 예 | — |
certificate | object | 예 | null일 수 있음 |
certificate.fingerprint | string | 예 | ^[0-9a-f]{64}$ 패턴과 일치 |
certificate.subject | string | 예 | — |
certificate.issuer | string | 예 | — |
certificate.validTo | string (date-time) | 예 | — |
응답: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
예제
curl -X POST "$ARKVORY_URL/api/v1/fleet/sites/probe" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"url":"<url>"}'사이트 잊기
DELETE /api/v1/fleet/sites/{id}
액세스: 관리자 · 재시도: 반복해도 안전함: 같은 요청은 같은 결과를 냄
여기서 사이트와 봉인된 키를 삭제합니다. 사이트에서도 이 컨트롤러를 철회하세요. 그때까지 키는 그곳에서 유효합니다.
매개 변수
| 이름 | 위치 | 형식 | 필수 | 규칙 |
|---|---|---|---|---|
id | 경로 | string (uuid) | 예 | — |
응답: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507
예제
curl -X DELETE "$ARKVORY_URL/api/v1/fleet/sites/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"사이트 카탈로그 읽기
GET HEAD /api/v1/fleet/sites/{id}/read
액세스: 관리자 · 재시도: 반복해도 안전함(읽기)
카탈로그 읽기 한 번을 관리 사이트에 전달하고 그 응답을 그대로 반환합니다: 저장소, 검색, 아티팩트, 주석, 단계, 패키지, 파일 페이지와 기록, 저장소 사용량, 미러 상태. path는 쿼리를 포함한 사이트 경로입니다. 다른 경로와 파일 바이트는 400으로 거부됩니다.
매개 변수
| 이름 | 위치 | 형식 | 필수 | 규칙 |
|---|---|---|---|---|
id | 경로 | string (uuid) | 예 | — |
path | 쿼리 | string | 예 | ^/api/v1/ 패턴과 일치; 2048자 이하; A read route of the site with its query, from a fixed list: catalog metadata (repositories, search, artifacts, annotations, stages, packages, file pages and history, storage usage, mirror state), download queue settings and update state. Never file bytes. |
응답: 200, 400, 401, 403, 404, 409, 422, 503, 507
예제
curl -X GET "$ARKVORY_URL/api/v1/fleet/sites/$ID/read?path=$PATH" \
-H "Authorization: Bearer $ARKVORY_TOKEN"사이트 설정 변경
POST /api/v1/fleet/sites/{id}/change
액세스: 관리자 · 재시도: 자동으로 반복하지 않음
변경 하나를 관리 사이트에 전달하고 그 응답을 그대로 반환합니다. path는 다음 경로 중 하나입니다: /api/v1/system/downloads/settings(다운로드 대기열 설정, PUT으로 전송) 또는 /api/v1/system/updates/requests(업데이트 요청, POST로 전송). 본문은 그대로 사이트에 전달되며, 사이트가 리비전이나 요청 id를 확인하므로 반복된 변경은 두 번 적용되지 않습니다. 다른 경로는 400으로 거부됩니다.
매개 변수
| 이름 | 위치 | 형식 | 필수 | 규칙 |
|---|---|---|---|---|
id | 경로 | string (uuid) | 예 | — |
path | 쿼리 | string | 예 | ^/api/v1/ 패턴과 일치; 2048자 이하; A change route of the site, from a fixed list: PUT /api/v1/system/downloads/settings, POST /api/v1/system/updates/requests. |
요청 본문 (application/json)
응답: 200, 202, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
예제
curl -X POST "$ARKVORY_URL/api/v1/fleet/sites/$ID/change?path=$PATH" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'지금 사이트 읽기
POST /api/v1/fleet/sites/{id}/refresh
액세스: 관리자 · 재시도: 반복해도 안전함: 같은 요청은 같은 결과를 냄
다음 차례를 기다리지 않고 지금 사이트를 읽어 새 상태로 반환합니다.
매개 변수
| 이름 | 위치 | 형식 | 필수 | 규칙 |
|---|---|---|---|---|
id | 경로 | string (uuid) | 예 | — |
응답 200
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
id | string (uuid) | 예 | — |
name | string | 예 | — |
url | string | 예 | — |
fingerprint | string | 예 | ^[0-9a-f]{64}$ 패턴과 일치; null일 수 있음 |
addedBy | string | 예 | — |
addedAt | string (date-time) | 예 | — |
seenAt | string (date-time) | 예 | null일 수 있음 |
state | string | 예 | pending, ok, unreachable, certificate, revoked, invalid, refused 중 하나 |
error | string | 예 | null일 수 있음 |
topology | object | 예 | null일 수 있음 |
topology.collectedAt | string (date-time) | 예 | — |
topology.site | object | 예 | — |
topology.site.name | string | 예 | — |
topology.site.version | string | 예 | — |
topology.site.schema | integer | 예 | 0 이상 |
topology.site.role | string | 예 | api, reader 중 하나 |
topology.health | object | 예 | — |
topology.health.available | boolean | 예 | — |
topology.health.writable | boolean | 예 | — |
topology.health.draining | boolean | 예 | — |
topology.replication | object | 예 | null일 수 있음 |
topology.replication.copies | integer | 예 | 0–16 |
topology.replication.required | integer | 예 | 1–16 |
topology.replication.singleCopyUntil | string (date-time) | 예 | null일 수 있음 |
topology.replication.node | string | 아니요 | 63자 이하 |
topology.replication.profile | string | 아니요 | ha-2, ha-3 중 하나 |
topology.replication.peers | object 배열 | 아니요 | 요소 16개 이하 |
topology.gateways | object 배열 | 예 | 요소 16개 이하 |
topology.gateways[].slot | integer | 예 | 0 이상 |
topology.gateways[].active | boolean | 예 | — |
topology.gateways[].expiresAt | string (date-time) | 예 | — |
topology.mirrors | object 배열 | 예 | 요소 64개 이하 |
topology.mirrors[].repository | string | 예 | — |
topology.mirrors[].mode | string | 예 | mirror, import 중 하나 |
topology.mirrors[].upstream | string | 예 | — |
topology.mirrors[].sourceRepository | string | 예 | — |
topology.mirrors[].phase | string | 예 | — |
topology.mirrors[].errorCode | string | 예 | null일 수 있음 |
topology.mirrors[].checkedAt | string (date-time) | 예 | null일 수 있음 |
topology.mirrors[].syncedAt | string (date-time) | 예 | null일 수 있음 |
topology.mirrors[].lagChanges | string | 예 | 10진수 숫자로 쓴 정수이며 문자열로 전송; null일 수 있음 |
topology.mirrors[].copiedArtifacts | integer | 예 | 0 이상 |
topology.mirrors[].copiedBytes | string | 예 | 10진수 숫자로 쓴 정수이며 문자열로 전송 |
topology.updates | object | 예 | null일 수 있음 |
topology.updates.currentVersion | string | 예 | — |
topology.updates.latest | string | 예 | null일 수 있음 |
topology.updates.phase | string | 예 | — |
topology.updates.error | string | 예 | null일 수 있음 |
topology.updates.automatic | boolean | 예 | — |
topology.updates.heartbeatAt | string (date-time) | 예 | — |
topology.downloads | object | 예 | — |
topology.downloads.strategy | string | 예 | ordered, smallest-first, shared 중 하나 |
topology.downloads.sessions | integer | 예 | 0 이상 |
topology.downloads.active | integer | 예 | 0 이상 |
topology.downloads.waiting | integer | 예 | 0 이상 |
topology.downloads.oldestWaitSeconds | integer | 예 | 0 이상 |
topology.downloads.bytesPerSecond | integer | 예 | 0 이상 |
응답: 200, 400, 401, 403, 404, 405, 409, 422, 503, 507
예제
curl -X POST "$ARKVORY_URL/api/v1/fleet/sites/$ID/refresh" \
-H "Authorization: Bearer $ARKVORY_TOKEN"페어링 코드 만들기
POST /api/v1/system/fleet/pairings
액세스: 관리자 · 재시도: 자동으로 반복하지 않음
컨트롤러 관리자가 이 사이트를 관리하려고 입력하는, 10분간 유효한 일회용 코드를 만듭니다. 코드는 한 번만 표시되며 해시로만 저장됩니다. 사이트의 전역 관리자만 만들 수 있습니다.
응답 201
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
code | string | 예 | ^[0-9A-Z]{4}-[0-9A-Z]{4}-[0-9A-Z]{4}$ 패턴과 일치 |
expiresAt | string (date-time) | 예 | — |
fingerprint | string | 예 | ^[0-9a-f]{64}$ 패턴과 일치; null일 수 있음 |
응답: 201, 400, 401, 403, 404, 405, 409, 422, 503, 507
예제
curl -X POST "$ARKVORY_URL/api/v1/system/fleet/pairings" \
-H "Authorization: Bearer $ARKVORY_TOKEN"이 사이트의 컨트롤러 목록
GET HEAD /api/v1/system/fleet/controllers
액세스: 관리자 · 재시도: 반복해도 안전함(읽기)
이 사이트를 관리할 수 있는 컨트롤러를 나열합니다: 이름, 누가 언제 페어링했는지, 키를 마지막으로 사용한 시각.
응답 200
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
items | object 배열 | 예 | 요소 100개 이하 |
items[].id | string (uuid) | 예 | — |
items[].name | string | 예 | — |
items[].pairedBy | string | 예 | — |
items[].pairedAt | string (date-time) | 예 | — |
items[].usedAt | string (date-time) | 예 | null일 수 있음 |
응답: 200, 400, 401, 403, 404, 409, 422, 503, 507
예제
curl -X GET "$ARKVORY_URL/api/v1/system/fleet/controllers" \
-H "Authorization: Bearer $ARKVORY_TOKEN"컨트롤러 철회
DELETE /api/v1/system/fleet/controllers/{id}
액세스: 관리자 · 재시도: 반복해도 안전함: 같은 요청은 같은 결과를 냄
컨트롤러를 철회합니다: 플릿 키가 즉시 거부됩니다. 사이트를 다시 관리하려면 새 코드로 페어링해야 합니다.
매개 변수
| 이름 | 위치 | 형식 | 필수 | 규칙 |
|---|---|---|---|---|
id | 경로 | string (uuid) | 예 | — |
응답: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507
예제
curl -X DELETE "$ARKVORY_URL/api/v1/system/fleet/controllers/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"컨트롤러와 페어링
POST /api/v1/system/fleet/enrollment
액세스: 누구나, 키 없이 · 재시도: 자동으로 반복하지 않음
유효한 페어링 코드를 한 번 플릿 키로 교환합니다. 컨트롤러는 관리자가 확인한 지문에 고정된 TLS로 호출합니다. 키는 한 번만 반환되며 컨트롤러에 필요한 경로에만 접근합니다.
요청 본문 (application/json)
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
code | string | 예 | 32자 이하 |
name | string | 예 | 1–63자 |
응답 201
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
key | string | 예 | ^afk_[A-Za-z0-9_-]{43}$ 패턴과 일치 |
site | object | 예 | — |
site.name | string | 예 | — |
site.version | string | 예 | — |
응답: 201, 400, 403, 405, 413, 415, 503
예제
curl -X POST "$ARKVORY_URL/api/v1/system/fleet/enrollment" \
-H "Content-Type: application/json" \
-d '{"code":"<code>","name":"<name>"}'플릿 콘솔용으로 이 사이트 가져오기
GET HEAD /api/v1/system/topology
액세스: 관리자 · 재시도: 반복해도 안전함(읽기)
이 설치를 플릿의 한 사이트로 반환합니다(ADR 0077): 이름, 버전, 스키마와 역할, 사용 가능 여부와 쓰기 가능 여부, HA 사본과 노드, 임대 기준의 읽기 게이트웨이, 각 미러와 가져오기의 단계, 마지막 동기화 및 lagChanges(아직 적용되지 않은 원본 변경), 업데이트 에이전트 상태와 다운로드 대기열. 사이트의 전역 관리자나 페어링된 컨트롤러만 읽을 수 있습니다.
응답 200
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
collectedAt | string (date-time) | 예 | — |
site | object | 예 | — |
site.name | string | 예 | — |
site.version | string | 예 | — |
site.schema | integer | 예 | 0 이상 |
site.role | string | 예 | api, reader 중 하나 |
health | object | 예 | — |
health.available | boolean | 예 | — |
health.writable | boolean | 예 | — |
health.draining | boolean | 예 | — |
replication | object | 예 | null일 수 있음 |
replication.copies | integer | 예 | 0–16 |
replication.required | integer | 예 | 1–16 |
replication.singleCopyUntil | string (date-time) | 예 | null일 수 있음 |
replication.node | string | 아니요 | 63자 이하 |
replication.profile | string | 아니요 | ha-2, ha-3 중 하나 |
replication.peers | object 배열 | 아니요 | 요소 16개 이하 |
replication.peers[].name | string | 예 | 63자 이하 |
replication.peers[].connected | boolean | 예 | — |
replication.peers[].disk | string | 예 | 24자 이하 |
replication.peers[].complete | boolean | 예 | — |
replication.peers[].witness | boolean | 예 | — |
gateways | object 배열 | 예 | 요소 16개 이하 |
gateways[].slot | integer | 예 | 0 이상 |
gateways[].active | boolean | 예 | — |
gateways[].expiresAt | string (date-time) | 예 | — |
mirrors | object 배열 | 예 | 요소 64개 이하 |
mirrors[].repository | string | 예 | — |
mirrors[].mode | string | 예 | mirror, import 중 하나 |
mirrors[].upstream | string | 예 | — |
mirrors[].sourceRepository | string | 예 | — |
mirrors[].phase | string | 예 | — |
mirrors[].errorCode | string | 예 | null일 수 있음 |
mirrors[].checkedAt | string (date-time) | 예 | null일 수 있음 |
mirrors[].syncedAt | string (date-time) | 예 | null일 수 있음 |
mirrors[].lagChanges | string | 예 | 10진수 숫자로 쓴 정수이며 문자열로 전송; null일 수 있음 |
mirrors[].copiedArtifacts | integer | 예 | 0 이상 |
mirrors[].copiedBytes | string | 예 | 10진수 숫자로 쓴 정수이며 문자열로 전송 |
updates | object | 예 | null일 수 있음 |
updates.currentVersion | string | 예 | — |
updates.latest | string | 예 | null일 수 있음 |
updates.phase | string | 예 | — |
updates.error | string | 예 | null일 수 있음 |
updates.automatic | boolean | 예 | — |
updates.heartbeatAt | string (date-time) | 예 | — |
downloads | object | 예 | — |
downloads.strategy | string | 예 | ordered, smallest-first, shared 중 하나 |
downloads.sessions | integer | 예 | 0 이상 |
downloads.active | integer | 예 | 0 이상 |
downloads.waiting | integer | 예 | 0 이상 |
downloads.oldestWaitSeconds | integer | 예 | 0 이상 |
downloads.bytesPerSecond | integer | 예 | 0 이상 |
응답: 200, 400, 401, 403, 404, 409, 422, 503, 507
예제
curl -X GET "$ARKVORY_URL/api/v1/system/topology" \
-H "Authorization: Bearer $ARKVORY_TOKEN"다운로드 대기열 설정 읽기
GET HEAD /api/v1/system/downloads/settings
액세스: 관리자 · 재시도: 반복해도 안전함(읽기)
변경된 값(overrides), 서버 환경이 정한 값(defaults), 대기열이 지금 사용하는 값(effective)과 변경할 때 다시 보낼 리비전을 반환합니다. problem은 저장된 설정이 이 서버에 맞지 않는 이유를 알려 주며, 이때 대기열은 기본값으로 동작합니다.
응답 200
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
revision | integer | 예 | 0–9007199254740991 |
overrides | object | 예 | — |
overrides.strategy | string | 아니요 | ordered, smallest-first, shared 중 하나 |
overrides.sessions | integer | 아니요 | 1–1024 |
overrides.reserve | integer | 아니요 | 0–1023 |
overrides.perPrincipal | integer | 아니요 | 1–1024 |
overrides.weights | object | 아니요 | — |
overrides.weights.interactive | integer | 예 | 1–1000 |
overrides.weights.release | integer | 예 | 1–1000 |
overrides.weights.bulk | integer | 예 | 1–1000 |
overrides.weights.background | integer | 예 | 1–1000 |
overrides.sessionMinBytes | integer | 아니요 | 0–9007199254740991 |
overrides.idleSeconds | integer | 아니요 | 1–3600 |
overrides.agingMinutes | integer | 아니요 | 0–10080 |
overrides.preempt | boolean | 아니요 | — |
overrides.rangesPerSession | integer | 아니요 | 1–64 |
defaults | object | 예 | — |
defaults.strategy | string | 예 | ordered, smallest-first, shared 중 하나 |
defaults.sessions | integer | 예 | 1–1024 |
defaults.reserve | integer | 예 | 0–1023 |
defaults.perPrincipal | integer | 예 | 1–1024 |
defaults.weights | object | 예 | — |
defaults.weights.interactive | integer | 예 | 1–1000 |
defaults.weights.release | integer | 예 | 1–1000 |
defaults.weights.bulk | integer | 예 | 1–1000 |
defaults.weights.background | integer | 예 | 1–1000 |
defaults.sessionMinBytes | integer | 예 | 0–9007199254740991 |
defaults.idleSeconds | integer | 예 | 1–3600 |
defaults.agingMinutes | integer | 예 | 0–10080 |
defaults.preempt | boolean | 예 | — |
defaults.rangesPerSession | integer | 예 | 1–64 |
effective | object | 예 | — |
effective.strategy | string | 예 | ordered, smallest-first, shared 중 하나 |
effective.sessions | integer | 예 | 1–1024 |
effective.reserve | integer | 예 | 0–1023 |
effective.perPrincipal | integer | 예 | 1–1024 |
effective.weights | object | 예 | — |
effective.weights.interactive | integer | 예 | 1–1000 |
effective.weights.release | integer | 예 | 1–1000 |
effective.weights.bulk | integer | 예 | 1–1000 |
effective.weights.background | integer | 예 | 1–1000 |
effective.sessionMinBytes | integer | 예 | 0–9007199254740991 |
effective.idleSeconds | integer | 예 | 1–3600 |
effective.agingMinutes | integer | 예 | 0–10080 |
effective.preempt | boolean | 예 | — |
effective.rangesPerSession | integer | 예 | 1–64 |
admission | string | 예 | sessions, per-request 중 하나 |
updatedAt | string (date-time) | 예 | null일 수 있음 |
updatedBy | string | 예 | null일 수 있음 |
actor | string | 예 | null일 수 있음 |
problem | string | 예 | null일 수 있음 |
응답: 200, 400, 401, 403, 404, 409, 422, 503, 507
예제
curl -X GET "$ARKVORY_URL/api/v1/system/downloads/settings" \
-H "Authorization: Bearer $ARKVORY_TOKEN"다운로드 대기열 설정 변경
PUT /api/v1/system/downloads/settings
액세스: 관리자 · 재시도: 예상 리비전으로만 반복(compare-and-swap)
overrides를 서버 환경 위에 저장하고 재시작 없이 적용합니다: 새로운 결정은 즉시 이를 따르고, 진행 중인 다운로드는 자리를 유지합니다. 전달한 값은 이전의 모든 변경을 대체하며, {}는 환경값으로 되돌립니다. 이 서버에서 동작할 수 없는 설정은 필드 이름과 함께 400으로 거부되고, 오래된 expectedRevision은 409를 받습니다. 읽기 게이트웨이는 자신의 환경을 유지합니다.
요청 본문 (application/json)
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
expectedRevision | integer | 예 | 0–9007199254740991 |
overrides | object | 예 | — |
overrides.strategy | string | 아니요 | ordered, smallest-first, shared 중 하나 |
overrides.sessions | integer | 아니요 | 1–1024 |
overrides.reserve | integer | 아니요 | 0–1023 |
overrides.perPrincipal | integer | 아니요 | 1–1024 |
overrides.weights | object | 아니요 | — |
overrides.weights.interactive | integer | 예 | 1–1000 |
overrides.weights.release | integer | 예 | 1–1000 |
overrides.weights.bulk | integer | 예 | 1–1000 |
overrides.weights.background | integer | 예 | 1–1000 |
overrides.sessionMinBytes | integer | 아니요 | 0–9007199254740991 |
overrides.idleSeconds | integer | 아니요 | 1–3600 |
overrides.agingMinutes | integer | 아니요 | 0–10080 |
overrides.preempt | boolean | 아니요 | — |
overrides.rangesPerSession | integer | 아니요 | 1–64 |
응답 200
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
revision | integer | 예 | 0–9007199254740991 |
overrides | object | 예 | — |
overrides.strategy | string | 아니요 | ordered, smallest-first, shared 중 하나 |
overrides.sessions | integer | 아니요 | 1–1024 |
overrides.reserve | integer | 아니요 | 0–1023 |
overrides.perPrincipal | integer | 아니요 | 1–1024 |
overrides.weights | object | 아니요 | — |
overrides.weights.interactive | integer | 예 | 1–1000 |
overrides.weights.release | integer | 예 | 1–1000 |
overrides.weights.bulk | integer | 예 | 1–1000 |
overrides.weights.background | integer | 예 | 1–1000 |
overrides.sessionMinBytes | integer | 아니요 | 0–9007199254740991 |
overrides.idleSeconds | integer | 아니요 | 1–3600 |
overrides.agingMinutes | integer | 아니요 | 0–10080 |
overrides.preempt | boolean | 아니요 | — |
overrides.rangesPerSession | integer | 아니요 | 1–64 |
defaults | object | 예 | — |
defaults.strategy | string | 예 | ordered, smallest-first, shared 중 하나 |
defaults.sessions | integer | 예 | 1–1024 |
defaults.reserve | integer | 예 | 0–1023 |
defaults.perPrincipal | integer | 예 | 1–1024 |
defaults.weights | object | 예 | — |
defaults.weights.interactive | integer | 예 | 1–1000 |
defaults.weights.release | integer | 예 | 1–1000 |
defaults.weights.bulk | integer | 예 | 1–1000 |
defaults.weights.background | integer | 예 | 1–1000 |
defaults.sessionMinBytes | integer | 예 | 0–9007199254740991 |
defaults.idleSeconds | integer | 예 | 1–3600 |
defaults.agingMinutes | integer | 예 | 0–10080 |
defaults.preempt | boolean | 예 | — |
defaults.rangesPerSession | integer | 예 | 1–64 |
effective | object | 예 | — |
effective.strategy | string | 예 | ordered, smallest-first, shared 중 하나 |
effective.sessions | integer | 예 | 1–1024 |
effective.reserve | integer | 예 | 0–1023 |
effective.perPrincipal | integer | 예 | 1–1024 |
effective.weights | object | 예 | — |
effective.weights.interactive | integer | 예 | 1–1000 |
effective.weights.release | integer | 예 | 1–1000 |
effective.weights.bulk | integer | 예 | 1–1000 |
effective.weights.background | integer | 예 | 1–1000 |
effective.sessionMinBytes | integer | 예 | 0–9007199254740991 |
effective.idleSeconds | integer | 예 | 1–3600 |
effective.agingMinutes | integer | 예 | 0–10080 |
effective.preempt | boolean | 예 | — |
effective.rangesPerSession | integer | 예 | 1–64 |
admission | string | 예 | sessions, per-request 중 하나 |
updatedAt | string (date-time) | 예 | null일 수 있음 |
updatedBy | string | 예 | null일 수 있음 |
actor | string | 예 | null일 수 있음 |
problem | string | 예 | null일 수 있음 |
응답: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
예제
curl -X PUT "$ARKVORY_URL/api/v1/system/downloads/settings" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"expectedRevision":0,"overrides":{}}'사이트 변경 읽기
GET HEAD /api/v1/system/changes
액세스: 관리자 · 재시도: 반복해도 안전함(읽기)
사이트 에이전트가 보고하는지(agent), 대기 중인 요청, 최근 20개 요청과 그 상태(pending, applying, done 또는 이유가 있는 failed)를 반환합니다. 소스 키는 여기에 나타나지 않습니다.
응답 200
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
agent | boolean | 예 | — |
updating | boolean | 예 | — |
blocked | string | 예 | expired, interrupted, key_missing, not_a_mirror, already_attached, mirror_failed, switchover_failed, single_copy_failed, unreadable, digest_mismatch, null 중 하나; null일 수 있음 |
pending | object | 예 | null일 수 있음 |
pending.id | string (uuid) | 예 | — |
pending.kind | string | 예 | mirror-attach, mirror-key, mirror-detach, cluster-switchover, single-copy 중 하나 |
pending.actor | string | 예 | 200자 이하 |
pending.requestedAt | string (date-time) | 예 | — |
recent | object 배열 | 예 | 요소 20개 이하 |
recent[].id | string (uuid) | 예 | — |
recent[].digest | string | 예 | ^[0-9a-f]{64}$ 패턴과 일치 |
recent[].kind | string | 예 | mirror-attach, mirror-key, mirror-detach, cluster-switchover, single-copy 중 하나 |
recent[].state | string | 예 | pending, applying, done, failed 중 하나 |
recent[].error | string | 예 | expired, interrupted, key_missing, not_a_mirror, already_attached, mirror_failed, switchover_failed, single_copy_failed, unreadable, digest_mismatch, null 중 하나; null일 수 있음 |
recent[].actor | string | 예 | 200자 이하 |
recent[].requestedAt | string (date-time) | 예 | — |
recent[].finishedAt | string (date-time) | 예 | null일 수 있음 |
응답: 200, 400, 401, 403, 404, 409, 422, 503, 507
예제
curl -X GET "$ARKVORY_URL/api/v1/system/changes" \
-H "Authorization: Bearer $ARKVORY_TOKEN"사이트 변경을 대기열에 넣기
POST /api/v1/system/changes
액세스: 관리자 · 재시도: 반복해도 안전함: 같은 요청은 같은 결과를 냄
사이트 에이전트를 위한 변경 하나를 대기열에 넣으며, 에이전트는 1분 안에 arkvory configure와 cluster-*의 검사와 롤백으로 이를 적용합니다: 미러나 가져오기 연결, 소스 키 교체, 미러 분리, 활성 HA 노드 전환(노드 이름을 두 번 입력) 또는 단일 사본 쓰기 결정. id는 클라이언트가 고르며, 반복해도 변경이 다시 대기열에 들어가지 않습니다. key는 mirror-attach와 mirror-key의 소스 키 전용으로, 별도의 0600 파일로 에이전트에 전달되고 반환되지 않습니다. 202는 적용이 아니라 대기열에 들어갔다는 뜻입니다.
요청 본문 (application/json)
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
id | string (uuid) | 예 | — |
change | object | 예 | — |
change.kind | string | 예 | mirror-attach 중 하나 |
change.repository | string | 예 | ^[a-z0-9][a-z0-9_-]{0,63}$ 패턴과 일치 |
change.upstream | string | 예 | 255자 이하 |
change.sourceRepository | string | 예 | ^[a-z0-9][a-z0-9_-]{0,63}$ 패턴과 일치 |
change.stages | string 배열 | 아니요 | 요소 1–16개; 각 요소: ^[a-z0-9][a-z0-9_.-]{0,31}$ 패턴과 일치; null일 수 있음 |
change.repositories | string 배열 | 예 | 요소 1–64개; 각 요소: ^[a-z0-9][a-z0-9_-]{0,63}$ 패턴과 일치 |
change.node | string | 예 | ^[A-Za-z0-9][A-Za-z0-9_.-]{0,62}$ 패턴과 일치 |
change.confirm | string | 예 | ^[A-Za-z0-9][A-Za-z0-9_.-]{0,62}$ 패턴과 일치 |
change.until | string (date-time) | 예 | null일 수 있음 |
change.reason | string | 예 | 1–200자 |
key | string | 아니요 | 16–4000자 |
응답 202
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
id | string (uuid) | 예 | — |
응답: 202, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
예제
curl -X POST "$ARKVORY_URL/api/v1/system/changes" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"id":"00000000-0000-4000-8000-000000000000","change":{"kind":"mirror-attach","repository":"<repository>","upstream":"<upstream>","sourceRepository":"<sourceRepository>"}}'리포지토리 변경 피드 따라가기
GET HEAD /api/v1/repositories/{repository}/changes
액세스: 리포지토리 권한: artifact.list; 파일 키: read · 재시도: 반복해도 안전함(읽기)
순번 after(기본 0) 이후의 변경을 커밋 순서대로 최대 limit개(1–100, 기본 100) 반환합니다. 각 변경은 작업과 아티팩트를 담고, 파일 경로와 스테이지의 경우 detail에 경로나 스테이지를 담습니다. 행위자는 생략되므로 목록 조회 권한만으로 충분합니다. head는 리포지토리의 최신 순번이고 next는 다음 페이지의 커서이며, 페이지가 head에 도달하면 null입니다. 미러는 마지막으로 적용한 순번을 저장하고 그 지점부터 폴링합니다.
매개 변수
| 이름 | 위치 | 형식 | 필수 | 규칙 |
|---|---|---|---|---|
repository | 경로 | string | 예 | ^[a-z0-9][a-z0-9_-]{0,63}$ 패턴과 일치 |
after | 쿼리 | string | 아니요 | 10진수 숫자로 쓴 정수이며 문자열로 전송; Sequence cursor, default 0 |
limit | 쿼리 | integer | 아니요 | 1–100 |
응답 200
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
items | object 배열 | 예 | — |
items[].sequence | string | 예 | 10진수 숫자로 쓴 정수이며 문자열로 전송 |
items[].action | string | 예 | — |
items[].artifactId | string (uuid) | 예 | — |
items[].detail | string | 예 | null일 수 있음 |
head | string | 예 | 10진수 숫자로 쓴 정수이며 문자열로 전송 |
next | string | 예 | 10진수 숫자로 쓴 정수이며 문자열로 전송; null일 수 있음 |
응답: 200, 400, 401, 403, 404, 409, 422, 503, 507
예제
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/changes" \
-H "Authorization: Bearer $ARKVORY_TOKEN"다운로드 링크 생성
POST /api/v1/repositories/{repository}/artifacts/{id}/links
액세스: 리포지토리 권한: content.read; 파일 키: read · 재시도: 자동으로 반복하지 않음
이 아티팩트 하나에 한해 키 없이 downloadArtifact를 호출할 수 있게 하는 비밀 token, API 오리진 기준의 상대 url, expiresAt을 반환합니다. ttlSeconds로 유효 기간을 정하며(60초에서 1일까지, 기본 1시간), 토큰은 이 응답에서만 볼 수 있고 폐기할 수 없습니다. 토큰은 만료되거나 아티팩트가 삭제되면 사용할 수 없게 되며, 토큰을 통한 다운로드는 만든 사용자의 전송 한도에 포함됩니다. 호출자는 유효한 링크를 1,000개까지 가질 수 있고(507 token_limit), 다운로드 링크로는 다른 링크를 만들 수 없습니다.
매개 변수
| 이름 | 위치 | 형식 | 필수 | 규칙 |
|---|---|---|---|---|
repository | 경로 | string | 예 | ^[a-z0-9][a-z0-9_-]{0,63}$ 패턴과 일치 |
id | 경로 | string (uuid) | 예 | — |
요청 본문 (application/json)
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
ttlSeconds | integer | 아니요 | 60–86400; 기본값 3600 |
응답 201
| 필드 | 형식 | 필수 | 규칙 |
|---|---|---|---|
token | string | 예 | ^dtl_[A-Za-z0-9_-]{43}$ 패턴과 일치 |
url | string | 예 | — |
expiresAt | string (date-time) | 예 | — |
응답: 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
예제
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/links" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'