Dateien nach Pfad

Dateien, die über einen Pfad im Repository adressiert werden: Revisionen, Verlauf, Wiederherstellung und Raw-Dateien in einer einzigen Anfrage.

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

Dateipfade nach Präfix auflisten

GET HEAD /api/v1/repositories/{repository}/assets

Zugriff: Repository-Berechtigung: asset.read; Dateischlüssel: read · Wiederholung: Wiederholen ist sicher (Lesen)

Liefert jeden Dateipfad, der mit prefix beginnt (wörtlich, kein Muster; leer für alle), nach Pfad geordnet, jeweils mit aktueller Revision und Artefakt-ID. Es gibt keine Seitenaufteilung: Mehr als 1000 Treffer ergeben 400 mit der Aufforderung, ein engeres Präfix zu wählen; verwenden Sie daher für große Bäume besser listAssetPage.

Parameter

Name	Ort	Typ	Erforderlich	Regeln
repository	Pfad	string	ja	entspricht ^[a-z0-9][a-z0-9_-]{0,63}$
prefix	Query	string	nein	—

Antwort 200

Feld	Typ	Erforderlich	Regeln
items	Array von object	nein	—
items[].path	string	ja	—
items[].revision	integer	ja	1–2147483647
items[].artifactId	string (uuid)	ja	—

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

Beispiel

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

Dateipfade seitenweise auflisten

GET HEAD /api/v1/repositories/{repository}/assets/page

Zugriff: Repository-Berechtigung: asset.read; Dateischlüssel: read · Wiederholung: Wiederholen ist sicher (Lesen)

Liefert die aktuellen Dateipfade, die mit prefix beginnen (wörtlich; leer für alle), in UTF-8-Byte-Reihenfolge, jeweils mit aktueller Revision und Artefakt-ID. Seiten enthalten limit Einträge (1–100, Standard 50); weiter mit after = dem opaken next. Seiten sind kein Snapshot: Zwischenzeitlich geänderte Pfade können mit ihrer neueren Revision erscheinen oder bis zum nächsten Durchlauf fehlen.

Parameter

Name	Ort	Typ	Erforderlich	Regeln
repository	Pfad	string	ja	entspricht ^[a-z0-9][a-z0-9_-]{0,63}$
prefix	Query	string	nein	höchstens 1024 Zeichen; Standard ``; Case-sensitive literal prefix; % and _ are ordinary characters.
after	Query	string	nein	entspricht ^[A-Za-z0-9_-]+$; 1–8192 Zeichen
limit	Query	integer	nein	1–100; Standard 50

Antwort 200

Feld	Typ	Erforderlich	Regeln
items	Array von object	ja	höchstens 100 Elemente
items[].path	string	ja	—
items[].revision	integer	ja	1–2147483647
items[].artifactId	string (uuid)	ja	—
next	string	ja	entspricht ^[A-Za-z0-9_-]+$; 1–8192 Zeichen; darf null sein; Opaker Cursor, der an Repository und Präfix gebunden ist; am Ende null. Gewährt nie Zugriff.

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

Beispiel

curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/assets/page" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Aktuelle Revision eines Dateipfads abrufen

GET HEAD /api/v1/repositories/{repository}/asset

Zugriff: Repository-Berechtigung: asset.read; Dateischlüssel: read · Wiederholung: Wiederholen ist sicher (Lesen)

Liefert die aktuelle revision von path und die ID des Artefakts, auf das er verweist; ein unbekannter Pfad ergibt 404. Ein Pfad hat 1–1024 Zeichen in durch / getrennten Segmenten, ohne leere Segmente, ohne .- oder ..-Segmente und ohne \, : oder Steuerzeichen. Laden Sie die Bytes mit downloadAssetContent herunter oder übergeben Sie die Revision an setAsset als expectedRevision.

Parameter

Name	Ort	Typ	Erforderlich	Regeln
repository	Pfad	string	ja	entspricht ^[a-z0-9][a-z0-9_-]{0,63}$
path	Query	string	ja	—

Antwort 200

