Bulk API

Der Bulk-Dienst ist für Publisher, CMS-Integrationen, Agenturen und andere professionelle Workflows gedacht. Er stellt sowohl eine browserbasierte Bulk Workspace als auch die serverseitige API bereit.

Capability

Die Runtime-Lizenz benötigt:

bulk_api

Optional kann die Lizenzplattform ein Limit liefern:

bulk_items=250

Der effektive Grenzwert ist der kleinere Wert aus Lizenzlimit und BULK_MAX_ITEMS.

Dedizierter Container

Dockerfile.bulk verwendet dasselbe getestete Go-Binary, setzt aber sichere Betriebsdefaults:

SERVICE_MODE=bulk
REQUIRE_LICENSE=true
BULK_REQUIRE_API_KEY=true
API_ALLOWED_ORIGIN=

Der dedizierte Modus enthält bewusst keine öffentliche Generator-, Produkt- oder Hintergrundseite, stellt aber die spezialisierte Bulk Workspace unter / und /bulk bereit. Die eigentliche Verarbeitung erfolgt weiterhin über denselben authentifizierten API-Endpunkt.

Bulk Workspace

Die browserbasierte Oberfläche ist erreichbar unter:

/
/bulk

Sie bietet einen visuellen Mehrfach-Workflow, einen erweiterten JSON-Modus, Ergebnislinks sowie JSON-/CSV-Export. Details stehen in BULK-WORKSPACE.md.

Authentifizierung

Bei aktivierter API-Key-Pflicht:

Authorization: Bearer <key>

oder:

X-API-Key: <key>

Der Schlüssel kann über BULK_API_KEY_FILE aus einem Container-/Kubernetes-Secret gelesen werden.

Anfrage

POST /v1/bulk/declarations
Content-Type: application/json
Authorization: Bearer ...

{
  "items": [
    {
      "id": "post-1001",
      "parameters": {
        "mode": "article",
        "lang": "de",
        "textExtent": "none",
        "textReview": "none",
        "coverImageExtent": "full",
        "coverImageReview": "editorial",
        "researchExtent": "assisted",
        "researchReview": "expert",
        "assurance": "technicallyRecorded"
      }
    }
  ]
}

Jedes Element wird unabhängig verarbeitet. Ein fachlich fehlerhaftes Element führt zu einem Item-Fehler, ohne die übrigen Elemente zu verwerfen.

Betriebsgrenzen

BULK_MAX_ITEMS begrenzt Items pro Request;
BULK_MAX_BODY_BYTES begrenzt die Requestgröße;
ein Lizenzlimit bulk_items kann die Itemzahl weiter reduzieren;
der Dedicated Container wird ohne gültige bulk_api-Capability nicht ready;
bei REQUIRE_LICENSE=true werden fachliche Requests ohne gültige Runtime-Lizenz mit 503 blockiert;
Prometheus exportiert Bulk-Request-, Item- und Failure-Counter.

Netzwerk

Der Bulk-Service sollte standardmäßig intern betrieben werden. Die Kubernetes-Vorlage liefert nur einen ClusterIP-Service und bewusst keinen Ingress. Bei externer Veröffentlichung empfiehlt sich zusätzlich ein API-Gateway mit TLS, Rate-Limiting und organisationsspezifischer Authentifizierung.

Getrennte Runtime- und Ausgabe-URL

Bei einer separaten Bulk-Instanz kann BASE_URL die interne bzw. lizenzgebundene Adresse des Bulk-Dienstes sein, während OUTPUT_BASE_URL auf die öffentliche Full-/API-Instanz zeigt:

BASE_URL=http://ai-disclosure-bulk
OUTPUT_BASE_URL=https://ai.example.org

Dadurch enthalten Bulk-Ergebnisse nutzbare öffentliche Deklarations-, Manifest- und Badge-URLs.

3.2 KiB Raw Permalink Blame History