Die API von Olostep ist objektorientiert gestaltet. Dieses Design zu verstehen, hilft dir, effektivere Integrationen zu entwickeln.
Alles ist ein Objekt
Jede Ressource in Olostep ist ein Objekt mit einer eindeutigen Kennung. Egal, ob du es über die API, das SDK oder das Dashboard erstellst – du erhältst ein Objekt, auf das du verweisen, das du aktualisieren und abfragen kannst.
| Ressource | Objekt-ID-Format | Beispiel |
|---|
| Scrape | scrape_* | scrape_abc123 |
| Batch | batch_* | batch_xyz789 |
| Crawl | crawl_* | crawl_def456 |
| Map | map_* | map_ghi012 |
| Answer | answer_* | answer_jkl345 |
| Search | search_* | search_mno678 |
| Monitor | monitor_* | monitor_mno678 |
| File | file_* | file_mno678 |
| Schedule | schedule_* | schedule_pqr901 |
Objekte können Lebenszyklen haben
Einige Olostep-Objekte verfolgen den Status über ein status-Feld. Dieses Zustandsmaschinenmuster ermöglicht es dir, genau zu wissen, wo sich jede Ressource in ihrem Lebenszyklus befindet.
Batches
Batches haben zwei Status-Ebenen: den Batch selbst und die einzelnen Items.
Batch-Status:
| Status | Beschreibung |
|---|
in_progress | URLs werden gescraped |
completed | Verarbeitung abgeschlossen |
Batch-Fehler sind extrem selten. Batches werden fast immer abgeschlossen – selbst wenn einige URLs fehlschlagen, erreicht der Batch selbst den Status completed. Im seltenen Fall eines katastrophalen Infrastrukturfehlers (z.B. LLM-Dienstunterbrechung während der Anreicherung) kann der Batch fehlschlagen. Dies betrifft weniger als 0,01% der Batches.
| Status | Beschreibung |
|---|
success | URL erfolgreich gescraped |
failed | URL konnte nicht gescraped werden |
- URL ist blockiert oder gibt einen Fehler zurück
- Parser-Ausgabe fehlt
- Netzwerk-/Abruffehler
Fehlgeschlagene Items enthalten ein error-Objekt mit code und message, die den Fehler erklären. Der Batch wird trotzdem abgeschlossen – überprüfe den Status jedes Items bei der Verarbeitung der Ergebnisse.
Crawls
| Status | Beschreibung |
|---|
in_progress | URLs werden aktiv entdeckt und verarbeitet |
completed | Crawlen abgeschlossen |
Crawls werden immer abgeschlossen. Selbst wenn ein Crawl 0 URLs findet (aufgrund von robots.txt-Blockierung oder ungültiger Start-URL), wird der Crawl-Status completed sein. Überprüfe das pages_count-Feld, um die Ergebnisse zu verifizieren.
Monitore
Monitore sind langlebige Objekte mit einem reicheren Lebenszyklus als einmalige Ressourcen:
provisioning → active ⇄ paused
↘ failed
| Status | Beschreibung |
|---|
provisioning | Agent, Spezifikation, Planer und Zeitplan werden eingerichtet |
active | Zeitplan aktiviert; Läufe werden gemäß schedule.frequency ausgeführt |
paused | Zeitplan über POST /v1/monitors/:monitor_id/pause deaktiviert |
failed | Bereitstellung oder Zeitplanaktualisierung fehlgeschlagen (error_message ist gesetzt) |
deleted | Soft-gelöscht über DELETE /v1/monitors/:monitor_id |
202 mit status: provisioning zurück. Der Monitor wird active, sobald die Planung seine verfolgten Ziele löst – poll GET /v1/monitors/:monitor_id oder streame Bereitstellungsereignisse mit ?stream=1. Nur active Monitore können pausiert werden, und nur paused Monitore können fortgesetzt werden. Updates geben 409 zurück, während der Monitor noch provisioning ist.
Retrieve-Muster
Viele Objekte erzeugen Inhalte, die später abgerufen werden können. Das retrieve_id-Muster ermöglicht es dir, Inhalte abzurufen, ohne sie erneut zu verarbeiten.
# Inhalte mit retrieve_id abrufen
curl "https://api.olostep.com/v1/retrieve?retrieve_id=6h89o8u1kt" \
-H "Authorization: Bearer <your_token>"
- Batch-Items — Jede verarbeitete URL erhält eine
retrieve_id
- Crawl-Seiten — Jede gecrawlte Seite erhält eine
retrieve_id
Der /v1/retrieve-Endpunkt akzeptiert den formats-Parameter, um anzugeben, welche Inhaltstypen zurückgegeben werden sollen (html, markdown, json, text).
Webhooks: Ereignisgesteuerte Aktualisierungen
Anstatt auf Statusänderungen zu warten, konfiguriere Webhooks, um Ereignisse zu erhalten, wenn Objekte ihren Zustand ändern.
{
"event": "batch.completed",
"data": {
"id": "batch_xyz789",
"status": "completed",
"items_total": 100,
"items_completed": 100
}
}
Füge benutzerdefinierte Schlüssel-Wert-Paare zu Objekten hinzu, indem du Metadaten verwendest. Dies ermöglicht es dir, Olostep-Ressourcen mit deinen internen Systemen zu verknüpfen.
{
"items": [{"url": "https://example.com"}],
"metadata": {
"order_id": "12345",
"customer": "acme-corp"
}
}
Zusammenfassung
| Konzept | Beschreibung |
|---|
| Objekte | Jede Ressource hat eine eindeutige ID und ist abfragbar |
| Lebenszyklen | Fortschritt über das status-Feld verfolgen |
| Retrieve | Inhalte später mit retrieve_id abrufen |
| Webhooks | Benachrichtigungen bei Zustandsänderungen erhalten |
| Metadaten | Eigene Daten an jedes Objekt anhängen |
