115 lines
3.2 KiB
Markdown
115 lines
3.2 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
bulk_api
|
|
```
|
|
|
|
Optional kann die Lizenzplattform ein Limit liefern:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
/
|
|
/bulk
|
|
```
|
|
|
|
Sie bietet einen visuellen Mehrfach-Workflow, einen erweiterten JSON-Modus, Ergebnislinks sowie JSON-/CSV-Export. Details stehen in [`BULK-WORKSPACE.md`](BULK-WORKSPACE.md).
|
|
|
|
## Authentifizierung
|
|
|
|
Bei aktivierter API-Key-Pflicht:
|
|
|
|
```http
|
|
Authorization: Bearer <key>
|
|
```
|
|
|
|
oder:
|
|
|
|
```http
|
|
X-API-Key: <key>
|
|
```
|
|
|
|
Der Schlüssel kann über `BULK_API_KEY_FILE` aus einem Container-/Kubernetes-Secret gelesen werden.
|
|
|
|
## Anfrage
|
|
|
|
```http
|
|
POST /v1/bulk/declarations
|
|
Content-Type: application/json
|
|
Authorization: Bearer ...
|
|
```
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```env
|
|
BASE_URL=http://ai-disclosure-bulk
|
|
OUTPUT_BASE_URL=https://ai.example.org
|
|
```
|
|
|
|
Dadurch enthalten Bulk-Ergebnisse nutzbare öffentliche Deklarations-, Manifest- und Badge-URLs.
|