S3-Kundenverwaltung, Nutzung und Abrechnung per REST API

Die administrative REST API stellt Kundenspeicher bereit, verwaltet Quotas und Preise und liefert Nutzungs- und Abrechnungsberichte. Für Änderungen benötigen Sie admin oder s3-admin. read-only kann Berichte und Trackingstatus lesen. Die API ist kein Kunden-Self-Service-Portal. Ihre Nutzung erfolgt in eigener Verantwortung und ist nicht durch den Support abgedeckt.

Anfragen und Endpunkte

Der Präfix aller hier genannten Endpunkte ist /api/v1/object-storage. Verwenden Sie HTTPS und X-API-Key. Metadaten und Abrechnungsoptionen können als URL-Parameter mit --data-urlencode gesendet werden. Geheimnisse gehören ausschließlich in JSON-Anfragekörper. Für wiederholbare Änderungen verwenden Sie denselben Idempotency-Key und dieselbe Anfrage; ein neuer Vorgang benötigt einen neuen Schlüssel. Die wiederholte Bereitstellungsantwort kann erneut Zugangsdaten enthalten und muss geschützt werden.

Operation	Zweck
GET /customers	Kundenliste; optional ein vollständiges Paar von Abrechnungsdaten.
POST /customers	Kunde, S3-Benutzer, Bucket und Quota anlegen.
PATCH /customers	Metadaten, Quota und Preise ändern.
DELETE /customers	Registrierung entfernen; mit ausdrücklichem Purge auch Daten und Benutzer löschen.
POST /customers/adopt	Vorhandenen replizierten oder wiederhergestellten Benutzer und Bucket registrieren.
POST /customers/usage	Speichernutzung erfassen und Traffic sammeln.
GET /traffic, POST /traffic, POST /traffic/collect	Trackingzustand lesen, Tracking aktivieren und Traffic-Zähler sammeln.
GET /billing, GET /billing/export, GET /billing/users	Kundenbericht, CSV-Inhalt und Zusammenfassung nach UID/Standort.
GET/POST /billing/federation, POST /billing/federation/report	Standortübergreifende Abrechnung konfigurieren und Bericht erstellen.

Kunden anlegen und ändern

Für die Erstellung sind customer_id, customer_name und eine positive ganzzahlige quota_gb erforderlich. Optionale Felder umfassen Kundennummer, E-Mail, Standort, Bucket, service_type (s3 oder s3_nextcloud), Währung, Speicherpreis, Mindestbetrag und Abrechnungsstatus. Traffic-Optionen heißen charge_uploads, charge_downloads, upload_price_per_gb und download_price_per_gb. Boolesche Parameter verwenden true/false; Preise müssen nichtnegativ sein.

Standard ist EUR; Speicher- und Traffic-Preise sind zunächst null. Bei Ceph ist Upload-Abrechnung standardmäßig aus, Download-Abrechnung an. Tracking und Preise werden separat konfiguriert. Ohne Standortangabe gilt der Standardstandort; ohne Bucketangabe wird ein Kundenbucket erzeugt.

curl --cacert /pfad/ca.pem -X POST --get \
  --header 'X-API-Key: <API_KEY>' \
  --header 'Idempotency-Key: <REQUEST_ID>' \
  --data-urlencode 'customer_id=example-001' \
  --data-urlencode 'customer_name=Beispielkunde' \
  --data-urlencode 'quota_gb=100' \
  --data-urlencode 'price_per_gb=0.20' \
  --data-urlencode 'minimum_charge=5' \
  'https://eekas.example.com:18443/api/v1/object-storage/customers'

Die Erstellung liefert status, customer und credentials mit access_key und secret_key. Sichern Sie diese Antwort geschützt. Kundenlisten liefern das Secret nicht. Objektzugriffe verwenden den separat konfigurierten S3-Endpunkt und nicht den Verwaltungsport.

PATCH benötigt customer_id; Standort und Bucket werden darüber nicht geändert. Weggelassene Felder bleiben erhalten. Zum Abschalten eines Preises setzen Sie ausdrücklich 0, zum Abschalten einer Option false. Eine Quota-Änderung aktualisiert die tatsächliche Bucket-Quota. Prüfen Sie GET /api/v1/object-storage/quotas?quota_scope=bucket&bucket=<BUCKET> und data.bucket_quota.enabled sowie max_size in Bytes.

