Saltar al contenido

Políticas de almacenamiento y retención ​

Cuotas, uso, políticas de retención, su vista previa y ejecución, limpieza y eliminación de artefactos.

Operaciones de este grupo con su regla de acceso, su regla de reintento, sus parámetros y sus respuestas. Cada solicitud lleva una clave: Authorization: Bearer <clave> (consulte «Autenticación»).

Operaciones ​

Comprobar si se puede eliminar un artefacto ​

GET HEAD /api/v1/repositories/{repository}/artifacts/{id}/deletion

Acceso: Permiso de repositorio: artifact.delete · Reintento: Se puede repetir (lectura)

Devuelve el nombre, el tamaño, la hora de publicación y la annotationRevision actual del artefacto, y los blockers que impedirían su eliminación: reference (una referencia externa, o el uso por una imagen de contenedor, Git LFS o npm), asset_history (una revisión actual o anterior de una ruta de archivo), attachment_history o promotion_stage. No cambia nada; pase la revisión a deleteArtifact como expectedAnnotationRevision.

Parámetros

NombreUbicaciónTipoObligatorioReglas
repositoryrutastringsícoincide con ^[a-z0-9][a-z0-9_-]{0,63}$
idrutastring (uuid)sí—

Respuesta 200

CampoTipoObligatorioReglas
idstring (uuid)sí—
namestringsí1–240 caracteres
sizestringsíun número entero en dígitos decimales, enviado como cadena
publishedAtstring (date-time)sí—
annotationRevisionintegersí0–2147483647
blockersarray de stringsíhasta 4 elementos; sin elementos repetidos; cada elemento: uno de reference, asset_history, attachment_history, protected_label, promotion_stage

Respuestas: 200, 400, 401, 403, 404, 409, 422, 503, 507

Ejemplo

bash
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/deletion" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Previsualizar los candidatos de retención ​

POST /api/v1/repositories/{repository}/retention/preview

Acceso: Permiso de repositorio: artifact.delete · Reintento: Se puede repetir (lectura)

Enumera los artefactos publicados antes de criteria.publishedBefore (una hora UTC pasada con milisegundos), ordenados por ID, cada uno con su revisión de anotaciones y sus impedimentos, donde protected_label significa que lleva una de las criteria.protectedLabels (una lista explícita de hasta 32). Las páginas contienen limit elementos (1–100, 50 por defecto); continúe pasando next como after. No se reserva nada: elija los elementos que eliminar y páselos con sus revisiones a applyRetention, que los comprueba de nuevo.

Parámetros

NombreUbicaciónTipoObligatorioReglas
repositoryrutastringsícoincide con ^[a-z0-9][a-z0-9_-]{0,63}$

Cuerpo de la solicitud (application/json)

CampoTipoObligatorioReglas
criteriaobjectsí—
criteria.publishedBeforestring (date-time)sícoincide con ^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$
criteria.protectedLabelsarray de stringsíhasta 32 elementos; sin elementos repetidos; cada elemento: 1–64 caracteres
limitintegerno1–100
afterstring (uuid)no—

Respuesta 200

CampoTipoObligatorioReglas
itemsarray de objectsíhasta 100 elementos
items[].idstring (uuid)sí—
items[].namestringsí1–240 caracteres
items[].sizestringsíun número entero en dígitos decimales, enviado como cadena
items[].publishedAtstring (date-time)sí—
items[].annotationRevisionintegersí0–2147483647
items[].blockersarray de stringsíhasta 4 elementos; sin elementos repetidos; cada elemento: uno de reference, asset_history, attachment_history, protected_label, promotion_stage
nextstring (uuid)sípuede ser null

Respuestas: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

Ejemplo

bash
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/retention/preview" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"criteria":{"publishedBefore":"2026-01-01T00:00:00.000Z","protectedLabels":[]}}'

Eliminar los candidatos de retención seleccionados ​

POST /api/v1/repositories/{repository}/retention/apply

Acceso: Permiso de repositorio: artifact.delete · Reintento: Se puede repetir: la misma solicitud tiene el mismo efecto

Vuelve a comprobar de 1 a 100 artefactos elegidos con previewRetention (items con id y expectedAnnotationRevision) según los mismos criteria y elimina lógicamente los aptos en una sola transacción. Cada elemento recibe un outcome: deleted, already_deleted, changed (las anotaciones cambiaron), not_eligible (publicado demasiado tarde), protected con sus impedimentos, o not_found. Los bytes siguen reservados hasta que la limpieza física en línea del repositorio los recupera.

