Uploads
Fortsetzbare Uploads: eine Upload-Sitzung erstellen, die Bytes vollständig oder in Teilen senden, den Upload abschließen und den Abschluss-Job verfolgen.
Die Vorgänge dieser Gruppe mit ihrer Zugriffsregel, Wiederholungsregel, ihren Parametern und Antworten. Jede Anfrage trägt einen Schlüssel: Authorization: Bearer <Schlüssel> (siehe „Authentifizierung“).
Vorgänge
Empfangene Teile eines Uploads auflisten
GET HEAD /api/v1/repositories/{repository}/uploads/{id}/parts
Zugriff: Repository-Berechtigung: upload.read; Dateischlüssel: write · Wiederholung: Wiederholen ist sicher (Lesen)
Liefert partBytes, die beim Anlegen des Uploads festgelegte Teilgröße (8 MiB, verdoppelt bei Dateien, die mehr als 10.000 Teile benötigen würden; nur das letzte Teil ist kürzer), sowie die bereits gespeicherten Teile mit Index, Größe und SHA-256. Lesen Sie die Liste, bevor Sie einen unterbrochenen Multipart-Upload fortsetzen, und senden Sie nur die fehlenden Teile mit putUploadPart. Nur der Ersteller des Uploads sieht sie; für alle anderen ist es ein 404.
Parameter
| Name | Ort | Typ | Erforderlich | Regeln |
|---|---|---|---|---|
repository | Pfad | string | ja | entspricht ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | Pfad | string (uuid) | ja | — |
Antwort 200
| Feld | Typ | Erforderlich | Regeln |
|---|---|---|---|
partBytes | integer | nein | 8388608–1073741824; Alle Teile haben diese Größe, außer dem letzten. |
items | Array von object | nein | — |
items[].index | integer | ja | 0–9999 |
items[].size | integer | ja | 1–1073741824 |
items[].sha256 | string | ja | SHA-256: 64 hexadezimale Ziffern in Kleinbuchstaben |
Antworten: 200, 400, 401, 403, 404, 409, 422, 503, 507
Beispiel
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID/parts" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Ein Teil hochladen
PUT /api/v1/repositories/{repository}/uploads/{id}/parts/{index}
Zugriff: Repository-Berechtigung: upload.write; Dateischlüssel: write · Wiederholung: Upload erneut lesen, dann entscheiden
Speichert den Body als Teil index (ab 0) eines ausstehenden Multipart-Uploads; seine Länge muss genau partBytes (aus listUploadParts) betragen, beim letzten Teil dem Rest, und X-Content-SHA256 muss der SHA-256 dieser Bytes als Hexadezimalzahl in Kleinbuchstaben sein, sonst 422. Teile dürfen in beliebiger Reihenfolge eintreffen, doch ein Upload nimmt jeweils nur eine Anfrage entgegen (eine gleichzeitige erhält 503 busy); ein Teil mit demselben Hash erneut zu senden ist sicher, ein anderer Hash für einen bereits gespeicherten Index ergibt 409 part_mismatch. Sind alle Teile gespeichert, rufen Sie completeUpload oder enqueueCompletion auf.
Parameter
| Name | Ort | Typ | Erforderlich | Regeln |
|---|---|---|---|---|
repository | Pfad | string | ja | entspricht ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | Pfad | string (uuid) | ja | — |
index | Pfad | integer | ja | 0–9999 |
X-Content-SHA256 | Header | string | ja | SHA-256: 64 hexadezimale Ziffern in Kleinbuchstaben |
Anfragetext (application/octet-stream)
Antworten: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507
Beispiel
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 @fileUpload im Hintergrund abschließen
POST /api/v1/repositories/{repository}/uploads/{id}/complete-async
Zugriff: Repository-Berechtigung: upload.complete; Dateischlüssel: write · Wiederholung: Job erneut lesen, dann entscheiden
Stellt den Abschluss eines ausstehenden Uploads für den Worker-Dienst in die Warteschlange, statt ihn in der Anfrage auszuführen, und gibt den Job sofort mit 202 zurück; verfolgen Sie ihn mit getCompletionJob. Ein erneuter Aufruf für denselben Upload liefert denselben Job, und ein Job, der aus einem vorübergehenden Grund fehlgeschlagen ist, wird erneut eingereiht. Ein eingereihter Job bedeutet nicht, dass das Artefakt veröffentlicht ist: Das gilt erst bei completed. 409 upload_state, wenn der Upload nicht mehr aussteht; 507 queue_full, wenn der Aufrufer 100 offene Jobs hat oder der Server 10.000.
Parameter
| Name | Ort | Typ | Erforderlich | Regeln |
|---|---|---|---|---|
repository | Pfad | string | ja | entspricht ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | Pfad | string (uuid) | ja | — |
Antwort 202
| Feld | Typ | Erforderlich | Regeln |
|---|---|---|---|
id | string (uuid) | ja | — |
uploadId | string (uuid) | ja | — |
repository | string | ja | — |
owner | string | ja | — |
status | string | ja | einer von queued, running, completed, failed |
generation | integer | ja | 0–2147483647 |
attempts | integer | ja | mindestens 0 |
credentialId | string (uuid) | nein | Optionale ID des auslösenden verwalteten Schlüssels; nie sein Geheimnis. |
errorCode | string | ja | darf null sein |
Antworten: 202, 400, 401, 403, 404, 405, 409, 422, 503, 507
Beispiel
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID/complete-async" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Abschluss-Job abrufen
GET HEAD /api/v1/jobs/{id}
Zugriff: Repository-Berechtigung: job.read; Dateischlüssel: write · Wiederholung: Wiederholen ist sicher (Lesen)
Liefert den Zustand eines mit enqueueCompletion eingereihten Abschluss-Jobs: queued, running, completed (der Upload ist veröffentlicht) oder failed mit einem errorCode, dazu die Zahl der Versuche. Der Worker unternimmt bis zu fünf Versuche mit wachsenden Pausen; Fehler wie integrity_mismatch lassen den Job sofort fehlschlagen. Nur der Ersteller des Jobs sieht ihn; für alle anderen ist es ein 404.
Parameter
| Name | Ort | Typ | Erforderlich | Regeln |
|---|---|---|---|---|
id | Pfad | string (uuid) | ja | — |
Antwort 200
| Feld | Typ | Erforderlich | Regeln |
|---|---|---|---|
id | string (uuid) | ja | — |
uploadId | string (uuid) | ja | — |
repository | string | ja | — |
owner | string | ja | — |
status | string | ja | einer von queued, running, completed, failed |
generation | integer | ja | 0–2147483647 |
attempts | integer | ja | mindestens 0 |
credentialId | string (uuid) | nein | Optionale ID des auslösenden verwalteten Schlüssels; nie sein Geheimnis. |
errorCode | string | ja | darf null sein |
Antworten: 200, 400, 401, 403, 404, 409, 422, 503, 507
Beispiel
curl -X GET "$ARKVORY_URL/api/v1/jobs/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Upload-Sitzung erstellen
POST /api/v1/repositories/{repository}/uploads
Zugriff: Repository-Berechtigung: upload.create; Dateischlüssel: write · Wiederholung: Wiederholen ist sicher mit demselben Idempotency-Key
Reserviert einen Upload für eine Datei, die durch name, size (eine Dezimalzeichenfolge), sha256 und optionale labels und metadata beschrieben wird; liefert 201 mit der Sitzung (pending, 7 Tage gültig) und ihrem Header Location. Idempotency-Key (1–128 Buchstaben, Ziffern und _.:-) ist erforderlich: Derselbe Schlüssel mit derselben Beschreibung liefert dieselbe Sitzung, mit einer anderen Beschreibung ergibt er 409 idempotency_mismatch. Die Größe wird sofort auf das Kontingent des Repositorys und die Kapazität des Servers angerechnet (507). Senden Sie die Bytes anschließend vollständig mit putUploadContent oder in Teilen mit putUploadPart und schließen Sie mit completeUpload ab.
Parameter
| Name | Ort | Typ | Erforderlich | Regeln |
|---|---|---|---|---|
repository | Pfad | string | ja | entspricht ^[a-z0-9][a-z0-9_-]{0,63}$ |
Idempotency-Key | Header | string | ja | höchstens 128 Zeichen |
Anfragetext (application/json)
| Feld | Typ | Erforderlich | Regeln |
|---|---|---|---|
name | string | ja | 1–240 Zeichen |
size | string | ja | eine ganze Zahl in Dezimalziffern, als String gesendet |
sha256 | string | ja | SHA-256: 64 hexadezimale Ziffern in Kleinbuchstaben |
labels | Array von string | nein | höchstens 32 Elemente; jedes Element: höchstens 64 Zeichen |
metadata | Map von string | nein | höchstens 32 Einträge |
Antwort 201
| Feld | Typ | Erforderlich | Regeln |
|---|---|---|---|
id | string (uuid) | ja | — |
repository | string | ja | — |
status | string | ja | einer von pending, available, cancelled |
createdAt | string (date-time) | ja | — |
expiresAt | string (date-time) | ja | — |
descriptor | object | ja | — |
descriptor.name | string | ja | 1–240 Zeichen |
descriptor.size | string | ja | eine ganze Zahl in Dezimalziffern, als String gesendet |
descriptor.sha256 | string | ja | SHA-256: 64 hexadezimale Ziffern in Kleinbuchstaben |
descriptor.labels | Array von string | nein | höchstens 32 Elemente; jedes Element: höchstens 64 Zeichen |
descriptor.metadata | Map von string | nein | höchstens 32 Einträge |
Antworten: 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Beispiel
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>"}'Upload abrufen
GET HEAD /api/v1/repositories/{repository}/uploads/{id}
Zugriff: Repository-Berechtigung: upload.read; Dateischlüssel: write · Wiederholung: Wiederholen ist sicher (Lesen)
Liefert die Sitzung mit ihrem status (pending, available nach der Veröffentlichung, cancelled), ihrem Ablaufzeitpunkt und dem angegebenen Deskriptor. Lesen Sie sie nach einer verlorenen Antwort auf putUploadContent oder completeUpload als Erstes: available bedeutet, dass das Artefakt unter derselben ID veröffentlicht ist. Nur der Ersteller des Uploads sieht sie; für alle anderen ist es ein 404.
Parameter
| Name | Ort | Typ | Erforderlich | Regeln |
|---|---|---|---|---|
repository | Pfad | string | ja | entspricht ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | Pfad | string (uuid) | ja | — |
Antwort 200
| Feld | Typ | Erforderlich | Regeln |
|---|---|---|---|
id | string (uuid) | ja | — |
repository | string | ja | — |
status | string | ja | einer von pending, available, cancelled |
createdAt | string (date-time) | ja | — |
expiresAt | string (date-time) | ja | — |
descriptor | object | ja | — |
descriptor.name | string | ja | 1–240 Zeichen |
descriptor.size | string | ja | eine ganze Zahl in Dezimalziffern, als String gesendet |
descriptor.sha256 | string | ja | SHA-256: 64 hexadezimale Ziffern in Kleinbuchstaben |
descriptor.labels | Array von string | nein | höchstens 32 Elemente; jedes Element: höchstens 64 Zeichen |
descriptor.metadata | Map von string | nein | höchstens 32 Einträge |
Antworten: 200, 400, 401, 403, 404, 409, 422, 503, 507
Beispiel
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Upload abbrechen
DELETE /api/v1/repositories/{repository}/uploads/{id}
Zugriff: Repository-Berechtigung: upload.cancel; Dateischlüssel: write · Wiederholung: Upload erneut lesen, dann entscheiden
Bricht einen ausstehenden Upload ab und liefert ihn mit dem Status cancelled zurück; ein veröffentlichter Upload lässt sich nicht abbrechen (409 upload_state). Die empfangenen Bytes werden sofort ausgeblendet, bleiben aber auf das Kontingent angerechnet, bis die Online-Bereinigung des Repositorys (setCleanup, standardmäßig aus) sie nach ihrer Karenzzeit entfernt.
Parameter
| Name | Ort | Typ | Erforderlich | Regeln |
|---|---|---|---|---|
repository | Pfad | string | ja | entspricht ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | Pfad | string (uuid) | ja | — |
Antwort 200
| Feld | Typ | Erforderlich | Regeln |
|---|---|---|---|
id | string (uuid) | ja | — |
repository | string | ja | — |
status | string | ja | einer von pending, available, cancelled |
createdAt | string (date-time) | ja | — |
expiresAt | string (date-time) | ja | — |
descriptor | object | ja | — |
descriptor.name | string | ja | 1–240 Zeichen |
descriptor.size | string | ja | eine ganze Zahl in Dezimalziffern, als String gesendet |
descriptor.sha256 | string | ja | SHA-256: 64 hexadezimale Ziffern in Kleinbuchstaben |
descriptor.labels | Array von string | nein | höchstens 32 Elemente; jedes Element: höchstens 64 Zeichen |
descriptor.metadata | Map von string | nein | höchstens 32 Einträge |
Antworten: 200, 400, 401, 403, 404, 405, 409, 422, 503, 507
Beispiel
curl -X DELETE "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Die ganze Datei in einer Anfrage hochladen
PUT /api/v1/repositories/{repository}/uploads/{id}/content
Zugriff: Repository-Berechtigung: upload.write, upload.complete; Dateischlüssel: write · Wiederholung: Upload erneut lesen, dann entscheiden
Streamt den Request-Body als vollständigen Inhalt eines ausstehenden Uploads, prüft ihn gegen die angegebene Größe und den angegebenen SHA-256 (422 bei Abweichung) und veröffentlicht das Artefakt; die Antwort ist der Upload mit dem Status available. Eine unterbrochene Anfrage hinterlässt nichts, was sich fortsetzen ließe: Lesen Sie den Upload mit getUpload und senden Sie die Datei erneut ab Byte null. Nicht für einen Upload, der schon Teile hat (409 upload_state); außerdem muss eine Anfrage innerhalb der Upload-Frist des Servers (standardmäßig 30 Minuten) abgeschlossen sein, senden Sie große Dateien daher in Teilen.
Parameter
| Name | Ort | Typ | Erforderlich | Regeln |
|---|---|---|---|---|
repository | Pfad | string | ja | entspricht ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | Pfad | string (uuid) | ja | — |
Anfragetext (application/octet-stream)
Antwort 200
| Feld | Typ | Erforderlich | Regeln |
|---|---|---|---|
id | string (uuid) | ja | — |
repository | string | ja | — |
status | string | ja | einer von pending, available, cancelled |
createdAt | string (date-time) | ja | — |
expiresAt | string (date-time) | ja | — |
descriptor | object | ja | — |
descriptor.name | string | ja | 1–240 Zeichen |
descriptor.size | string | ja | eine ganze Zahl in Dezimalziffern, als String gesendet |
descriptor.sha256 | string | ja | SHA-256: 64 hexadezimale Ziffern in Kleinbuchstaben |
descriptor.labels | Array von string | nein | höchstens 32 Elemente; jedes Element: höchstens 64 Zeichen |
descriptor.metadata | Map von string | nein | höchstens 32 Einträge |
Antworten: 200, 400, 401, 403, 404, 405, 409, 422, 503, 507
Beispiel
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 @fileUpload abschließen
POST /api/v1/repositories/{repository}/uploads/{id}/complete
Zugriff: Repository-Berechtigung: upload.complete; Dateischlüssel: write · Wiederholung: Upload erneut lesen, dann entscheiden
Setzt die gespeicherten Teile der Reihe nach zusammen, prüft die gesamte Datei gegen die angegebene Größe und den angegebenen SHA-256 und veröffentlicht das Artefakt; liefert den Upload mit dem Status available. Ein erneuter Aufruf für einen veröffentlichten Upload liefert dasselbe Ergebnis und holt damit auch einen Abschluss nach, dessen Antwort verloren ging. Ein fehlendes Teil ergibt 409 parts_incomplete, ein abweichender Inhalt 422; für sehr große Dateien, bei denen die Anfrage in ein Timeout laufen könnte, verwenden Sie stattdessen enqueueCompletion.
Parameter
| Name | Ort | Typ | Erforderlich | Regeln |
|---|---|---|---|---|
repository | Pfad | string | ja | entspricht ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | Pfad | string (uuid) | ja | — |
Antwort 200
| Feld | Typ | Erforderlich | Regeln |
|---|---|---|---|
id | string (uuid) | ja | — |
repository | string | ja | — |
status | string | ja | einer von pending, available, cancelled |
createdAt | string (date-time) | ja | — |
expiresAt | string (date-time) | ja | — |
descriptor | object | ja | — |
descriptor.name | string | ja | 1–240 Zeichen |
descriptor.size | string | ja | eine ganze Zahl in Dezimalziffern, als String gesendet |
descriptor.sha256 | string | ja | SHA-256: 64 hexadezimale Ziffern in Kleinbuchstaben |
descriptor.labels | Array von string | nein | höchstens 32 Elemente; jedes Element: höchstens 64 Zeichen |
descriptor.metadata | Map von string | nein | höchstens 32 Einträge |
Antworten: 200, 400, 401, 403, 404, 405, 409, 422, 503, 507
Beispiel
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID/complete" \
-H "Authorization: Bearer $ARKVORY_TOKEN"