active und suspended sind abrechenbar. trial, cancelled und do_not_bill ergeben keine Gebühren. Diese Abrechnungszustände sperren den S3-Zugriff nicht. Aktuelle Preise und Zustände verändern auch historische Berichte; bewahren Sie genehmigte Exporte auf.

Für das Entfernen einer Registrierung geben Sie purge_data=false ausdrücklich an. purge_data=true löscht zusätzlich Kundendaten und S3-Benutzer. Eine erneut angelegte Kunden-ID erhält eine neue Generation und übernimmt nicht den früheren Speicherpeak.

Vorhandene Kunden nach Replikation oder Wiederherstellung übernehmen

POST /customers/adopt registriert vorhandene Daten, ohne Benutzer, Schlüssel oder Quota neu anzulegen. Pflichtangaben sind customer_id, customer_name, quota_gb, site, bucket und uid. Der bestehende Bucketeigentümer muss zur UID passen. Übernehmen Sie bei Bedarf die Metadaten des Primärstandorts einschließlich Preise, generation_id und created_at.

quota_gb dokumentiert bei der Übernahme die vereinbarte bestehende Quota und ändert deren Durchsetzung nicht. Eine spätere ausdrückliche PATCH-Anfrage kann sie ändern. Bei übernommenen Registrierungen wird ohne Purge nur der Kundenbezug entfernt. Kundenregister, Tarife und historische Abrechnungsdaten werden durch Objektreplikation nicht automatisch kopiert.

Traffic aktivieren und erfassen

POST /traffic benötigt site und kann Gateways neu starten. HTTP 202 bestätigt die Einplanung; fragen Sie GET /traffic ab, bis der Standort active oder error meldet. Prüfen Sie message und warnings. Zustände sind disabled, enabling, active und error. start und last_collected sind Unix-Zeitwerte; null Sekunden bedeuten keine erfasste Grenze beziehungsweise Sammlung.

Tracking und Traffic-Abrechnung neu registrierter Kunden beginnen an der nächsten vollen UTC-Stunde. Frühere Übertragungen werden nicht nachträglich berechnet. Eine erneute Aktivierung eines aktiven Standorts behält die ursprüngliche Grenze. Gezählt werden S3-Anfrage- und Antwortbytes der Gateways einschließlich unterstützter fehlgeschlagener Operationen; die Zähler sind keine Messung aller Netzwerk- oder WAN-Bytes.

POST /traffic/collect sammelt alle oder einen ausgewählten Standort. Wiederholungen zählen Bytes nicht doppelt. Bei einer gleichzeitig laufenden Sammlung warten Sie und versuchen es später erneut. Neueste Stunden sind während der Protokollübertragung vorläufig; historisches Nachholen kann mehrere Läufe benötigen. Der Fünf-Minuten-Timer erfasst Traffic und keine Speicherpeaks. Das Abschalten des Trackings oder Löschen geschützter Nutzungsprotokolle ist absichtlich nicht vorgesehen.

Speicher erfassen und Berichte prüfen

POST /customers/usage erstellt Speicher-Snapshots und sammelt Traffic. Prüfen Sie error_count, errors und traffic_error auch bei HTTP 200. Planen Sie Speichererfassung separat in der benötigten Häufigkeit; zwischen Snapshots erstellte und gelöschte Daten können im gemessenen Peak fehlen.

Berichte benötigen period_start und period_end als YYYY-MM-DD, einschließlich beider Tage in UTC. Beginn darf nicht nach Ende liegen. Die Kundenliste akzeptiert entweder keine oder beide Datumsangaben. Kundenberichte unterstützen customer_id und uid; die UID-Zusammenfassung unterstützt uid.

Ein als GB bezeichneter Wert entspricht 1.073.741.824 Bytes (GiB). Für abrechenbare Kunden gilt:

storage_amount = max(sampled_peak_GB * price_per_gb, minimum_charge)
amount = storage_amount + upload_amount + download_amount

Jede Geldkomponente wird auf drei Dezimalstellen gerundet. Der Mindestbetrag gilt nur für Speicher. Ein mehrmonatiger Bereich verwendet einen Peak und einen Mindestbetrag; er ist nicht die Summe einzelner Monatsabrechnungen. Quota, aktuelle Nutzung und Zeitraumpeak sind unterschiedliche Werte.