Parámetros

NombreUbicaciónTipoObligatorioReglas
repositoryrutastringsícoincide con ^[a-z0-9][a-z0-9_-]{0,63}$

Cuerpo de la solicitud (application/json)

CampoTipoObligatorioReglas
criteriaobjectsí—
criteria.publishedBeforestring (date-time)sícoincide con ^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$
criteria.protectedLabelsarray de stringsíhasta 32 elementos; sin elementos repetidos; cada elemento: 1–64 caracteres
itemsarray de objectsí1–100 elementos
items[].idstring (uuid)sí—
items[].expectedAnnotationRevisionintegersí0–2147483647

Respuesta 200

CampoTipoObligatorioReglas
itemsarray de objectsí1–100 elementos
items[].idstring (uuid)sí—
items[].outcomestringsíuno de deleted, already_deleted, protected, changed, not_eligible, not_found
items[].blockersarray de stringsíhasta 4 elementos; sin elementos repetidos; cada elemento: uno de reference, asset_history, attachment_history, protected_label, promotion_stage

Respuestas: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

Ejemplo

bash
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/retention/apply" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"criteria":{"publishedBefore":"2026-01-01T00:00:00.000Z","protectedLabels":[]},"items":[{"id":"00000000-0000-4000-8000-000000000000","expectedAnnotationRevision":0}]}'

Obtener la política de almacenamiento ​

GET HEAD /api/v1/repositories/{repository}/storage/policy

Acceso: Permiso de repositorio: storage.read · Reintento: Se puede repetir (lectura)

Devuelve la configuración de limpieza automática y de cuota del repositorio con su revision, la próxima y la última ejecución programadas, cuántas compilaciones eliminó la última ejecución y su error. Por defecto la política está desactivada y no hay cuota de repositorio (la capacidad de todo el servidor sigue aplicándose).

Parámetros

NombreUbicaciónTipoObligatorioReglas
repositoryrutastringsícoincide con ^[a-z0-9][a-z0-9_-]{0,63}$

Respuesta 200

CampoTipoObligatorioReglas
revisionintegersí0–2147483647
policyobjectsí—
policy.enabledbooleansí—
policy.groupingstringsíuno de package-channel, package, repository
policy.keepLastintegersí1–100000
policy.channelsarray de objectsíhasta 32 elementos
policy.channels[].labelstringsí1–64 caracteres
policy.channels[].keepLastintegersí1–100000
policy.protectedLabelsarray de stringsíhasta 32 elementos; sin elementos repetidos; cada elemento: 1–64 caracteres
policy.minAgeHoursintegersí0–87600
policy.intervalMinutesintegersí1–10080
policy.quotaBytesstringsíun número entero en dígitos decimales, enviado como cadena; puede ser null
policy.warningPercentintegersí1–98
policy.criticalPercentintegersí2–99
nextRunAtstring (date-time)sípuede ser null
lastRunAtstring (date-time)sípuede ser null
lastDeletedintegersí0–100
lastErrorstringsíhasta 64 caracteres; puede ser null

Respuestas: 200, 400, 401, 403, 404, 409, 422, 503, 507

Ejemplo

bash
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/storage/policy" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Reemplazar la política de almacenamiento ​

PUT /api/v1/repositories/{repository}/storage/policy

Acceso: Permiso de repositorio: storage.manage · Reintento: Repetir solo con la revisión esperada (compare-and-swap)

Reemplaza la política completa, que conserva las últimas keepLast compilaciones UPack registradas por paquete, por etiqueta de canal (channels) o por repositorio (grouping), nunca elimina compilaciones con alguna de las protectedLabels ni más recientes que minAgeHours, se ejecuta cada intervalMinutes y limita el repositorio con quotaBytes (una cadena decimal, null para ninguna) y sus umbrales de aviso. expectedRevision debe ser la revisión actual; de lo contrario, 409 revision_mismatch. Activarla requiere además artifact.delete y vincula la programación a la clave administrada que llama: cuando esa clave se revoca, caduca o pierde estos permisos, la eliminación programada se detiene hasta que la política se guarde con otra clave. Los archivos ordinarios cuentan para la cuota, pero la política nunca los elimina.

Parámetros

NombreUbicaciónTipoObligatorioReglas
repositoryrutastringsícoincide con ^[a-z0-9][a-z0-9_-]{0,63}$

Cuerpo de la solicitud (application/json)

