System und Zustand

Liveness, Readiness, Metriken, das OpenAPI-Dokument und die Fähigkeiten des Servers.

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

Detaillierte Bereitschaft prüfen

GET HEAD /health/ready

Zugriff: Jeder gültige Schlüssel oder jede gültige Sitzung · Wiederholung: Wiederholen ist sicher (Lesen)

Antwortet mit ready, wenn Datenbank und Speicher reagieren, und liefert die role dieses Knotens (api oder reader), ob er derzeit Schreibzugriffe annimmt (writable ist auf einem Lese-Gateway false, ebenso solange auf dem Datenträger nur noch die Reserve an freiem Speicherplatz bleibt), den gemeinsamen Download-Slot eines Lese-Gateways sowie aggregierte Zähler für Zulassung und Bandbreite von Uploads und Downloads. Solange der Server herunterfährt (Draining) oder eine Abhängigkeit nicht verfügbar ist, antwortet er mit 503 und Retry-After. Die Anfrage wird nicht auf das Anfragebudget angerechnet; für einen Load Balancer ohne Schlüssel verwenden Sie getReadinessStatus.

Antwort 200

Feld	Typ	Erforderlich	Regeln
role	string	ja	einer von api, reader
sharedDownloads	object	ja	darf null sein
sharedDownloads.slot	integer	ja	mindestens 0
sharedDownloads.slots	integer	ja	mindestens 0
sharedDownloads.active	boolean	ja	—
sharedDownloads.leaseSeconds	integer	ja	mindestens 0
status	string	ja	einer von ready
writable	boolean	ja	—
replication	object	nein	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	—
transfers	object	ja	—
transfers.uploads	object	ja	—
transfers.uploads.admission	object	ja	—
transfers.uploads.bandwidth	object	ja	—
transfers.uploads.sessions	object	nein	—
transfers.downloads	object	ja	—
transfers.downloads.admission	object	ja	—
transfers.downloads.bandwidth	object	ja	—
transfers.downloads.sessions	object	nein	—

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

Beispiel

curl -X GET "$ARKVORY_URL/health/ready" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Serverfähigkeiten und Limits abrufen

GET HEAD /api/v1/capabilities

Zugriff: Jeder gültige Schlüssel oder jede gültige Sitzung · Wiederholung: Wiederholen ist sicher (Lesen)

Liefert die API-Versionen, die Gateway-Rolle, Feature-Flags (zum Beispiel selfRegistration oder mirrorFeed) und die Limits, an die sich ein Client anpasst: das größte Objekt (maxObjectBytes, eine Dezimalzeichenfolge), das kleinste und das größte Multipart-Segment, die größte Anzahl von Teilen und die größte Seitengröße. Lesen Sie sie einmal beim Start eines Clients; sie listet keine Ressourcen auf.

Antwort 200

Feld	Typ	Erforderlich	Regeln
apiVersions	Array von string	ja	—
gatewayRole	string	ja	einer von api, reader
features	Map von boolean	ja	—
limits	object	ja	—
limits.maxObjectBytes	string	nein	eine ganze Zahl in Dezimalziffern, als String gesendet
limits.partBytes	integer	nein	Kleinstes Multipart-Segment.
limits.maxPartBytes	integer	nein	—
limits.maxParts	integer	nein	—
limits.maxPageSize	integer	nein	—

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

Beispiel

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

Bereitschaft für einen Load Balancer prüfen

GET HEAD /health/status

Zugriff: Jeder, ohne Schlüssel · Wiederholung: Wiederholen ist sicher (Lesen)

Benötigt keinen Schlüssel und liefert keine Details: 200 mit {"status":"ready"} oder 503 mit unavailable oder draining und Retry-After. Die Prüfung der Abhängigkeiten wird gemeinsam genutzt und eine Sekunde zwischengespeichert, sodass häufige Probes die Datenbank nicht belasten; die Probe wird nicht auf das Anfragebudget angerechnet.

Antwort 200

Feld	Typ	Erforderlich	Regeln
status	string	ja	einer von ready, unavailable, draining

Antworten: 200, 400, 403, 503

Beispiel

curl -X GET "$ARKVORY_URL/health/status"

Prüfen, ob der Prozess läuft

GET HEAD /health/live

Zugriff: Jeder, ohne Schlüssel · Wiederholung: Wiederholen ist sicher (Lesen)

Liefert 200 mit {"status":"ok"}, solange der Prozess HTTP beantwortet. Es werden keine Abhängigkeiten geprüft; verwenden Sie die Anfrage daher für die Entscheidung über einen Neustart und getReadinessStatus für die Entscheidung über Datenverkehr.

Antwort 200

Feld	Typ	Erforderlich	Regeln
status	string	ja	einer von ok

Antworten: 200, 400, 403, 503

Beispiel

curl -X GET "$ARKVORY_URL/health/live"

OpenAPI-Dokument abrufen

GET HEAD /api/v1/openapi.json

Zugriff: Jeder gültige Schlüssel oder jede gültige Sitzung · Wiederholung: Wiederholen ist sicher (Lesen)