Prüfen Sie traffic_coverage und traffic_warning. Abdeckung kann unvollständig, vorläufig, veraltet oder nicht verfügbar sein. Fehlende Zähler mit null bedeuten nicht null Verbrauch. traffic_start_at und traffic_collected_at liefern verfügbare UTC-Zeitstempel. actual_used_gb im Bericht ist der Zeitraumpeak; latest_used_gb in der Kundenliste ist der neueste Snapshot. Summieren Sie unterschiedliche Währungen nicht ungeprüft.

/billing/export liefert JSON mit csv und filename; /billing/users liefert zusätzlich summary. Schreiben Sie den Inhalt von csv in eine Datei. Der HTTP-Antwortkörper ist kein roher CSV-Download.

Standortübergreifende Abrechnung

Die Zusammenführung ist ausdrücklich zu konfigurieren. Registrieren Sie replizierte Kunden zunächst mit /customers/adopt. POST /billing/federation verwendet ein JSON-Objekt request mit peers und groups. Peers benötigen ID, HTTPS-Adresse und API-Schlüssel; Gruppen verbinden einen logischen Benutzer/Bucket über unterschiedliche Abrechnungszonen und benennen einen Preisverantwortlichen über owner sowie die members.

Peer-Schlüssel bleiben in geschützter Speicherung und werden aus Antworten entfernt. Ein weggelassener Schlüssel bleibt nur bei unveränderter Peer-ID und Herkunft erhalten. TLS-Prüfung ist verpflichtend; verwenden Sie ca_pem für private CAs. Weiterleitungen werden abgewiesen.

POST /billing/federation/report erhält {"request":{"period_start":"2026-09-01","period_end":"2026-09-30"}}. Der Bericht berechnet den höchsten logischen Speicherpeak einmal, addiert Traffic unterschiedlicher Zonen und verwendet Preise und Zustand des Preisverantwortlichen. Summen bleiben nach Währung getrennt. Nicht erreichbare Peers oder doppelte Abrechnungszonen führen zum Fehler. Fehlende Zähler liefern null-Beträge; vorläufige beziehungsweise unvollständige Abdeckung bleibt sichtbar.

Ein erreichbarer Peer bedeutet keinen endgültigen Trafficstand. Es gibt keinen automatischen Abrechnungs-Failover und keinen automatischen Rechnungsabschluss. Sichern Sie Kundenexporte und freigegebene Berichte außerhalb der Primärinstallation. Ein Wechsel des Preisverantwortlichen nach einem Ausfall erfordert Prüfung; die Wiederherstellung von Objekten rekonstruiert kein verlorenes Abrechnungsjournal.

Interne Sicherungsübertragungen und Zugriffsprotokolle

Verwaltete Archivlesevorgänge verwenden Systemkonten und werden aus den kundenseitigen Gateway-Nutzungsprotokollen ausgeschlossen. Selbst übergebene Quellzugangsdaten müssen Systemzugangsdaten sein; Kundenschlüssel werden dafür abgewiesen. Native Synchronisierung verwendet ebenfalls Systemanfragen.

Das Ziel rechnet externe Uploads und Wiederherstellungsvorgänge nach seiner eigenen Konfiguration ab. Ist dort ein Bucket einem Abrechnungskunden zugeordnet und werden normale Kundenzugangsdaten verwendet, können Übertragungen berechnet werden. Der Ausschluss interner Quelllesevorgänge deaktiviert die Zielabrechnung nicht.

GET /access-logs liest Protokollstufe, Aufbewahrung und Dienstzustand. POST /access-logs verwendet level=off/standard/detailed, retention_days und optional site und kann Gateways neu starten. GET /access-logs/export akzeptiert days=0/1/7/30/90/365 (Standard 7) und liefert JSON-Inhalte mit Dateiname und MIME-Typ. POST /access-logs/clear benötigt confirm=clear-access-logs; notwendige Abrechnungsprotokolle bleiben geschützt. Der ältere Endpunkt /usage ist eine Rohansicht; verwenden Sie für eine Bewertung der Abdeckung Traffic- und Billing-Endpunkte.

Einrichtung und Referenz

Beginnen Sie mit REST API – Einstieg und Automatisierung. Die API-Referenz enthält die vollständigen Parameter. Beachten Sie außerdem S3-Replikation, Sicherung und Wiederherstellung per REST API.