CampoTipoObligatorioReglas
expectedRevisionintegersí0–2147483647
policyobjectsí—
policy.enabledbooleansí—
policy.groupingstringsíuno de package-channel, package, repository
policy.keepLastintegersí1–100000
policy.channelsarray de objectsíhasta 32 elementos
policy.channels[].labelstringsí1–64 caracteres
policy.channels[].keepLastintegersí1–100000
policy.protectedLabelsarray de stringsíhasta 32 elementos; sin elementos repetidos; cada elemento: 1–64 caracteres
policy.minAgeHoursintegersí0–87600
policy.intervalMinutesintegersí1–10080
policy.quotaBytesstringsíun número entero en dígitos decimales, enviado como cadena; puede ser null
policy.warningPercentintegersí1–98
policy.criticalPercentintegersí2–99

Respuesta 200

CampoTipoObligatorioReglas
revisionintegersí0–2147483647
policyobjectsí—
policy.enabledbooleansí—
policy.groupingstringsíuno de package-channel, package, repository
policy.keepLastintegersí1–100000
policy.channelsarray de objectsíhasta 32 elementos
policy.channels[].labelstringsí1–64 caracteres
policy.channels[].keepLastintegersí1–100000
policy.protectedLabelsarray de stringsíhasta 32 elementos; sin elementos repetidos; cada elemento: 1–64 caracteres
policy.minAgeHoursintegersí0–87600
policy.intervalMinutesintegersí1–10080
policy.quotaBytesstringsíun número entero en dígitos decimales, enviado como cadena; puede ser null
policy.warningPercentintegersí1–98
policy.criticalPercentintegersí2–99
nextRunAtstring (date-time)sípuede ser null
lastRunAtstring (date-time)sípuede ser null
lastDeletedintegersí0–100
lastErrorstringsíhasta 64 caracteres; puede ser null

Respuestas: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

Ejemplo

bash
curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/storage/policy" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expectedRevision":0,"policy":{"enabled":false,"grouping":"package-channel","keepLast":1,"channels":[],"protectedLabels":[],"minAgeHours":0,"intervalMinutes":1,"quotaBytes":"1024","warningPercent":1,"criticalPercent":2}}'

Obtener el uso de almacenamiento de un repositorio ​

GET HEAD /api/v1/repositories/{repository}/storage/usage

Acceso: Permiso de repositorio: storage.read · Reintento: Se puede repetir (lectura)

Devuelve los bytes que reserva el repositorio como cadenas decimales: publicados, subidas pendientes y retirados (eliminados o cancelados, aún no recuperados), su suma reservedBytes, la cuota y un state (unlimited, normal, warning, critical, exceeded). Es la reserva lógica que se cuenta frente a la cuota, no el espacio usado en disco.

Parámetros

NombreUbicaciónTipoObligatorioReglas
repositoryrutastringsícoincide con ^[a-z0-9][a-z0-9_-]{0,63}$

Respuesta 200

CampoTipoObligatorioReglas
publishedBytesstringsíun número entero en dígitos decimales, enviado como cadena
pendingBytesstringsíun número entero en dígitos decimales, enviado como cadena
retiredBytesstringsíun número entero en dígitos decimales, enviado como cadena
reservedBytesstringsíun número entero en dígitos decimales, enviado como cadena
quotaBytesstringsíun número entero en dígitos decimales, enviado como cadena; puede ser null
statestringsíuno de unlimited, normal, warning, critical, exceeded

Respuestas: 200, 400, 401, 403, 404, 409, 422, 503, 507

Ejemplo

bash
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/storage/usage" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Previsualizar lo que eliminaría la política de almacenamiento ​

GET HEAD /api/v1/repositories/{repository}/storage/preview

Acceso: Permiso de repositorio: artifact.delete · Reintento: Se puede repetir (lectura)

Devuelve hasta 100 compilaciones registradas que la política guardada eliminaría ahora (incluso mientras está desactivada), con la revision de la política y hasMore; quedan fuera las compilaciones retenidas por referencias, rutas de archivo, adjuntos, etiquetas protegidas o antigüedad. No se reserva nada: una ejecución vuelve a evaluar las compilaciones.

Parámetros

NombreUbicaciónTipoObligatorioReglas
repositoryrutastringsícoincide con ^[a-z0-9][a-z0-9_-]{0,63}$

Respuesta 200