Feld	Typ	Erforderlich	Regeln
path	string	ja	—
revision	integer	ja	1–2147483647
artifactId	string (uuid)	ja	—

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

Beispiel

curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset?path=$PATH" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Einen Dateipfad auf ein Artefakt verweisen lassen

PUT /api/v1/repositories/{repository}/asset

Zugriff: Repository-Berechtigung: asset.write, artifact.read; Dateischlüssel: read, write · Wiederholung: Nur mit der erwarteten Revision wiederholen (compare-and-swap)

Lässt path ein veröffentlichtes Artefakt desselben Repositorys als seine neue Revision bezeichnen; expectedRevision ist 0, um den Pfad anzulegen, und die aktuelle Revision, um ihn zu ersetzen, sonst 409 revision_mismatch. Frühere Revisionen bleiben im Verlauf und schützen ihre Artefakte vor dem Löschen. Um Bytes zu speichern und in einer Anfrage zu benennen, verwenden Sie putRawFile.

Parameter

Name	Ort	Typ	Erforderlich	Regeln
repository	Pfad	string	ja	entspricht ^[a-z0-9][a-z0-9_-]{0,63}$

Anfragetext (application/json)

Feld	Typ	Erforderlich	Regeln
path	string	ja	—
artifactId	string (uuid)	ja	—
expectedRevision	integer	ja	0–2147483646

Antwort 200

Feld	Typ	Erforderlich	Regeln
path	string	ja	—
revision	integer	ja	1–2147483647
artifactId	string (uuid)	ja	—

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

Beispiel

curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path":"<path>","artifactId":"00000000-0000-4000-8000-000000000000","expectedRevision":0}'

Revisionen eines Dateipfads auflisten

GET HEAD /api/v1/repositories/{repository}/asset/history

Zugriff: Repository-Berechtigung: asset.read; Dateischlüssel: read · Wiederholung: Wiederholen ist sicher (Lesen)

Liefert die Revisionen von path, neueste zuerst, 50 pro Seite, jeweils mit ihrem Artefakt, dem Akteur, der Zeit und, bei einer Wiederherstellung, der kopierten sourceRevision (Akteur und Zeit sind null bei Revisionen, die frühe Serverversionen aufgezeichnet haben). Weiter mit before = next. Ein unbekannter Pfad ergibt 404.

Parameter

Name	Ort	Typ	Erforderlich	Regeln
repository	Pfad	string	ja	entspricht ^[a-z0-9][a-z0-9_-]{0,63}$
path	Query	string	ja	—
before	Query	integer	nein	1–2147483647; Only revisions strictly smaller than this value

Antwort 200

Feld	Typ	Erforderlich	Regeln
items	Array von object	ja	höchstens 50 Elemente
items[].path	string	ja	—
items[].revision	integer	ja	1–2147483647
items[].artifactId	string (uuid)	ja	—
items[].actor	string	ja	darf null sein; Null bei Verlauf, der vor Migration 4 aufgezeichnet wurde
items[].createdAt	string (date-time)	ja	darf null sein; Null bei Verlauf, der vor Migration 4 aufgezeichnet wurde
items[].sourceRevision	integer	ja	1–2147483647; darf null sein; Wiederhergestellte Revision; null bei gewöhnlichem Ersetzen
next	integer	ja	1–2147483647; darf null sein; Exklusiv vor dem Cursor; am Ende null

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

Beispiel

curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset/history?path=$PATH" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Eine Revision eines Dateipfads abrufen

GET HEAD /api/v1/repositories/{repository}/asset/revision

Zugriff: Repository-Berechtigung: asset.read; Dateischlüssel: read · Wiederholung: Wiederholen ist sicher (Lesen)

Liefert die Revision revision von path mit Artefakt-ID, Akteur, Zeit und Quelle der Wiederherstellung. Revisionen ändern sich nie, daher lässt sich die Artefakt-ID zwischenspeichern; laden Sie das Artefakt mit downloadArtifact herunter. Ein fehlender Pfad oder eine fehlende Revision ergibt 404.