Liefert das OpenAPI-3.0-Dokument dieser Installation mit den Erweiterungen x-arkvory-*, die Zugriffs-, Wiederholungs- und Gateway-Regeln jeder Operation beschreiben. surface (discovery, identity, catalog, transfers, administration oder operations) liefert nur diesen Bereich; ein unbekannter oder wiederholter Query-Parameter ergibt 400. Das Dokument ist für alle Aufrufer gleich und gewährt nichts: Welche Aufrufe diese Anmeldedaten erlauben, ermitteln Sie mit listVisibleOperations.

Parameter

Name	Ort	Typ	Erforderlich	Regeln
surface	Query	string	nein	einer von discovery, identity, catalog, transfers, administration, operations; Documentation view only; not filtered by caller permissions.

Antwort 200

Feld	Typ	Erforderlich	Regeln
openapi	string	ja	einer von 3.0.3
info	object	ja	—
paths	object	ja	—

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

Beispiel

curl -X GET "$ARKVORY_URL/api/v1/openapi.json" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

Prometheus-Metriken abrufen

GET HEAD /health/metrics

Zugriff: Jeder gültige Schlüssel oder jede gültige Sitzung · Wiederholung: Wiederholen ist sicher (Lesen)

Liefert die Prozessmetriken im Prometheus-Textformat (text/plain; version=0.0.4) für einen Scraper. Zähler und Histogramme gehören zu diesem Prozess und beginnen nach einem Neustart bei null (siehe arkvory_process_start_time_seconds); Labels beschränken sich auf Routenvorlage, Methode, Statusklasse und Transferrichtung und nennen nie ein Artefakt, einen Schlüssel oder ein Konto. Der Scrape wird nicht auf das Anfragebudget angerechnet.

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

Beispiel

curl -X GET "$ARKVORY_URL/health/metrics" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -o file

Operationen auflisten, die diese Anmeldedaten aufrufen dürfen

GET HEAD /api/v1/operations

Zugriff: Jeder gültige Schlüssel oder jede gültige Sitzung · Wiederholung: Wiederholen ist sicher (Lesen)

Listet die Operationen dieses Gateways, die die Anmeldedaten aufrufen dürfen, nach operationId geordnet, jeweils mit ihrem Bereich (surface), ihrer Wiederholungsregel, den erforderlichen Aktionen und den conditions, die erst beim Aufruf geprüft werden (etwa resource-state oder upload-owner). repository fügt die Operationen dieses Repositorys hinzu (ein unbekanntes oder fremdes Repository ergibt 404), surface beschränkt die Liste auf einen Bereich; Seiten enthalten limit Einträge (1–100, Standard 50), weiter mit after = next. Die Antwort ist unverbindlich: Erstellen Sie Menüs daraus, aber jede echte Anfrage wird erneut autorisiert, und ein Lese-Gateway listet keine ändernden Methoden.

Parameter

Name	Ort	Typ	Erforderlich	Regeln
repository	Query	string	nein	entspricht ^[a-z0-9][a-z0-9_-]{0,63}$
surface	Query	string	nein	einer von discovery, identity, catalog, transfers, administration, operations
after	Query	string	nein	entspricht ^[A-Za-z][A-Za-z0-9]{0,95}$
limit	Query	integer	nein	1–100; Standard 50

Antwort 200

Feld	Typ	Erforderlich	Regeln
apiVersion	string	ja	einer von v1
documentVersion	string	ja	entspricht ^\d+\.\d+\.\d+$
gatewayRole	string	ja	einer von api, reader
repository	string	ja	entspricht ^[a-z0-9][a-z0-9_-]{0,63}$; darf null sein
advisory	boolean	ja	einer von true
items	Array von object	ja	höchstens 100 Elemente
items[].operationId	string	ja	entspricht ^[A-Za-z][A-Za-z0-9]{0,95}$
items[].method	string	ja	einer von get, head, post, put, patch, delete
items[].path	string	ja	entspricht ^/; höchstens 512 Zeichen
items[].summary	string	ja	höchstens 1024 Zeichen
items[].surface	string	ja	einer von discovery, identity, catalog, transfers, administration, operations
items[].visibility	string	ja	einer von public, authenticated, self, repository, owned-resource, delegated, bootstrap, administrator
items[].retry	string	ja	einer von read, never-automatic, idempotent, idempotency-key, compare-and-swap, reconcile-upload, reconcile-job
items[].requiredActions	Array von string	ja	höchstens 33 Elemente; keine wiederholten Elemente; jedes Element: einer von repository.read, storage.read, storage.manage, diagnostics.read, artifact.read, artifact.list, artifact.delete, artifact.promote, content.read, upload.create, upload.read, upload.write, upload.complete, upload.cancel, job.read, package.read, package.publish, asset.read, asset.write, asset.restore, annotation.read, annotation.write, reference.write, audit.read, service-account.read, service-account.manage, policy.read, policy.manage, credential.read, credential.manage, service-audit.read, backup.read, backup.manage
items[].conditions	Array von string	ja	höchstens 6 Elemente; keine wiederholten Elemente; jedes Element: einer von resource-state, upload-owner, job-owner, reference-owner, delegation-target-and-ceiling, own-key
next	string	ja	entspricht ^[A-Za-z][A-Za-z0-9]{0,95}$; darf null sein

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

Beispiel

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