Uploads
Uploads retomáveis: crie uma sessão de upload, envie os bytes de uma vez ou em partes, conclua-a e acompanhe a tarefa de conclusão.
Operações deste grupo com a regra de acesso, a regra de repetição, os parâmetros e as respostas. Toda solicitação leva uma chave: Authorization: Bearer <chave> (consulte “Autenticação”).
Operações
Listar as partes recebidas de um upload
GET HEAD /api/v1/repositories/{repository}/uploads/{id}/parts
Acesso: Permissão no repositório: upload.read; chaves em arquivo: write · Repetição: Pode ser repetida com segurança (leitura)
Retorna partBytes, o tamanho da parte fixado para este upload quando ele foi criado (8 MiB, dobrado para arquivos que exigiriam mais de 10 000 partes; somente a última parte é menor), e as partes já armazenadas com seu índice, tamanho e SHA-256. Leia-o antes de retomar um upload multipart interrompido e envie apenas as partes que faltam com putUploadPart. Somente o criador do upload o vê; para qualquer outra pessoa, é um 404.
Parâmetros
| Nome | Local | Tipo | Obrigatório | Regras |
|---|---|---|---|---|
repository | caminho | string | sim | corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | caminho | string (uuid) | sim | — |
Resposta 200
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
partBytes | integer | não | 8388608–1073741824; Todas as partes têm este tamanho, exceto a última. |
items | array de object | não | — |
items[].index | integer | sim | 0–9999 |
items[].size | integer | sim | 1–1073741824 |
items[].sha256 | string | sim | SHA-256: 64 dígitos hexadecimais minúsculos |
Respostas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemplo
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID/parts" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Enviar uma parte
PUT /api/v1/repositories/{repository}/uploads/{id}/parts/{index}
Acesso: Permissão no repositório: upload.write; chaves em arquivo: write · Repetição: Ler o upload novamente e então decidir
Armazena o corpo como a parte index (a partir de 0) de um upload multipart pendente; seu comprimento deve ser exatamente partBytes (de listUploadParts), ou o restante, no caso da última parte, e X-Content-SHA256 deve ser o SHA-256 em hexadecimal minúsculo desses bytes; caso contrário, 422. As partes podem chegar em qualquer ordem, mas um upload atende uma solicitação por vez (uma solicitação concorrente recebe 503 busy); enviar uma parte novamente com o mesmo hash é seguro, e um hash diferente para um índice já armazenado gera 409 part_mismatch. Quando todas as partes estiverem armazenadas, chame completeUpload ou enqueueCompletion.
Parâmetros
| Nome | Local | Tipo | Obrigatório | Regras |
|---|---|---|---|---|
repository | caminho | string | sim | corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | caminho | string (uuid) | sim | — |
index | caminho | integer | sim | 0–9999 |
X-Content-SHA256 | cabeçalho | string | sim | SHA-256: 64 dígitos hexadecimais minúsculos |
Corpo da solicitação (application/octet-stream)
Respostas: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507
Exemplo
curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID/parts/$INDEX" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "X-Content-SHA256: $X_CONTENT_SHA256" \
-H "Content-Type: application/octet-stream" \
--data-binary @fileConcluir um upload em segundo plano
POST /api/v1/repositories/{repository}/uploads/{id}/complete-async
Acesso: Permissão no repositório: upload.complete; chaves em arquivo: write · Repetição: Ler a tarefa novamente e então decidir
Enfileira a conclusão de um upload pendente para o serviço worker em vez de executá-la na própria solicitação e retorna o job imediatamente com 202; acompanhe-o com getCompletionJob. Chamá-lo novamente para o mesmo upload retorna o mesmo job, e um job que falhou por um motivo transitório é enfileirado de novo. Um job enfileirado não significa que o artefato foi publicado: somente completed significa. 409 upload_state se o upload não estiver mais pendente; 507 queue_full quando o chamador tem 100 jobs abertos ou o servidor tem 10 000.
Parâmetros
| Nome | Local | Tipo | Obrigatório | Regras |
|---|---|---|---|---|
repository | caminho | string | sim | corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | caminho | string (uuid) | sim | — |
Resposta 202
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
id | string (uuid) | sim | — |
uploadId | string (uuid) | sim | — |
repository | string | sim | — |
owner | string | sim | — |
status | string | sim | um destes: queued, running, completed, failed |
generation | integer | sim | 0–2147483647 |
attempts | integer | sim | pelo menos 0 |
credentialId | string (uuid) | não | ID opcional da chave gerenciada que iniciou a operação; nunca o seu segredo. |
errorCode | string | sim | pode ser null |
Respostas: 202, 400, 401, 403, 404, 405, 409, 422, 503, 507
Exemplo
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID/complete-async" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Obter um job de conclusão
GET HEAD /api/v1/jobs/{id}
Acesso: Permissão no repositório: job.read; chaves em arquivo: write · Repetição: Pode ser repetida com segurança (leitura)
Retorna o estado de um job de conclusão enfileirado com enqueueCompletion: queued, running, completed (o upload está publicado) ou failed com um errorCode, além do número de tentativas. O worker tenta até cinco vezes, com pausas crescentes; erros como integrity_mismatch falham imediatamente. Somente o criador do job o vê; para qualquer outra pessoa, é um 404.
Parâmetros
| Nome | Local | Tipo | Obrigatório | Regras |
|---|---|---|---|---|
id | caminho | string (uuid) | sim | — |
Resposta 200
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
id | string (uuid) | sim | — |
uploadId | string (uuid) | sim | — |
repository | string | sim | — |
owner | string | sim | — |
status | string | sim | um destes: queued, running, completed, failed |
generation | integer | sim | 0–2147483647 |
attempts | integer | sim | pelo menos 0 |
credentialId | string (uuid) | não | ID opcional da chave gerenciada que iniciou a operação; nunca o seu segredo. |
errorCode | string | sim | pode ser null |
Respostas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemplo
curl -X GET "$ARKVORY_URL/api/v1/jobs/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Criar uma sessão de upload
POST /api/v1/repositories/{repository}/uploads
Acesso: Permissão no repositório: upload.create; chaves em arquivo: write · Repetição: Pode ser repetida com segurança com a mesma Idempotency-Key
Reserva um upload para um arquivo descrito por name, size (uma string decimal), sha256 e, opcionalmente, labels e metadata; retorna 201 com a sessão (pending, válida por 7 dias) e seu Location. Idempotency-Key (1–128 letras, dígitos e _.:-) é obrigatória: a mesma chave com a mesma descrição retorna a mesma sessão; com uma descrição diferente, é um 409 idempotency_mismatch. O tamanho é reservado de imediato na cota do repositório e na capacidade do servidor (507). Em seguida, envie os bytes inteiros com putUploadContent ou em partes com putUploadPart e finalize com completeUpload.
Parâmetros
| Nome | Local | Tipo | Obrigatório | Regras |
|---|---|---|---|---|
repository | caminho | string | sim | corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$ |
Idempotency-Key | cabeçalho | string | sim | até 128 caracteres |
Corpo da solicitação (application/json)
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
name | string | sim | 1–240 caracteres |
size | string | sim | um número inteiro em dígitos decimais, enviado como string |
sha256 | string | sim | SHA-256: 64 dígitos hexadecimais minúsculos |
labels | array de string | não | até 32 itens; cada item: até 64 caracteres |
metadata | mapa de string | não | até 32 entradas |
Resposta 201
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
id | string (uuid) | sim | — |
repository | string | sim | — |
status | string | sim | um destes: pending, available, cancelled |
createdAt | string (date-time) | sim | — |
expiresAt | string (date-time) | sim | — |
descriptor | object | sim | — |
descriptor.name | string | sim | 1–240 caracteres |
descriptor.size | string | sim | um número inteiro em dígitos decimais, enviado como string |
descriptor.sha256 | string | sim | SHA-256: 64 dígitos hexadecimais minúsculos |
descriptor.labels | array de string | não | até 32 itens; cada item: até 64 caracteres |
descriptor.metadata | mapa de string | não | até 32 entradas |
Respostas: 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Exemplo
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"name":"<name>","size":"1024","sha256":"<sha256: SHA-256>"}'Obter um upload
GET HEAD /api/v1/repositories/{repository}/uploads/{id}
Acesso: Permissão no repositório: upload.read; chaves em arquivo: write · Repetição: Pode ser repetida com segurança (leitura)
Retorna a sessão com seu status (pending, available depois de publicado, cancelled), sua expiração e o descritor declarado. Se a resposta de putUploadContent ou de completeUpload for perdida, leia isto primeiro: available significa que o artefato foi publicado com o mesmo ID. Somente o criador do upload o vê; para qualquer outra pessoa, é um 404.
Parâmetros
| Nome | Local | Tipo | Obrigatório | Regras |
|---|---|---|---|---|
repository | caminho | string | sim | corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | caminho | string (uuid) | sim | — |
Resposta 200
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
id | string (uuid) | sim | — |
repository | string | sim | — |
status | string | sim | um destes: pending, available, cancelled |
createdAt | string (date-time) | sim | — |
expiresAt | string (date-time) | sim | — |
descriptor | object | sim | — |
descriptor.name | string | sim | 1–240 caracteres |
descriptor.size | string | sim | um número inteiro em dígitos decimais, enviado como string |
descriptor.sha256 | string | sim | SHA-256: 64 dígitos hexadecimais minúsculos |
descriptor.labels | array de string | não | até 32 itens; cada item: até 64 caracteres |
descriptor.metadata | mapa de string | não | até 32 entradas |
Respostas: 200, 400, 401, 403, 404, 409, 422, 503, 507
Exemplo
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Cancelar um upload
DELETE /api/v1/repositories/{repository}/uploads/{id}
Acesso: Permissão no repositório: upload.cancel; chaves em arquivo: write · Repetição: Ler o upload novamente e então decidir
Cancela um upload pendente e o retorna com o status cancelled; um upload publicado não pode ser cancelado (409 upload_state). Os bytes recebidos ficam ocultos imediatamente, mas continuam reservados na cota até que a limpeza online do repositório (setCleanup, desativada por padrão) os remova depois do período de carência.
Parâmetros
| Nome | Local | Tipo | Obrigatório | Regras |
|---|---|---|---|---|
repository | caminho | string | sim | corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | caminho | string (uuid) | sim | — |
Resposta 200
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
id | string (uuid) | sim | — |
repository | string | sim | — |
status | string | sim | um destes: pending, available, cancelled |
createdAt | string (date-time) | sim | — |
expiresAt | string (date-time) | sim | — |
descriptor | object | sim | — |
descriptor.name | string | sim | 1–240 caracteres |
descriptor.size | string | sim | um número inteiro em dígitos decimais, enviado como string |
descriptor.sha256 | string | sim | SHA-256: 64 dígitos hexadecimais minúsculos |
descriptor.labels | array de string | não | até 32 itens; cada item: até 64 caracteres |
descriptor.metadata | mapa de string | não | até 32 entradas |
Respostas: 200, 400, 401, 403, 404, 405, 409, 422, 503, 507
Exemplo
curl -X DELETE "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Enviar o arquivo inteiro em uma solicitação
PUT /api/v1/repositories/{repository}/uploads/{id}/content
Acesso: Permissão no repositório: upload.write, upload.complete; chaves em arquivo: write · Repetição: Ler o upload novamente e então decidir
Transmite o corpo da solicitação como o conteúdo completo de um upload pendente, confere-o com o tamanho e o SHA-256 declarados (422 em caso de divergência) e publica o artefato; a resposta é o upload com o status available. Uma solicitação interrompida não deixa nada para retomar: leia o upload com getUpload e envie o arquivo novamente a partir do byte zero. Não serve para um upload que já tem partes (409 upload_state); além disso, uma solicitação deve terminar dentro do prazo de upload do servidor (30 minutos por padrão), portanto envie arquivos grandes em partes.
Parâmetros
| Nome | Local | Tipo | Obrigatório | Regras |
|---|---|---|---|---|
repository | caminho | string | sim | corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | caminho | string (uuid) | sim | — |
Corpo da solicitação (application/octet-stream)
Resposta 200
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
id | string (uuid) | sim | — |
repository | string | sim | — |
status | string | sim | um destes: pending, available, cancelled |
createdAt | string (date-time) | sim | — |
expiresAt | string (date-time) | sim | — |
descriptor | object | sim | — |
descriptor.name | string | sim | 1–240 caracteres |
descriptor.size | string | sim | um número inteiro em dígitos decimais, enviado como string |
descriptor.sha256 | string | sim | SHA-256: 64 dígitos hexadecimais minúsculos |
descriptor.labels | array de string | não | até 32 itens; cada item: até 64 caracteres |
descriptor.metadata | mapa de string | não | até 32 entradas |
Respostas: 200, 400, 401, 403, 404, 405, 409, 422, 503, 507
Exemplo
curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID/content" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/octet-stream" \
--data-binary @fileConcluir um upload
POST /api/v1/repositories/{repository}/uploads/{id}/complete
Acesso: Permissão no repositório: upload.complete; chaves em arquivo: write · Repetição: Ler o upload novamente e então decidir
Monta as partes armazenadas em ordem, confere o arquivo inteiro com o tamanho e o SHA-256 declarados e publica o artefato; retorna o upload com o status available. Chamá-lo novamente para um upload publicado retorna o mesmo resultado, portanto ele também recupera uma conclusão cuja resposta foi perdida. Uma parte ausente gera 409 parts_incomplete, e uma divergência de conteúdo gera 422; para arquivos muito grandes, em que a solicitação pode expirar, use enqueueCompletion.
Parâmetros
| Nome | Local | Tipo | Obrigatório | Regras |
|---|---|---|---|---|
repository | caminho | string | sim | corresponde a ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | caminho | string (uuid) | sim | — |
Resposta 200
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
id | string (uuid) | sim | — |
repository | string | sim | — |
status | string | sim | um destes: pending, available, cancelled |
createdAt | string (date-time) | sim | — |
expiresAt | string (date-time) | sim | — |
descriptor | object | sim | — |
descriptor.name | string | sim | 1–240 caracteres |
descriptor.size | string | sim | um número inteiro em dígitos decimais, enviado como string |
descriptor.sha256 | string | sim | SHA-256: 64 dígitos hexadecimais minúsculos |
descriptor.labels | array de string | não | até 32 itens; cada item: até 64 caracteres |
descriptor.metadata | mapa de string | não | até 32 entradas |
Respostas: 200, 400, 401, 403, 404, 405, 409, 422, 503, 507
Exemplo
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID/complete" \
-H "Authorization: Bearer $ARKVORY_TOKEN"