Parameter

Name	Ort	Typ	Erforderlich	Regeln
repository	Pfad	string	ja	entspricht ^[a-z0-9][a-z0-9_-]{0,63}$
path	Query	string	ja	—
revision	Query	integer	ja	1–2147483647

Antwort 200

Feld	Typ	Erforderlich	Regeln
path	string	ja	—
revision	integer	ja	1–2147483647
artifactId	string (uuid)	ja	—
actor	string	ja	darf null sein; Null bei Verlauf, der vor Migration 4 aufgezeichnet wurde
createdAt	string (date-time)	ja	darf null sein; Null bei Verlauf, der vor Migration 4 aufgezeichnet wurde
sourceRevision	integer	ja	1–2147483647; darf null sein; Wiederhergestellte Revision; null bei gewöhnlichem Ersetzen

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

Beispiel

curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset/revision?path=$PATH&revision=$REVISION" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Eine frühere Revision eines Dateipfads wiederherstellen

POST /api/v1/repositories/{repository}/asset/restore

Zugriff: Repository-Berechtigung: asset.restore, asset.read, artifact.read; Dateischlüssel: read, write · Wiederholung: Nur mit der erwarteten Revision wiederholen (compare-and-swap)

Fügt eine neue Revision von path hinzu, die auf das Artefakt von sourceRevision verweist; nichts wird kopiert und keine Revision entfernt. expectedRevision muss die aktuelle Revision sein (mindestens 1), sonst 409 revision_mismatch – daher ist die Wiederholung einer bereits erfolgreichen Wiederherstellung ein 409 und keine zweite Wiederherstellung. Die neue Revision hält sourceRevision fest, und die Änderung wird in derselben Transaktion im Audit protokolliert.

Parameter

Name	Ort	Typ	Erforderlich	Regeln
repository	Pfad	string	ja	entspricht ^[a-z0-9][a-z0-9_-]{0,63}$

Anfragetext (application/json)

Feld	Typ	Erforderlich	Regeln
path	string	ja	—
sourceRevision	integer	ja	1–2147483647
expectedRevision	integer	ja	1–2147483646

Antwort 200

Feld	Typ	Erforderlich	Regeln
path	string	ja	—
revision	integer	ja	1–2147483647
artifactId	string (uuid)	ja	—

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

Beispiel

curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset/restore" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path":"<path>","sourceRevision":1,"expectedRevision":1}'

Datei nach Pfad herunterladen

GET HEAD /api/v1/repositories/{repository}/asset/content

Zugriff: Repository-Berechtigung: content.read; Dateischlüssel: read · Wiederholung: Wiederholen ist sicher (Lesen)

Löst path zu seiner aktuellen Revision auf und streamt dieses Artefakt wie downloadArtifact, mit Range, If-Range, If-None-Match und HEAD. Der Pfad wird bei jeder Anfrage aufgelöst; setzen Sie einen Download daher mit If-Range auf den zurückgegebenen ETag fort: Hat sich der Pfad inzwischen weiterbewegt, ist die Antwort die gesamte neue Datei statt einer Mischung aus beiden. downloadRawFile leistet dasselbe mit dem Pfad in der URL.

Parameter