CampoTipoObligatorioReglas
revisionintegersí0–2147483647
itemsarray de objectsíhasta 100 elementos
items[].idstring (uuid)sí—
items[].namestringsíhasta 240 caracteres
items[].sizestringsíun número entero en dígitos decimales, enviado como cadena
items[].publishedAtstring (date-time)sí—
items[].annotationRevisionintegersí0–2147483647
items[].blockersarray de stringsíhasta 0 elementos
hasMorebooleansí—

Respuestas: 200, 400, 401, 403, 404, 409, 422, 503, 507

Ejemplo

bash
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/storage/preview" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Ejecutar la política de almacenamiento ahora ​

POST /api/v1/repositories/{repository}/storage/run

Acceso: Permiso de repositorio: storage.manage, artifact.delete · Reintento: No repetir automáticamente

Ejecuta de inmediato un lote de la política activada en lugar de esperar a la programación: vuelve a ordenar las compilaciones, comprueba permisos y dependencias, y elimina lógicamente hasta 100, devolviendo un resultado para cada una. expectedRevision debe ser la revisión actual de la política y la política debe estar activada; de lo contrario, 409. Los bytes se recuperan después mediante la limpieza física en línea del repositorio, que tiene su propia política (setCleanup).

Parámetros

NombreUbicaciónTipoObligatorioReglas
repositoryrutastringsícoincide con ^[a-z0-9][a-z0-9_-]{0,63}$

Cuerpo de la solicitud (application/json)

CampoTipoObligatorioReglas
expectedRevisionintegersí0–2147483647

Respuesta 200

CampoTipoObligatorioReglas
itemsarray de objectsíhasta 100 elementos
items[].idstring (uuid)sí—
items[].outcomestringsíuno de deleted, already_deleted, protected, changed, not_eligible, not_found
items[].blockersarray de stringsíhasta 4 elementos; cada elemento: uno de reference, asset_history, attachment_history, protected_label, promotion_stage

Respuestas: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

Ejemplo

bash
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/storage/run" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expectedRevision":0}'

Listar los eventos de almacenamiento de un repositorio ​

GET HEAD /api/v1/repositories/{repository}/storage/events

Acceso: Permiso de repositorio: diagnostics.read · Reintento: Se puede repetir (lectura)

Devuelve hasta 100 eventos de diagnóstico de las políticas de almacenamiento, las cuotas, la retención y la limpieza física posteriores a la secuencia after (0 por defecto), del más antiguo al más reciente, cada uno con nivel, código y algunos detalles; level (info, warning, error) los filtra; continúe pasando next como after. Solo se conservan los 1000 eventos más recientes por repositorio y 20 000 en total, así que expórtelos si necesita una retención más larga.

Parámetros

NombreUbicaciónTipoObligatorioReglas
repositoryrutastringsícoincide con ^[a-z0-9][a-z0-9_-]{0,63}$
afterconsultastringnoun número entero en dígitos decimales, enviado como cadena
levelconsultastringnouno de info, warning, error

Respuesta 200

CampoTipoObligatorioReglas
itemsarray de objectsíhasta 100 elementos
items[].sequencestringsíun número entero en dígitos decimales, enviado como cadena
items[].occurredAtstring (date-time)sí—
items[].levelstringsíuno de info, warning, error
items[].codestringsíhasta 96 caracteres
items[].detailsmapa de string | integersíhasta 16 entradas
nextstringsíun número entero en dígitos decimales, enviado como cadena; puede ser null

Respuestas: 200, 400, 401, 403, 404, 409, 422, 503, 507

Ejemplo

bash
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/storage/events" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Obtener la configuración de la limpieza en línea ​

GET HEAD /api/v1/repositories/{repository}/storage/cleanup

Acceso: Permiso de repositorio: storage.read · Reintento: Se puede repetir (lectura)

Devuelve la política de limpieza física en línea del repositorio con su revision (enabled, graceHours, batchSize, intervalSeconds, delayMilliseconds), la última y la próxima ejecución, y cuántos objetos recuperó, aplazó o no pudo procesar el último lote, con los bytes liberados. La limpieza es lo que elimina físicamente las subidas canceladas y los artefactos eliminados; está desactivada por defecto.

Parámetros

NombreUbicaciónTipoObligatorioReglas
repositoryrutastringsícoincide con ^[a-z0-9][a-z0-9_-]{0,63}$

Respuesta 200

