Artefakte und Katalog
Veröffentlichte Artefakte: Auflistung, Details, Inhalt, Annotationen, Referenzen, Suche, das Katalog-Audit und sein Änderungsfeed.
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
Annotationen eines Artefakts abrufen
GET HEAD /api/v1/repositories/{repository}/artifacts/{id}/annotations
Zugriff: Repository-Berechtigung: annotation.read; Dateischlüssel: read · Wiederholung: Wiederholen ist sicher (Lesen)
Liefert die aktuellen Labels, Metadaten und Sammlungen eines veröffentlichten Artefakts mit ihrer revision. Revision 0 bedeutet, dass sie nie ersetzt wurden: Labels und Metadaten sind die beim Anlegen des Uploads angegebenen, und die Sammlungen sind leer. Übergeben Sie die Revision an setAnnotations als expectedRevision.
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 |
|---|---|---|---|
revision | integer | ja | 0–2147483647 |
labels | Array von string | ja | höchstens 32 Elemente |
metadata | Map von string | ja | höchstens 32 Einträge |
collections | Array von string | ja | höchstens 32 Elemente |
Antworten: 200, 400, 401, 403, 404, 409, 422, 503, 507
Beispiel
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/annotations" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Annotationen eines Artefakts ersetzen
PUT /api/v1/repositories/{repository}/artifacts/{id}/annotations
Zugriff: Repository-Berechtigung: annotation.write, artifact.read; Dateischlüssel: read, write · Wiederholung: Nur mit der erwarteten Revision wiederholen (compare-and-swap)
Ersetzt labels, metadata und collections eines veröffentlichten Artefakts auf einmal; ein in value weggelassenes Feld wird leer. expectedRevision muss die aktuelle Revision sein (0 für die erste Änderung), sonst 409 revision_mismatch: Lesen Sie die Annotationen erneut und wenden Sie die Änderung neu an. Bis zu 32 Labels und 32 Sammlungen (1–64 Buchstaben, Ziffern oder _.:-) sowie 32 Metadateneinträge (Werte bis zu 1024 Zeichen); die Bytes und der ursprüngliche Deskriptor ändern sich nie.
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/json)
| Feld | Typ | Erforderlich | Regeln |
|---|---|---|---|
expectedRevision | integer | ja | 0–2147483646 |
value | object | ja | — |
value.labels | Array von string | nein | höchstens 32 Elemente |
value.metadata | Map von string | nein | höchstens 32 Einträge |
value.collections | Array von string | nein | höchstens 32 Elemente |
Antwort 200
| Feld | Typ | Erforderlich | Regeln |
|---|---|---|---|
revision | integer | ja | 0–2147483647 |
labels | Array von string | ja | höchstens 32 Elemente |
metadata | Map von string | ja | höchstens 32 Einträge |
collections | Array von string | ja | höchstens 32 Elemente |
Antworten: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Beispiel
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":{}}'Artefakt als UPack-Paket registrieren
POST /api/v1/repositories/{repository}/artifacts/{id}/package
Zugriff: Repository-Berechtigung: package.publish, artifact.read; Dateischlüssel: read, write · Wiederholung: Wiederholen ist sicher: Dieselbe Anfrage hat dieselbe Wirkung
Öffnet das veröffentlichte Artefakt als UPack-ZIP, liest die upack.json im Stammverzeichnis des Archivs (name, optional group, version nach SemVer) und registriert diese Paketversion dafür; unsichere oder ungültige Archive werden mit 400 abgelehnt. Eine Version ist unveränderlich: Dasselbe Artefakt erneut zu registrieren liefert denselben Eintrag, ein anderes Artefakt für eine vorhandene Kombination aus Gruppe, Name und Version (ohne Beachtung der Groß-/Kleinschreibung verglichen) ergibt 409 version_exists. Danach erscheint die Version in listPackages und wird nach Name, Versionsbereich und Stufe aufgelöst.
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 |
|---|---|---|---|
group | string | nein | — |
name | string | nein | — |
version | string | nein | — |
artifactId | string (uuid) | nein | — |
manifest | object | nein | — |
Antworten: 200, 400, 401, 403, 404, 405, 409, 422, 503, 507
Beispiel
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/package" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Artefakte suchen
GET HEAD /api/v1/repositories/{repository}/search
Zugriff: Repository-Berechtigung: artifact.list; Dateischlüssel: read · Wiederholung: Wiederholen ist sicher (Lesen)
Findet veröffentlichte Artefakte anhand von q (einer Teilzeichenfolge des Namens oder eines aktuellen Metadatenwerts, ohne Beachtung der Groß-/Kleinschreibung), eines exakten aktuellen label, einer collection und eines exakten Paars metadataKey/metadataValue, die nur zusammen angegeben werden; alle angegebenen Filter müssen zutreffen. Die Ergebnisse kommen in Seiten zu 100, nach ID geordnet, jeweils mit Größe, Erstellungs- und Veröffentlichungszeit, aktuellen Labels und Hochstufungsstufen; weiter mit after = next. Metadaten und Sammlungen werden nicht zurückgegeben: Lesen Sie sie mit getAnnotations.
Parameter
| Name | Ort | Typ | Erforderlich | Regeln |
|---|---|---|---|---|
repository | Pfad | string | ja | entspricht ^[a-z0-9][a-z0-9_-]{0,63}$ |
q | Query | string | nein | — |
label | Query | string | nein | — |
collection | Query | string | nein | — |
after | Query | string | nein | — |
metadataKey | Query | string | nein | entspricht ^[a-zA-Z][a-zA-Z0-9_.-]{0,63}$; höchstens 64 Zeichen; Exact metadata key; requires metadataValue. |
metadataValue | Query | string | nein | höchstens 1024 Zeichen; Exact case-sensitive value; requires metadataKey. Empty string is allowed. |
Antwort 200
| Feld | Typ | Erforderlich | Regeln |
|---|---|---|---|
items | Array von object | ja | höchstens 100 Elemente |
items[].id | string (uuid) | ja | — |
items[].name | string | ja | — |
items[].size | string | ja | eine ganze Zahl in Dezimalziffern, als String gesendet; Größe in Bytes, Dezimalzeichenfolge |
items[].createdAt | string (date-time) | ja | Zeitpunkt der Upload-Reservierung |
items[].publishedAt | string (date-time) | ja | darf null sein; Veröffentlichungszeit; nur dann null, wenn keine aufgezeichnet wurde |
items[].labels | Array von string | ja | höchstens 32 Elemente; Aktuelle Labels: die Annotation, wenn sie ersetzt wurde, sonst der Deskriptor des Uploads |
items[].stages | Array von string | ja | höchstens 16 Elemente; jedes Element: entspricht ^[a-z0-9][a-z0-9_.-]{0,31}$; Aktuelle Hochstufungsstufen in Byte-Reihenfolge |
next | string (uuid) | ja | darf null sein; Letzte ID einer vollen Seite; als after übergeben |
Antworten: 200, 400, 401, 403, 404, 409, 422, 503, 507
Beispiel
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/search" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Katalog-Audit eines Repositorys lesen
GET HEAD /api/v1/repositories/{repository}/audit
Zugriff: Repository-Berechtigung: audit.read; Dateischlüssel: write · Wiederholung: Wiederholen ist sicher (Lesen)
Liefert, älteste zuerst, bis zu 100 Katalogänderungen des Repositorys nach der Sequenznummer after (Standard 0): Veröffentlichungen, Löschungen, Änderungen an Annotationen und Anhängen, Paketregistrierungen, Änderungen von Dateipfaden, Referenzen, Stufen und Hochstufungen, jeweils mit Akteur, Aktion, Artefakt und Zeit. Um weiterzulesen, übergeben Sie die letzte sequence der Seite als after; es gibt kein Feld next. Downloads und Anmeldungen sind darin nicht enthalten; Spiegel folgen listCatalogChanges, das die Akteure auslässt.
Parameter
| Name | Ort | Typ | Erforderlich | Regeln |
|---|---|---|---|---|
repository | Pfad | string | ja | entspricht ^[a-z0-9][a-z0-9_-]{0,63}$ |
after | Query | string | nein | — |
Antwort 200
| Feld | Typ | Erforderlich | Regeln |
|---|---|---|---|
items | Array von object | nein | — |
items[].sequence | string | nein | — |
items[].actor | string | nein | — |
items[].action | string | nein | — |
items[].artifactId | string | nein | — |
items[].occurredAt | string (date-time) | nein | — |
Antworten: 200, 400, 401, 403, 404, 409, 422, 503, 507
Beispiel
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/audit" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Referenz zu einem Artefakt hinzufügen
POST /api/v1/repositories/{repository}/artifacts/{id}/references
Zugriff: Repository-Berechtigung: reference.write, artifact.read; Dateischlüssel: read, write · Wiederholung: Wiederholen ist sicher: Dieselbe Anfrage hat dieselbe Wirkung
Vermerkt, dass etwas außerhalb von Arkvory dieses Artefakt verwendet, unter einem frei gewählten key (1–256 Buchstaben, Ziffern oder _.:/-), zum Beispiel dem Namen einer Bereitstellung. Ein referenziertes Artefakt kann weder gelöscht noch durch die Aufbewahrungsregeln entfernt werden, solange noch eine Referenz besteht. Die Referenz gehört dem Aufrufer; denselben Schlüssel erneut hinzuzufügen ändert nichts.
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/json)
| Feld | Typ | Erforderlich | Regeln |
|---|---|---|---|
key | string | ja | höchstens 256 Zeichen |
Antworten: 204, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Beispiel
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>"}'Referenz von einem Artefakt entfernen
DELETE /api/v1/repositories/{repository}/artifacts/{id}/references
Zugriff: Repository-Berechtigung: reference.write, artifact.read; Dateischlüssel: read, write · Wiederholung: Wiederholen ist sicher: Dieselbe Anfrage hat dieselbe Wirkung
Entfernt die eigene Referenz key des Aufrufers vom Artefakt; Referenzen anderer Aufrufer bleiben bestehen. Auch das Entfernen eines nicht vorhandenen Schlüssels ist erfolgreich.
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/json)
| Feld | Typ | Erforderlich | Regeln |
|---|---|---|---|
key | string | ja | höchstens 256 Zeichen |
Antworten: 204, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Beispiel
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>"}'Artefakte auflisten
GET HEAD /api/v1/repositories/{repository}/artifacts
Zugriff: Repository-Berechtigung: artifact.list; Dateischlüssel: read · Wiederholung: Wiederholen ist sicher (Lesen)
Listet die veröffentlichten Artefakte des Repositorys nach ID geordnet auf, limit pro Seite (1–100, Standard 50); weiter mit after = next. next ist gesetzt, sobald eine Seite voll ist, daher kann die letzte Seite leer sein. Jeder Eintrag enthält den beim Upload angegebenen Deskriptor; aktuelle Labels und Metadaten stehen in getAnnotations.
Parameter
| Name | Ort | Typ | Erforderlich | Regeln |
|---|---|---|---|---|
repository | Pfad | string | ja | entspricht ^[a-z0-9][a-z0-9_-]{0,63}$ |
after | Query | string (uuid) | nein | — |
limit | Query | integer | nein | 1–100; Standard 50 |
Antwort 200
| Feld | Typ | Erforderlich | Regeln |
|---|---|---|---|
items | Array von object | nein | — |
items[].id | string (uuid) | ja | — |
items[].repository | string | ja | — |
items[].status | string | ja | einer von pending, available, cancelled |
items[].createdAt | string (date-time) | ja | — |
items[].expiresAt | string (date-time) | ja | — |
items[].descriptor | object | ja | — |
items[].descriptor.name | string | ja | 1–240 Zeichen |
items[].descriptor.size | string | ja | eine ganze Zahl in Dezimalziffern, als String gesendet |
items[].descriptor.sha256 | string | ja | SHA-256: 64 hexadezimale Ziffern in Kleinbuchstaben |
items[].descriptor.labels | Array von string | nein | höchstens 32 Elemente; jedes Element: höchstens 64 Zeichen |
items[].descriptor.metadata | Map von string | nein | höchstens 32 Einträge |
next | string | nein | darf null sein |
Antworten: 200, 400, 401, 403, 404, 409, 422, 503, 507
Beispiel
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Artefakt abrufen
GET HEAD /api/v1/repositories/{repository}/artifacts/{id}
Zugriff: Repository-Berechtigung: artifact.read; Dateischlüssel: read · Wiederholung: Wiederholen ist sicher (Lesen)
Liefert ein veröffentlichtes Artefakt: seine ID, das Repository, den Status, die Erstellungszeit und den beim Upload angegebenen Deskriptor (Name, Größe, SHA-256, ursprüngliche Labels und Metadaten). Ausstehende, abgebrochene und gelöschte Artefakte antworten mit 404. Die Bytes lesen Sie mit downloadArtifact.
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/artifacts/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Artefakt löschen
DELETE /api/v1/repositories/{repository}/artifacts/{id}
Zugriff: Repository-Berechtigung: artifact.delete · Wiederholung: Wiederholen ist sicher: Dieselbe Anfrage hat dieselbe Wirkung
Löscht ein veröffentlichtes Artefakt logisch: Es verschwindet sofort aus Listen, Suchen und Downloads, und seine Bytes werden nach der Karenzzeit von der Online-Bereinigung des Repositorys (setCleanup, standardmäßig aus) freigegeben. expectedAnnotationRevision muss der aktuellen Annotationsrevision entsprechen. Die Antwort ist 200 mit einem outcome: deleted, already_deleted, changed (die Revision weicht ab), not_found oder protected mit den blockers, die es zurückhalten (eine Referenz, eine Revision eines Dateipfads, ein Build-Anhang oder eine Hochstufungsstufe). Prüfen Sie vorab mit inspectArtifactDeletion.
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/json)
| Feld | Typ | Erforderlich | Regeln |
|---|---|---|---|
expectedAnnotationRevision | integer | ja | 0–2147483647 |
Antwort 200
| Feld | Typ | Erforderlich | Regeln |
|---|---|---|---|
id | string (uuid) | ja | — |
outcome | string | ja | einer von deleted, already_deleted, protected, changed, not_eligible, not_found |
blockers | Array von string | ja | höchstens 4 Elemente; keine wiederholten Elemente; jedes Element: einer von reference, asset_history, attachment_history, protected_label, promotion_stage |
Antworten: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Beispiel
curl -X DELETE "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"expectedAnnotationRevision":0}'Artefakt herunterladen
GET HEAD /api/v1/repositories/{repository}/artifacts/{id}/content
Zugriff: Repository-Berechtigung: content.read; Dateischlüssel: read · Wiederholung: Wiederholen ist sicher (Lesen)
Streamt die Originalbytes mit Content-Length, Content-Disposition (dem Artefaktnamen) und einem starken ETag ("sha256:<hex>"). Ein einzelner Range-Header ergibt 206 (ein nicht erfüllbarer 416); If-Range mit dem ETag setzt den Download sicher fort, und If-None-Match ergibt 304. HEAD liefert dieselben Header ohne Body und ignoriert Range. Statt eines Authorization-Headers kann die Anfrage einen Download-Link aus createDownloadLink als token tragen; Downloads warten auf einen freien Slot der Download-Zulassung des Servers.
Parameter
| Name | Ort | Typ | Erforderlich | Regeln |
|---|---|---|---|---|
repository | Pfad | string | ja | entspricht ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | Pfad | string (uuid) | ja | — |
Range | Header | string | nein | — |
If-Range | Header | string | nein | — |
If-None-Match | Header | string | nein | — |
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. |
token | Query | string | nein | entspricht ^dtl_[A-Za-z0-9_-]{43}$; Download link from POST …/artifacts/{id}/links, instead of an Authorization header |
Antworten: 200, 206, 304, 400, 401, 403, 404, 409, 416, 422, 503, 507
Beispiel
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/content" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-o fileÜbersicht der Standorte lesen
GET HEAD /api/v1/fleet/overview
Zugriff: Administrator · Wiederholung: Wiederholen ist sicher (Lesen)
Warnungen über die verwalteten Standorte und diese Installation, die schwersten zuerst (critical, warning, info), und die Spiegelverbindungen zwischen ihnen. Aus den letzten Hintergrundabfragen erstellt, höchstens alle 5 Sekunden. Eine Quelle, an deren Adresse kein verwalteter Standort antwortet, ist external:<origin>; diese Installation ist self und erhält Verbindungen zu ihr nur, wenn ARKVORY_SITE_URL gesetzt ist. Nur der Schreibprozess antwortet.
Antwort 200
| Feld | Typ | Erforderlich | Regeln |
|---|---|---|---|
generatedAt | string (date-time) | ja | — |
self | object | ja | — |
self.name | string | ja | — |
self.version | string | ja | — |
self.url | string | ja | darf null sein |
alerts | Array von object | ja | — |
alerts[].site | string | ja | — |
alerts[].name | string | ja | — |
alerts[].kind | string | ja | einer von unreachable, certificate, revoked, refused, invalid, stale, not-writable, copies, single-copy, mirror-failing, mirror-lag, updates-failed, version-skew |
alerts[].severity | string | ja | einer von critical, warning, info |
alerts[].subject | string | ja | darf null sein |
alerts[].since | string (date-time) | ja | darf null sein |
links | Array von object | ja | — |
links[].from | string | ja | — |
links[].to | string | ja | — |
links[].repository | string | ja | — |
links[].sourceRepository | string | ja | — |
links[].mode | string | ja | einer von mirror, import |
links[].lagChanges | string | ja | eine ganze Zahl in Dezimalziffern, als String gesendet; darf null sein |
links[].failing | boolean | ja | — |
links[].stale | boolean | nein | — |
external | Array von string | ja | — |
Antworten: 200, 400, 401, 403, 404, 409, 422, 503, 507
Beispiel
curl -X GET "$ARKVORY_URL/api/v1/fleet/overview" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Verwaltete Standorte auflisten
GET HEAD /api/v1/fleet/sites
Zugriff: Administrator · Wiederholung: Wiederholen ist sicher (Lesen)
Listet die Standorte, die diese Installation verwaltet (ADR 0077), mit dem, was jeder zuletzt gemeldet hat: state (ok oder warum er nicht gelesen wurde: unreachable, certificate, revoked, invalid, refused), wann er zuletzt gesehen wurde, und seine letzte topology. Standorte werden alle 30 Sekunden im Hintergrund gelesen. Ein Standortschlüssel wird nie zurückgegeben.
Antwort 200
| Feld | Typ | Erforderlich | Regeln |
|---|---|---|---|
items | Array von object | ja | höchstens 256 Elemente |
items[].id | string (uuid) | ja | — |
items[].name | string | ja | — |
items[].url | string | ja | — |
items[].fingerprint | string | ja | entspricht ^[0-9a-f]{64}$; darf null sein |
items[].addedBy | string | ja | — |
items[].addedAt | string (date-time) | ja | — |
items[].seenAt | string (date-time) | ja | darf null sein |
items[].state | string | ja | einer von pending, ok, unreachable, certificate, revoked, invalid, refused |
items[].error | string | ja | darf null sein |
items[].topology | object | ja | darf null sein |
items[].topology.collectedAt | string (date-time) | ja | — |
items[].topology.site | object | ja | — |
items[].topology.health | object | ja | — |
items[].topology.replication | object | ja | darf null sein |
items[].topology.gateways | Array von object | ja | höchstens 16 Elemente |
items[].topology.mirrors | Array von object | ja | höchstens 64 Elemente |
items[].topology.updates | object | ja | darf null sein |
items[].topology.downloads | object | ja | — |
Antworten: 200, 400, 401, 403, 404, 409, 422, 503, 507
Beispiel
curl -X GET "$ARKVORY_URL/api/v1/fleet/sites" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Mit einem Standort koppeln
POST /api/v1/fleet/sites
Zugriff: Administrator · Wiederholung: Nicht automatisch wiederholen
Koppelt einen Standort: der Controller verbindet sich erneut, das Zertifikat muss noch den vom Administrator bestätigten fingerprint haben (null für HTTP auf Loopback), der am Standort erstellte Kopplungs-code wird gegen einen Schlüssel getauscht und dieser mit ARKVORY_FLEET_KEY_FILE versiegelt. Vor der Antwort wird der Standort einmal gelesen. Ohne Schlüsseldatei lautet die Antwort 503.
Anfragetext (application/json)
| Feld | Typ | Erforderlich | Regeln |
|---|---|---|---|
url | string | ja | — |
fingerprint | string | ja | entspricht ^[0-9a-f]{64}$; darf null sein |
code | string | ja | höchstens 32 Zeichen |
Antwort 201
| Feld | Typ | Erforderlich | Regeln |
|---|---|---|---|
id | string (uuid) | ja | — |
name | string | ja | — |
url | string | ja | — |
fingerprint | string | ja | entspricht ^[0-9a-f]{64}$; darf null sein |
addedBy | string | ja | — |
addedAt | string (date-time) | ja | — |
seenAt | string (date-time) | ja | darf null sein |
state | string | ja | einer von pending, ok, unreachable, certificate, revoked, invalid, refused |
error | string | ja | darf null sein |
topology | object | ja | darf null sein |
topology.collectedAt | string (date-time) | ja | — |
topology.site | object | ja | — |
topology.site.name | string | ja | — |
topology.site.version | string | ja | — |
topology.site.schema | integer | ja | mindestens 0 |
topology.site.role | string | ja | einer von api, reader |
topology.health | object | ja | — |
topology.health.available | boolean | ja | — |
topology.health.writable | boolean | ja | — |
topology.health.draining | boolean | ja | — |
topology.replication | object | ja | darf null sein |
topology.replication.copies | integer | ja | 0–16 |
topology.replication.required | integer | ja | 1–16 |
topology.replication.singleCopyUntil | string (date-time) | ja | darf null sein |
topology.replication.node | string | nein | höchstens 63 Zeichen |
topology.replication.profile | string | nein | einer von ha-2, ha-3 |
topology.replication.peers | Array von object | nein | höchstens 16 Elemente |
topology.gateways | Array von object | ja | höchstens 16 Elemente |
topology.gateways[].slot | integer | ja | mindestens 0 |
topology.gateways[].active | boolean | ja | — |
topology.gateways[].expiresAt | string (date-time) | ja | — |
topology.mirrors | Array von object | ja | höchstens 64 Elemente |
topology.mirrors[].repository | string | ja | — |
topology.mirrors[].mode | string | ja | einer von mirror, import |
topology.mirrors[].upstream | string | ja | — |
topology.mirrors[].sourceRepository | string | ja | — |
topology.mirrors[].phase | string | ja | — |
topology.mirrors[].errorCode | string | ja | darf null sein |
topology.mirrors[].checkedAt | string (date-time) | ja | darf null sein |
topology.mirrors[].syncedAt | string (date-time) | ja | darf null sein |
topology.mirrors[].lagChanges | string | ja | eine ganze Zahl in Dezimalziffern, als String gesendet; darf null sein |
topology.mirrors[].copiedArtifacts | integer | ja | mindestens 0 |
topology.mirrors[].copiedBytes | string | ja | eine ganze Zahl in Dezimalziffern, als String gesendet |
topology.updates | object | ja | darf null sein |
topology.updates.currentVersion | string | ja | — |
topology.updates.latest | string | ja | darf null sein |
topology.updates.phase | string | ja | — |
topology.updates.error | string | ja | darf null sein |
topology.updates.automatic | boolean | ja | — |
topology.updates.heartbeatAt | string (date-time) | ja | — |
topology.downloads | object | ja | — |
topology.downloads.strategy | string | ja | einer von ordered, smallest-first, shared |
topology.downloads.sessions | integer | ja | mindestens 0 |
topology.downloads.active | integer | ja | mindestens 0 |
topology.downloads.waiting | integer | ja | mindestens 0 |
topology.downloads.oldestWaitSeconds | integer | ja | mindestens 0 |
topology.downloads.bytesPerSecond | integer | ja | mindestens 0 |
Antworten: 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Beispiel
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>"}'Zertifikat eines Standorts lesen
POST /api/v1/fleet/sites/probe
Zugriff: Administrator · Wiederholung: Wiederholen ist sicher: Dieselbe Anfrage hat dieselbe Wirkung
Verbindet sich mit der Adresse und liest das Zertifikat des Standorts, ohne etwas zu senden: vergleichen Sie seinen fingerprint vor dem Koppeln mit dem, den der Administrator des Standorts sieht.
Anfragetext (application/json)
| Feld | Typ | Erforderlich | Regeln |
|---|---|---|---|
url | string | ja | — |
Antwort 200
| Feld | Typ | Erforderlich | Regeln |
|---|---|---|---|
url | string | ja | — |
certificate | object | ja | darf null sein |
certificate.fingerprint | string | ja | entspricht ^[0-9a-f]{64}$ |
certificate.subject | string | ja | — |
certificate.issuer | string | ja | — |
certificate.validTo | string (date-time) | ja | — |
Antworten: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Beispiel
curl -X POST "$ARKVORY_URL/api/v1/fleet/sites/probe" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"url":"<url>"}'Standort vergessen
DELETE /api/v1/fleet/sites/{id}
Zugriff: Administrator · Wiederholung: Wiederholen ist sicher: Dieselbe Anfrage hat dieselbe Wirkung
Vergisst hier einen Standort und seinen versiegelten Schlüssel. Widerrufen Sie diesen Controller auch am Standort; bis dahin bleibt der Schlüssel dort gültig.
Parameter
| Name | Ort | Typ | Erforderlich | Regeln |
|---|---|---|---|---|
id | Pfad | string (uuid) | ja | — |
Antworten: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507
Beispiel
curl -X DELETE "$ARKVORY_URL/api/v1/fleet/sites/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Katalog eines Standorts lesen
GET HEAD /api/v1/fleet/sites/{id}/read
Zugriff: Administrator · Wiederholung: Wiederholen ist sicher (Lesen)
Leitet einen Katalog-Lesezugriff an einen verwalteten Standort weiter und gibt dessen Antwort unverändert zurück: Repositorys, Suche, Artefakte, Annotationen, Stufen, Pakete, Dateiseiten und -verlauf, Speicherbelegung, Spiegelzustand. path ist die Route des Standorts mit ihrer Abfrage. Andere Routen und Dateibytes werden mit 400 abgelehnt.
Parameter
| Name | Ort | Typ | Erforderlich | Regeln |
|---|---|---|---|---|
id | Pfad | string (uuid) | ja | — |
path | Query | string | ja | entspricht ^/api/v1/; höchstens 2048 Zeichen; 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. |
Antworten: 200, 400, 401, 403, 404, 409, 422, 503, 507
Beispiel
curl -X GET "$ARKVORY_URL/api/v1/fleet/sites/$ID/read?path=$PATH" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Eine Einstellung eines Standorts ändern
POST /api/v1/fleet/sites/{id}/change
Zugriff: Administrator · Wiederholung: Nicht automatisch wiederholen
Leitet eine Änderung an einen verwalteten Standort weiter und gibt dessen Antwort unverändert zurück. path ist eine dieser Routen: /api/v1/system/downloads/settings (Einstellungen der Download-Warteschlange, als PUT gesendet) oder /api/v1/system/updates/requests (eine Update-Anfrage, als POST gesendet). Der Body geht unverändert an den Standort; der Standort prüft Revision oder Anfrage-ID, daher wird eine wiederholte Änderung nicht doppelt angewendet. Andere Pfade werden mit 400 abgelehnt.
Parameter
| Name | Ort | Typ | Erforderlich | Regeln |
|---|---|---|---|---|
id | Pfad | string (uuid) | ja | — |
path | Query | string | ja | entspricht ^/api/v1/; höchstens 2048 Zeichen; A change route of the site, from a fixed list: PUT /api/v1/system/downloads/settings, POST /api/v1/system/updates/requests. |
Anfragetext (application/json)
Antworten: 200, 202, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Beispiel
curl -X POST "$ARKVORY_URL/api/v1/fleet/sites/$ID/change?path=$PATH" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'Standort jetzt lesen
POST /api/v1/fleet/sites/{id}/refresh
Zugriff: Administrator · Wiederholung: Wiederholen ist sicher: Dieselbe Anfrage hat dieselbe Wirkung
Liest den Standort jetzt, statt auf die nächste Runde zu warten, und gibt ihn mit dem neuen Zustand zurück.
Parameter
| Name | Ort | Typ | Erforderlich | Regeln |
|---|---|---|---|---|
id | Pfad | string (uuid) | ja | — |
Antwort 200
| Feld | Typ | Erforderlich | Regeln |
|---|---|---|---|
id | string (uuid) | ja | — |
name | string | ja | — |
url | string | ja | — |
fingerprint | string | ja | entspricht ^[0-9a-f]{64}$; darf null sein |
addedBy | string | ja | — |
addedAt | string (date-time) | ja | — |
seenAt | string (date-time) | ja | darf null sein |
state | string | ja | einer von pending, ok, unreachable, certificate, revoked, invalid, refused |
error | string | ja | darf null sein |
topology | object | ja | darf null sein |
topology.collectedAt | string (date-time) | ja | — |
topology.site | object | ja | — |
topology.site.name | string | ja | — |
topology.site.version | string | ja | — |
topology.site.schema | integer | ja | mindestens 0 |
topology.site.role | string | ja | einer von api, reader |
topology.health | object | ja | — |
topology.health.available | boolean | ja | — |
topology.health.writable | boolean | ja | — |
topology.health.draining | boolean | ja | — |
topology.replication | object | ja | darf null sein |
topology.replication.copies | integer | ja | 0–16 |
topology.replication.required | integer | ja | 1–16 |
topology.replication.singleCopyUntil | string (date-time) | ja | darf null sein |
topology.replication.node | string | nein | höchstens 63 Zeichen |
topology.replication.profile | string | nein | einer von ha-2, ha-3 |
topology.replication.peers | Array von object | nein | höchstens 16 Elemente |
topology.gateways | Array von object | ja | höchstens 16 Elemente |
topology.gateways[].slot | integer | ja | mindestens 0 |
topology.gateways[].active | boolean | ja | — |
topology.gateways[].expiresAt | string (date-time) | ja | — |
topology.mirrors | Array von object | ja | höchstens 64 Elemente |
topology.mirrors[].repository | string | ja | — |
topology.mirrors[].mode | string | ja | einer von mirror, import |
topology.mirrors[].upstream | string | ja | — |
topology.mirrors[].sourceRepository | string | ja | — |
topology.mirrors[].phase | string | ja | — |
topology.mirrors[].errorCode | string | ja | darf null sein |
topology.mirrors[].checkedAt | string (date-time) | ja | darf null sein |
topology.mirrors[].syncedAt | string (date-time) | ja | darf null sein |
topology.mirrors[].lagChanges | string | ja | eine ganze Zahl in Dezimalziffern, als String gesendet; darf null sein |
topology.mirrors[].copiedArtifacts | integer | ja | mindestens 0 |
topology.mirrors[].copiedBytes | string | ja | eine ganze Zahl in Dezimalziffern, als String gesendet |
topology.updates | object | ja | darf null sein |
topology.updates.currentVersion | string | ja | — |
topology.updates.latest | string | ja | darf null sein |
topology.updates.phase | string | ja | — |
topology.updates.error | string | ja | darf null sein |
topology.updates.automatic | boolean | ja | — |
topology.updates.heartbeatAt | string (date-time) | ja | — |
topology.downloads | object | ja | — |
topology.downloads.strategy | string | ja | einer von ordered, smallest-first, shared |
topology.downloads.sessions | integer | ja | mindestens 0 |
topology.downloads.active | integer | ja | mindestens 0 |
topology.downloads.waiting | integer | ja | mindestens 0 |
topology.downloads.oldestWaitSeconds | integer | ja | mindestens 0 |
topology.downloads.bytesPerSecond | integer | ja | mindestens 0 |
Antworten: 200, 400, 401, 403, 404, 405, 409, 422, 503, 507
Beispiel
curl -X POST "$ARKVORY_URL/api/v1/fleet/sites/$ID/refresh" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Kopplungscode erstellen
POST /api/v1/system/fleet/pairings
Zugriff: Administrator · Wiederholung: Nicht automatisch wiederholen
Erstellt einen einmaligen, zehn Minuten gültigen Code, den der Administrator eines Controllers eingibt, um diesen Standort zu verwalten. Der Code wird einmal angezeigt und nur als Hash gespeichert. Nur der globale Administrator des Standorts darf ihn erstellen.
Antwort 201
| Feld | Typ | Erforderlich | Regeln |
|---|---|---|---|
code | string | ja | entspricht ^[0-9A-Z]{4}-[0-9A-Z]{4}-[0-9A-Z]{4}$ |
expiresAt | string (date-time) | ja | — |
fingerprint | string | ja | entspricht ^[0-9a-f]{64}$; darf null sein |
Antworten: 201, 400, 401, 403, 404, 405, 409, 422, 503, 507
Beispiel
curl -X POST "$ARKVORY_URL/api/v1/system/fleet/pairings" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Controller des Standorts auflisten
GET HEAD /api/v1/system/fleet/controllers
Zugriff: Administrator · Wiederholung: Wiederholen ist sicher (Lesen)
Listet die Controller auf, die diesen Standort verwalten dürfen: Name, wer sie gekoppelt hat, wann, und wann ihr Schlüssel zuletzt benutzt wurde.
Antwort 200
| Feld | Typ | Erforderlich | Regeln |
|---|---|---|---|
items | Array von object | ja | höchstens 100 Elemente |
items[].id | string (uuid) | ja | — |
items[].name | string | ja | — |
items[].pairedBy | string | ja | — |
items[].pairedAt | string (date-time) | ja | — |
items[].usedAt | string (date-time) | ja | darf null sein |
Antworten: 200, 400, 401, 403, 404, 409, 422, 503, 507
Beispiel
curl -X GET "$ARKVORY_URL/api/v1/system/fleet/controllers" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Controller widerrufen
DELETE /api/v1/system/fleet/controllers/{id}
Zugriff: Administrator · Wiederholung: Wiederholen ist sicher: Dieselbe Anfrage hat dieselbe Wirkung
Widerruft einen Controller: sein Flottenschlüssel wird sofort abgelehnt. Um den Standort wieder zu verwalten, muss er mit einem neuen Code gekoppelt werden.
Parameter
| Name | Ort | Typ | Erforderlich | Regeln |
|---|---|---|---|---|
id | Pfad | string (uuid) | ja | — |
Antworten: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507
Beispiel
curl -X DELETE "$ARKVORY_URL/api/v1/system/fleet/controllers/$ID" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Mit einem Controller koppeln
POST /api/v1/system/fleet/enrollment
Zugriff: Jeder, ohne Schlüssel · Wiederholung: Nicht automatisch wiederholen
Tauscht einen gültigen Kopplungscode einmal gegen einen Flottenschlüssel. Der Controller ruft dies über TLS auf, das auf den vom Administrator bestätigten Fingerabdruck festgelegt ist. Der Schlüssel wird einmal zurückgegeben und erreicht nur die Routen, die ein Controller braucht.
Anfragetext (application/json)
| Feld | Typ | Erforderlich | Regeln |
|---|---|---|---|
code | string | ja | höchstens 32 Zeichen |
name | string | ja | 1–63 Zeichen |
Antwort 201
| Feld | Typ | Erforderlich | Regeln |
|---|---|---|---|
key | string | ja | entspricht ^afk_[A-Za-z0-9_-]{43}$ |
site | object | ja | — |
site.name | string | ja | — |
site.version | string | ja | — |
Antworten: 201, 400, 403, 405, 413, 415, 503
Beispiel
curl -X POST "$ARKVORY_URL/api/v1/system/fleet/enrollment" \
-H "Content-Type: application/json" \
-d '{"code":"<code>","name":"<name>"}'Diesen Standort für die Flottenkonsole lesen
GET HEAD /api/v1/system/topology
Zugriff: Administrator · Wiederholung: Wiederholen ist sicher (Lesen)
Liefert diese Installation als einen Standort einer Flotte (ADR 0077): Name, Version, Schema und Rolle, ob sie verfügbar und beschreibbar ist, die HA-Kopien und -Knoten, die Lese-Gateways aus ihren Leases, jeden Spiegel und Import mit Phase, letzter Synchronisierung und lagChanges (noch nicht übernommene Änderungen der Quelle), den Zustand des Update-Agenten und die Download-Warteschlange. Lesen darf nur der globale Administrator des Standorts oder ein damit gekoppelter Controller.
Antwort 200
| Feld | Typ | Erforderlich | Regeln |
|---|---|---|---|
collectedAt | string (date-time) | ja | — |
site | object | ja | — |
site.name | string | ja | — |
site.version | string | ja | — |
site.schema | integer | ja | mindestens 0 |
site.role | string | ja | einer von api, reader |
health | object | ja | — |
health.available | boolean | ja | — |
health.writable | boolean | ja | — |
health.draining | boolean | ja | — |
replication | object | ja | darf null sein |
replication.copies | integer | ja | 0–16 |
replication.required | integer | ja | 1–16 |
replication.singleCopyUntil | string (date-time) | ja | darf null sein |
replication.node | string | nein | höchstens 63 Zeichen |
replication.profile | string | nein | einer von ha-2, ha-3 |
replication.peers | Array von object | nein | höchstens 16 Elemente |
replication.peers[].name | string | ja | höchstens 63 Zeichen |
replication.peers[].connected | boolean | ja | — |
replication.peers[].disk | string | ja | höchstens 24 Zeichen |
replication.peers[].complete | boolean | ja | — |
replication.peers[].witness | boolean | ja | — |
gateways | Array von object | ja | höchstens 16 Elemente |
gateways[].slot | integer | ja | mindestens 0 |
gateways[].active | boolean | ja | — |
gateways[].expiresAt | string (date-time) | ja | — |
mirrors | Array von object | ja | höchstens 64 Elemente |
mirrors[].repository | string | ja | — |
mirrors[].mode | string | ja | einer von mirror, import |
mirrors[].upstream | string | ja | — |
mirrors[].sourceRepository | string | ja | — |
mirrors[].phase | string | ja | — |
mirrors[].errorCode | string | ja | darf null sein |
mirrors[].checkedAt | string (date-time) | ja | darf null sein |
mirrors[].syncedAt | string (date-time) | ja | darf null sein |
mirrors[].lagChanges | string | ja | eine ganze Zahl in Dezimalziffern, als String gesendet; darf null sein |
mirrors[].copiedArtifacts | integer | ja | mindestens 0 |
mirrors[].copiedBytes | string | ja | eine ganze Zahl in Dezimalziffern, als String gesendet |
updates | object | ja | darf null sein |
updates.currentVersion | string | ja | — |
updates.latest | string | ja | darf null sein |
updates.phase | string | ja | — |
updates.error | string | ja | darf null sein |
updates.automatic | boolean | ja | — |
updates.heartbeatAt | string (date-time) | ja | — |
downloads | object | ja | — |
downloads.strategy | string | ja | einer von ordered, smallest-first, shared |
downloads.sessions | integer | ja | mindestens 0 |
downloads.active | integer | ja | mindestens 0 |
downloads.waiting | integer | ja | mindestens 0 |
downloads.oldestWaitSeconds | integer | ja | mindestens 0 |
downloads.bytesPerSecond | integer | ja | mindestens 0 |
Antworten: 200, 400, 401, 403, 404, 409, 422, 503, 507
Beispiel
curl -X GET "$ARKVORY_URL/api/v1/system/topology" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Einstellungen der Download-Warteschlange lesen
GET HEAD /api/v1/system/downloads/settings
Zugriff: Administrator · Wiederholung: Wiederholen ist sicher (Lesen)
Gibt die geänderten Werte (overrides), die Werte aus der Umgebung des Servers (defaults) und das, was die Warteschlange jetzt verwendet (effective), zurück, dazu die Revision für eine Änderung. problem nennt, warum gespeicherte Einstellungen nicht zu diesem Server passen; die Warteschlange läuft dann mit den Standardwerten.
Antwort 200
| Feld | Typ | Erforderlich | Regeln |
|---|---|---|---|
revision | integer | ja | 0–9007199254740991 |
overrides | object | ja | — |
overrides.strategy | string | nein | einer von ordered, smallest-first, shared |
overrides.sessions | integer | nein | 1–1024 |
overrides.reserve | integer | nein | 0–1023 |
overrides.perPrincipal | integer | nein | 1–1024 |
overrides.weights | object | nein | — |
overrides.weights.interactive | integer | ja | 1–1000 |
overrides.weights.release | integer | ja | 1–1000 |
overrides.weights.bulk | integer | ja | 1–1000 |
overrides.weights.background | integer | ja | 1–1000 |
overrides.sessionMinBytes | integer | nein | 0–9007199254740991 |
overrides.idleSeconds | integer | nein | 1–3600 |
overrides.agingMinutes | integer | nein | 0–10080 |
overrides.preempt | boolean | nein | — |
overrides.rangesPerSession | integer | nein | 1–64 |
defaults | object | ja | — |
defaults.strategy | string | ja | einer von ordered, smallest-first, shared |
defaults.sessions | integer | ja | 1–1024 |
defaults.reserve | integer | ja | 0–1023 |
defaults.perPrincipal | integer | ja | 1–1024 |
defaults.weights | object | ja | — |
defaults.weights.interactive | integer | ja | 1–1000 |
defaults.weights.release | integer | ja | 1–1000 |
defaults.weights.bulk | integer | ja | 1–1000 |
defaults.weights.background | integer | ja | 1–1000 |
defaults.sessionMinBytes | integer | ja | 0–9007199254740991 |
defaults.idleSeconds | integer | ja | 1–3600 |
defaults.agingMinutes | integer | ja | 0–10080 |
defaults.preempt | boolean | ja | — |
defaults.rangesPerSession | integer | ja | 1–64 |
effective | object | ja | — |
effective.strategy | string | ja | einer von ordered, smallest-first, shared |
effective.sessions | integer | ja | 1–1024 |
effective.reserve | integer | ja | 0–1023 |
effective.perPrincipal | integer | ja | 1–1024 |
effective.weights | object | ja | — |
effective.weights.interactive | integer | ja | 1–1000 |
effective.weights.release | integer | ja | 1–1000 |
effective.weights.bulk | integer | ja | 1–1000 |
effective.weights.background | integer | ja | 1–1000 |
effective.sessionMinBytes | integer | ja | 0–9007199254740991 |
effective.idleSeconds | integer | ja | 1–3600 |
effective.agingMinutes | integer | ja | 0–10080 |
effective.preempt | boolean | ja | — |
effective.rangesPerSession | integer | ja | 1–64 |
admission | string | ja | einer von sessions, per-request |
updatedAt | string (date-time) | ja | darf null sein |
updatedBy | string | ja | darf null sein |
actor | string | ja | darf null sein |
problem | string | ja | darf null sein |
Antworten: 200, 400, 401, 403, 404, 409, 422, 503, 507
Beispiel
curl -X GET "$ARKVORY_URL/api/v1/system/downloads/settings" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Einstellungen der Download-Warteschlange ändern
PUT /api/v1/system/downloads/settings
Zugriff: Administrator · Wiederholung: Nur mit der erwarteten Revision wiederholen (compare-and-swap)
Speichert overrides über der Umgebung des Servers und wendet sie ohne Neustart an: neue Entscheidungen folgen ihnen sofort, aktive Downloads behalten ihre Plätze. Die angegebenen Werte ersetzen alle früheren Änderungen; {} kehrt zur Umgebung zurück. Einstellungen, die hier nicht laufen können, werden mit 400 und dem Feldnamen abgelehnt; eine veraltete expectedRevision erhält 409. Lese-Gateways behalten ihre Umgebung.
Anfragetext (application/json)
| Feld | Typ | Erforderlich | Regeln |
|---|---|---|---|
expectedRevision | integer | ja | 0–9007199254740991 |
overrides | object | ja | — |
overrides.strategy | string | nein | einer von ordered, smallest-first, shared |
overrides.sessions | integer | nein | 1–1024 |
overrides.reserve | integer | nein | 0–1023 |
overrides.perPrincipal | integer | nein | 1–1024 |
overrides.weights | object | nein | — |
overrides.weights.interactive | integer | ja | 1–1000 |
overrides.weights.release | integer | ja | 1–1000 |
overrides.weights.bulk | integer | ja | 1–1000 |
overrides.weights.background | integer | ja | 1–1000 |
overrides.sessionMinBytes | integer | nein | 0–9007199254740991 |
overrides.idleSeconds | integer | nein | 1–3600 |
overrides.agingMinutes | integer | nein | 0–10080 |
overrides.preempt | boolean | nein | — |
overrides.rangesPerSession | integer | nein | 1–64 |
Antwort 200
| Feld | Typ | Erforderlich | Regeln |
|---|---|---|---|
revision | integer | ja | 0–9007199254740991 |
overrides | object | ja | — |
overrides.strategy | string | nein | einer von ordered, smallest-first, shared |
overrides.sessions | integer | nein | 1–1024 |
overrides.reserve | integer | nein | 0–1023 |
overrides.perPrincipal | integer | nein | 1–1024 |
overrides.weights | object | nein | — |
overrides.weights.interactive | integer | ja | 1–1000 |
overrides.weights.release | integer | ja | 1–1000 |
overrides.weights.bulk | integer | ja | 1–1000 |
overrides.weights.background | integer | ja | 1–1000 |
overrides.sessionMinBytes | integer | nein | 0–9007199254740991 |
overrides.idleSeconds | integer | nein | 1–3600 |
overrides.agingMinutes | integer | nein | 0–10080 |
overrides.preempt | boolean | nein | — |
overrides.rangesPerSession | integer | nein | 1–64 |
defaults | object | ja | — |
defaults.strategy | string | ja | einer von ordered, smallest-first, shared |
defaults.sessions | integer | ja | 1–1024 |
defaults.reserve | integer | ja | 0–1023 |
defaults.perPrincipal | integer | ja | 1–1024 |
defaults.weights | object | ja | — |
defaults.weights.interactive | integer | ja | 1–1000 |
defaults.weights.release | integer | ja | 1–1000 |
defaults.weights.bulk | integer | ja | 1–1000 |
defaults.weights.background | integer | ja | 1–1000 |
defaults.sessionMinBytes | integer | ja | 0–9007199254740991 |
defaults.idleSeconds | integer | ja | 1–3600 |
defaults.agingMinutes | integer | ja | 0–10080 |
defaults.preempt | boolean | ja | — |
defaults.rangesPerSession | integer | ja | 1–64 |
effective | object | ja | — |
effective.strategy | string | ja | einer von ordered, smallest-first, shared |
effective.sessions | integer | ja | 1–1024 |
effective.reserve | integer | ja | 0–1023 |
effective.perPrincipal | integer | ja | 1–1024 |
effective.weights | object | ja | — |
effective.weights.interactive | integer | ja | 1–1000 |
effective.weights.release | integer | ja | 1–1000 |
effective.weights.bulk | integer | ja | 1–1000 |
effective.weights.background | integer | ja | 1–1000 |
effective.sessionMinBytes | integer | ja | 0–9007199254740991 |
effective.idleSeconds | integer | ja | 1–3600 |
effective.agingMinutes | integer | ja | 0–10080 |
effective.preempt | boolean | ja | — |
effective.rangesPerSession | integer | ja | 1–64 |
admission | string | ja | einer von sessions, per-request |
updatedAt | string (date-time) | ja | darf null sein |
updatedBy | string | ja | darf null sein |
actor | string | ja | darf null sein |
problem | string | ja | darf null sein |
Antworten: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Beispiel
curl -X PUT "$ARKVORY_URL/api/v1/system/downloads/settings" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"expectedRevision":0,"overrides":{}}'Änderungen des Standorts lesen
GET HEAD /api/v1/system/changes
Zugriff: Administrator · Wiederholung: Wiederholen ist sicher (Lesen)
Gibt zurück, ob sich der Agent des Standorts meldet (agent), die wartende Anfrage und die 20 neuesten mit ihrem Zustand: pending, applying, done oder failed mit Grund. Quellschlüssel erscheinen hier nie.
Antwort 200
| Feld | Typ | Erforderlich | Regeln |
|---|---|---|---|
agent | boolean | ja | — |
updating | boolean | ja | — |
blocked | string | ja | einer von expired, interrupted, key_missing, not_a_mirror, already_attached, mirror_failed, switchover_failed, single_copy_failed, unreadable, digest_mismatch, null; darf null sein |
pending | object | ja | darf null sein |
pending.id | string (uuid) | ja | — |
pending.kind | string | ja | einer von mirror-attach, mirror-key, mirror-detach, cluster-switchover, single-copy |
pending.actor | string | ja | höchstens 200 Zeichen |
pending.requestedAt | string (date-time) | ja | — |
recent | Array von object | ja | höchstens 20 Elemente |
recent[].id | string (uuid) | ja | — |
recent[].digest | string | ja | entspricht ^[0-9a-f]{64}$ |
recent[].kind | string | ja | einer von mirror-attach, mirror-key, mirror-detach, cluster-switchover, single-copy |
recent[].state | string | ja | einer von pending, applying, done, failed |
recent[].error | string | ja | einer von expired, interrupted, key_missing, not_a_mirror, already_attached, mirror_failed, switchover_failed, single_copy_failed, unreadable, digest_mismatch, null; darf null sein |
recent[].actor | string | ja | höchstens 200 Zeichen |
recent[].requestedAt | string (date-time) | ja | — |
recent[].finishedAt | string (date-time) | ja | darf null sein |
Antworten: 200, 400, 401, 403, 404, 409, 422, 503, 507
Beispiel
curl -X GET "$ARKVORY_URL/api/v1/system/changes" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Eine Änderung des Standorts einreihen
POST /api/v1/system/changes
Zugriff: Administrator · Wiederholung: Wiederholen ist sicher: Dieselbe Anfrage hat dieselbe Wirkung
Reiht eine Änderung für den Agenten des Standorts ein, der sie innerhalb einer Minute mit den Prüfungen und dem Rollback von arkvory configure und cluster-* anwendet: einen Spiegel oder Import anbinden, seinen Quellschlüssel ersetzen, Spiegel lösen, den aktiven HA-Knoten wechseln (Knotenname zweimal eingegeben) oder Schreibvorgänge mit einer Kopie beschließen. id wählt der Client; eine Wiederholung reiht die Änderung nicht erneut ein. key ist der Quellschlüssel nur für mirror-attach und mirror-key: er geht in einer eigenen 0600-Datei an den Agenten und wird nie zurückgegeben. 202 bedeutet eingereiht, nicht angewendet.
Anfragetext (application/json)
| Feld | Typ | Erforderlich | Regeln |
|---|---|---|---|
id | string (uuid) | ja | — |
change | object | ja | — |
change.kind | string | ja | einer von mirror-attach |
change.repository | string | ja | entspricht ^[a-z0-9][a-z0-9_-]{0,63}$ |
change.upstream | string | ja | höchstens 255 Zeichen |
change.sourceRepository | string | ja | entspricht ^[a-z0-9][a-z0-9_-]{0,63}$ |
change.stages | Array von string | nein | 1–16 Elemente; jedes Element: entspricht ^[a-z0-9][a-z0-9_.-]{0,31}$; darf null sein |
change.repositories | Array von string | ja | 1–64 Elemente; jedes Element: entspricht ^[a-z0-9][a-z0-9_-]{0,63}$ |
change.node | string | ja | entspricht ^[A-Za-z0-9][A-Za-z0-9_.-]{0,62}$ |
change.confirm | string | ja | entspricht ^[A-Za-z0-9][A-Za-z0-9_.-]{0,62}$ |
change.until | string (date-time) | ja | darf null sein |
change.reason | string | ja | 1–200 Zeichen |
key | string | nein | 16–4000 Zeichen |
Antwort 202
| Feld | Typ | Erforderlich | Regeln |
|---|---|---|---|
id | string (uuid) | ja | — |
Antworten: 202, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Beispiel
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>"}}'Änderungsfeed eines Repositorys verfolgen
GET HEAD /api/v1/repositories/{repository}/changes
Zugriff: Repository-Berechtigung: artifact.list; Dateischlüssel: read · Wiederholung: Wiederholen ist sicher (Lesen)
Liefert in Commit-Reihenfolge bis zu limit Änderungen (1–100, Standard 100) nach der Sequenz after (Standard 0): Aktion, Artefakt und, bei Dateipfaden und Stufen, den Pfad oder die Stufe in detail; Akteure werden ausgelassen, daher genügt Listenzugriff. head ist die neueste Sequenz des Repositorys, next der Cursor der folgenden Seite oder null, wenn die Seite den neuesten Stand erreicht hat. Ein Spiegel speichert die zuletzt angewendete Sequenz und fragt von dort aus zyklisch ab.
Parameter
| Name | Ort | Typ | Erforderlich | Regeln |
|---|---|---|---|---|
repository | Pfad | string | ja | entspricht ^[a-z0-9][a-z0-9_-]{0,63}$ |
after | Query | string | nein | eine ganze Zahl in Dezimalziffern, als String gesendet; Sequence cursor, default 0 |
limit | Query | integer | nein | 1–100 |
Antwort 200
| Feld | Typ | Erforderlich | Regeln |
|---|---|---|---|
items | Array von object | ja | — |
items[].sequence | string | ja | eine ganze Zahl in Dezimalziffern, als String gesendet |
items[].action | string | ja | — |
items[].artifactId | string (uuid) | ja | — |
items[].detail | string | ja | darf null sein |
head | string | ja | eine ganze Zahl in Dezimalziffern, als String gesendet |
next | string | ja | eine ganze Zahl in Dezimalziffern, als String gesendet; darf null sein |
Antworten: 200, 400, 401, 403, 404, 409, 422, 503, 507
Beispiel
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/changes" \
-H "Authorization: Bearer $ARKVORY_TOKEN"Download-Link erstellen
POST /api/v1/repositories/{repository}/artifacts/{id}/links
Zugriff: Repository-Berechtigung: content.read; Dateischlüssel: read · Wiederholung: Nicht automatisch wiederholen
Liefert ein geheimes token, eine url relativ zum API-Origin und expiresAt für downloadArtifact genau dieses einen Artefakts ohne Schlüssel; ttlSeconds legt die Lebensdauer fest (60 Sekunden bis ein Tag, Standard eine Stunde). Das Token wird nur in dieser Antwort angezeigt und lässt sich nicht widerrufen: Es funktioniert nicht mehr, wenn es abläuft oder das Artefakt gelöscht wird, und Downloads damit werden auf die Transferlimits des Erstellers angerechnet. Ein Aufrufer darf 1000 aktive Links besitzen (507 token_limit), und ein Download-Link kann keine weiteren Links erstellen.
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/json)
| Feld | Typ | Erforderlich | Regeln |
|---|---|---|---|
ttlSeconds | integer | nein | 60–86400; Standard 3600 |
Antwort 201
| Feld | Typ | Erforderlich | Regeln |
|---|---|---|---|
token | string | ja | entspricht ^dtl_[A-Za-z0-9_-]{43}$ |
url | string | ja | — |
expiresAt | string (date-time) | ja | — |
Antworten: 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
Beispiel
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/links" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'