Name	Ort	Typ	Erforderlich	Regeln
repository	Pfad	string	ja	entspricht ^[a-z0-9][a-z0-9_-]{0,63}$
Range	Header	string	nein	Single bytes range; multi-range is unsupported. HEAD ignores Range.
If-Range	Header	string	nein	Exact strong ETag; a mismatch causes a full response.
If-None-Match	Header	string	nein	Matching ETag returns 304, including HEAD.
Arkvory-Download-Id	Header	string	nein	entspricht ^[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	Header	string	nein	höchstens 80 Zeichen; 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	Header	string	nein	einer von 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.
path	Query	string	ja	—

Antworten: 200, 206, 304, 400, 401, 403, 404, 409, 416, 422, 503, 507

Beispiel

curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/asset/content?path=$PATH" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -o file

Eine Datei in einer Anfrage in einen Pfad hochladen

PUT /api/v1/repositories/{repository}/raw/{assetPath}

Zugriff: Repository-Berechtigung: upload.create, upload.write, upload.complete, asset.read, asset.write, artifact.read; Dateischlüssel: write · Wiederholung: Wiederholen ist sicher: Dieselbe Anfrage hat dieselbe Wirkung

Speichert den Request-Body beliebigen Medientyps als neue Revision des Pfads in der URL, für Skripte und CI (curl -T); die Antwort ist 201 mit Pfad, Revision und Artefakt. Mit X-Checksum-Sha256 und Content-Length werden die Bytes direkt in den Speicher gestreamt und geprüft; ohne sie werden sie zunächst zwischengespeichert und gehasht (422, wenn der Body nicht zu einer angegebenen Prüfsumme passt). Dieselben Bytes wie in der aktuellen Revision fügen nichts hinzu und ergeben 200 mit created: false, If-None-Match: * legt ausschließlich an (409 already_exists), und ein gleichzeitiger Schreiber desselben Pfads erhält 409 revision_mismatch. Für sehr große Dateien sind die fortsetzbaren Upload-Sitzungen vorzuziehen.

Parameter

Name	Ort	Typ	Erforderlich	Regeln
repository	Pfad	string	ja	entspricht ^[a-z0-9][a-z0-9_-]{0,63}$
assetPath	Pfad	string	ja	1–1024 Zeichen; File path; may contain slashes (folders). No empty, "." or ".." segments, backslash or colon.
X-Checksum-Sha256	Header	string	nein	entspricht ^[a-fA-F0-9]{64}$; SHA-256 of the body (64 hex digits); a mismatch stores nothing (422).
If-None-Match	Header	string	nein	einer von *; "*": store only when the path does not exist yet (409 already_exists).

Anfragetext (application/octet-stream)

Antwort 200

Feld	Typ	Erforderlich	Regeln
path	string	ja	—
revision	integer	ja	mindestens 1
created	boolean	ja	—
artifact	object	ja	—
artifact.id	string (uuid)	ja	—
artifact.size	string	ja	eine ganze Zahl in Dezimalziffern, als String gesendet
artifact.sha256	string	ja	SHA-256: 64 hexadezimale Ziffern in Kleinbuchstaben

Antworten: 200, 201, 400, 401, 403, 404, 405, 409, 422, 503, 507

Beispiel

curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/raw/$ASSETPATH" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @file

Datei über ihren URL-Pfad herunterladen

GET HEAD /api/v1/repositories/{repository}/raw/{assetPath}

Zugriff: Repository-Berechtigung: content.read; Dateischlüssel: read · Wiederholung: Wiederholen ist sicher (Lesen)

Streamt die aktuelle Revision des Pfads in der URL wie downloadArtifact, mit Range, If-Range, If-None-Match, HEAD und X-Arkvory-Artifact-Id, das das Artefakt nennt. Der Pfad wird bei jeder Anfrage aufgelöst; setzen Sie einen Download daher mit If-Range auf den zurückgegebenen ETag fort oder laden Sie das Artefakt über die ID herunter.

Parameter

Name	Ort	Typ	Erforderlich	Regeln
repository	Pfad	string	ja	entspricht ^[a-z0-9][a-z0-9_-]{0,63}$
assetPath	Pfad	string	ja	1–1024 Zeichen; File path; may contain slashes (folders). No empty, "." or ".." segments, backslash or colon.
Range	Header	string	nein	Single bytes range; multi-range is unsupported. HEAD ignores Range.
If-Range	Header	string	nein	Exact strong ETag; a mismatch causes a full response.
If-None-Match	Header	string	nein	Matching ETag returns 304, including HEAD.
Arkvory-Download-Id	Header	string	nein	entspricht ^[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	Header	string	nein	höchstens 80 Zeichen; 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	Header	string	nein	einer von 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.

Antworten: 200, 206, 304, 400, 401, 403, 404, 409, 416, 422, 503, 507

Beispiel

curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/raw/$ASSETPATH" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -o file