CampoTipoObligatorioReglas
revisionintegersí0–2147483647
policyobjectsí—
policy.enabledbooleansí—
policy.graceHoursintegersí0–8760
policy.batchSizeintegersí1–100
policy.intervalSecondsintegersí5–86400
policy.delayMillisecondsintegersí0–1000
lastRunAtstring (date-time)sípuede ser null
nextRunAtstring (date-time)sípuede ser null
lastCollectedintegersí0–100
lastDeferredintegersí0–100
lastFailedintegersí0–100
lastReclaimedBytesstringsíun número entero en dígitos decimales, enviado como cadena
lastErrorstringsípuede ser null

Respuestas: 200, 400, 401, 403, 404, 409, 422, 503, 507

Ejemplo

bash
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/storage/cleanup" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Configurar la limpieza en línea ​

PUT /api/v1/repositories/{repository}/storage/cleanup

Acceso: Permiso de repositorio: storage.manage · Reintento: Repetir solo con la revisión esperada (compare-and-swap)

Reemplaza la política de limpieza mientras el servidor está en marcha: enabled (también para pausarla), graceHours (0–8760, cuánto tiempo permanece el contenido eliminado antes de borrarse), batchSize (1–100 objetos), intervalSeconds (5–86400) y delayMilliseconds (0–1000 entre objetos). expectedRevision debe ser la revisión actual (0 antes del primer cambio); de lo contrario, 409 revision_mismatch. Un cambio surte efecto entre objetos, nunca a mitad de uno.

Parámetros

NombreUbicaciónTipoObligatorioReglas
repositoryrutastringsícoincide con ^[a-z0-9][a-z0-9_-]{0,63}$

Cuerpo de la solicitud (application/json)

CampoTipoObligatorioReglas
expectedRevisionintegersí0–2147483647
policyobjectsí—
policy.enabledbooleansí—
policy.graceHoursintegersí0–8760
policy.batchSizeintegersí1–100
policy.intervalSecondsintegersí5–86400
policy.delayMillisecondsintegersí0–1000

Respuesta 200

CampoTipoObligatorioReglas
revisionintegersí0–2147483647
policyobjectsí—
policy.enabledbooleansí—
policy.graceHoursintegersí0–8760
policy.batchSizeintegersí1–100
policy.intervalSecondsintegersí5–86400
policy.delayMillisecondsintegersí0–1000
lastRunAtstring (date-time)sípuede ser null
nextRunAtstring (date-time)sípuede ser null
lastCollectedintegersí0–100
lastDeferredintegersí0–100
lastFailedintegersí0–100
lastReclaimedBytesstringsíun número entero en dígitos decimales, enviado como cadena
lastErrorstringsípuede ser null

Respuestas: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

Ejemplo

bash
curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/storage/cleanup" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expectedRevision":0,"policy":{"enabled":false,"graceHours":0,"batchSize":1,"intervalSeconds":5,"delayMilliseconds":0}}'

Solicitar un lote de limpieza ahora ​

POST /api/v1/repositories/{repository}/storage/cleanup/run

Acceso: Permiso de repositorio: storage.manage · Reintento: No repetir automáticamente

Programa el siguiente lote de la política de limpieza activada para que empiece de inmediato; la respuesta es el estado de la limpieza, y los bytes se liberan solo cuando el lote se ha ejecutado (véase lastRunAt en getCleanup). expectedRevision debe ser la revisión actual; una limpieza desactivada produce un 409 state_conflict. Los objetos que se están leyendo o escribiendo se aplazan a un lote posterior.

Parámetros

NombreUbicaciónTipoObligatorioReglas
repositoryrutastringsícoincide con ^[a-z0-9][a-z0-9_-]{0,63}$

Cuerpo de la solicitud (application/json)

CampoTipoObligatorioReglas
expectedRevisionintegersí0–2147483647

Respuesta 200

CampoTipoObligatorioReglas
revisionintegersí0–2147483647
policyobjectsí—
policy.enabledbooleansí—
policy.graceHoursintegersí0–8760
policy.batchSizeintegersí1–100
policy.intervalSecondsintegersí5–86400
policy.delayMillisecondsintegersí0–1000
lastRunAtstring (date-time)sípuede ser null
nextRunAtstring (date-time)sípuede ser null
lastCollectedintegersí0–100
lastDeferredintegersí0–100
lastFailedintegersí0–100
lastReclaimedBytesstringsíun número entero en dígitos decimales, enviado como cadena
lastErrorstringsípuede ser null

Respuestas: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

Ejemplo

bash
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/storage/cleanup/run" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expectedRevision":0}'

Arkvory · ProAnimaStudio