JavaScript-Client-Bibliothek - Octoparse Docs

octoparse-client ist der offizielle JavaScript/TypeScript-Client für Data Hub. Er kapselt nur die öffentliche /v1 REST API. Methoden entsprechen eins zu eins den Endpoints, Parameternamen stimmen mit REST überein, und Rückgabewerte sind der rohe data-Payload. Erfordert Node.js 18+ oder eine moderne Browser-Laufzeit mit fetch.

Installation

npm install octoparse-client

Initialisierung

import { Client } from "octoparse-client";

const client = new Client({ apiKey: "<your API key>" });

Option	Beschreibung
`apiKey`	Data Hub API-Schlüssel. Ohne Angabe wird `OCTOPARSE_API_KEY` gelesen. Fehlt er weiterhin, ist der Client anonym und kann nur anonyme Endpoints aufrufen.
`baseUrl`	Service-URL. Ohne Angabe wird `OCTOPARSE_BASE_URL` gelesen, Standard ist `https://api-datahub.octoparse.com`. Für lokale oder Staging-Umgebungen explizit übergeben.
`timeout`	Per-request HTTP timeout in Millisekunden. Standard 90000.

Methoden-zu-Endpoint-Zuordnung

Methode	Endpoint	Hinweise
`meta()`	`GET /v1/meta`	Plattform-Konstanten
`search(q, { limit, offset, ... })`	`GET /v1/data-apps`	Eine Seite Karten, inkl. `pagination`
`getApp(appId)`	`GET /v1/data-apps/{app_id}`	Vollständiges App-Detail
`run(appId, inputs, { wait, maxRecords, version, build })`	`POST /v1/data-apps/{app_id}/runs`	Run starten
`call(appId, inputs, { maxRecords, timeout, raiseOnFailure, ... })`	`POST` + Poll	Blocking-Helper: warten bis terminal oder Timeout
`getRun(runId, { wait })`	`GET /v1/runs/{run_id}`	Status- und Abrechnungs-Snapshot
`listRunsPage(filters)`	`GET /v1/runs`	Eine Seite Runs, inkl. `pagination`
`listRuns(filters)`	`GET /v1/runs`	Eine Seite Runs, nur Items
`iterateRuns(filters)`	`GET /v1/runs`	Async-Iterator, der automatisch paginiert
`cancel(runId)`	`POST /v1/runs/{run_id}/cancel`	Run abbrechen
`getRecords(runId, { offset, limit, fields })`	`GET /v1/runs/{run_id}/records`	Eine Seite Ergebnisdatensätze
`iterateRecords(runId, { batch, fields })`	`GET /v1/runs/{run_id}/records`	Async-Iterator, der automatisch paginiert
`exportRecords(runId, format)`	`GET /v1/runs/{run_id}/records`	Voller Export als `jsonl`/`csv`-Text
`listDatasets({ offset, limit })`	`GET /v1/datasets`	Dataset-Liste
`setDatasetRetention(datasetId, retained)`	`PUT /v1/datasets/{dataset_id}/retention`	Retention-Flag setzen
`getDatasetRecords(datasetId, { offset, limit, fields })`	`GET /v1/datasets/{dataset_id}/records`	Eine Seite Dataset-Datensätze
`iterateDatasetRecords(datasetId, { batch, fields })`	`GET /v1/datasets/{dataset_id}/records`	Async-Iterator, der automatisch paginiert
`account()`	`GET /v1/account`	Kontoinfo und kumulierter Spend
`billing({ groupBy, createdFrom, createdTo, tzOffset })`	`GET /v1/billing`	Abrechnungsaggregation

Die filters der Run-Liste unterstützen status, dataApp, triggeredBy, runKind, credential, createdFrom, createdTo sowie offset / limit. Publishing-, Betriebs- und Secrets-Endpoints sind nicht gekapselt; rufen Sie REST direkt auf.

Typische Verwendung

import { Client, ApiError, RunFailed } from "octoparse-client";

const client = new Client({ apiKey: "<your API key>" });

// Discover
const { items } = await client.search("reviews", { limit: 5 });
for (const card of items) console.log(card.app_id, card.namespace, card.app_name);
const detail = await client.getApp("carol/reviews-query");

// Run and consume. Timeouts are milliseconds. TimeoutError does not cancel the server-side run.
const run = await client.call("carol/reviews-query", { product: "p-9001" }, {
  maxRecords: 100, timeout: 120_000, raiseOnFailure: true,
});
for await (const record of client.iterateRecords(run.run_id)) {
  console.log(record);
}

// Non-blocking: start, then poll yourself
const started = await client.run("carol/reviews-query", { product: "p-9002" }, { wait: 0 });
const polled = await client.getRun(started.run_id, { wait: 60 });

// Reconcile spend
console.log(await client.billing({ groupBy: "data_app", tzOffset: 480 }));
for await (const r of client.iterateRuns({ createdFrom: "2026-09-01T00:00:00+08:00" })) {
  console.log(r.run_id, r.status, r.billing.total);
}

// Results are kept 90 days by default; mark datasets you need longer
await client.setDatasetRetention(run.dataset_id, true);

Fehlerbehandlung

API-Fehlerantworten werfen ApiError (erweitert Error). Die Felder entsprechen dem REST-error-Objekt:

Eigenschaft	Bedeutung
`statusCode`	HTTP-Status
`code`	Stabile Fehler-ID für Verzweigungen
`category`	Grobe Fehlerklasse
`message`	Englische Beschreibung
`retryable`	Ob dieselbe Anfrage erneut versucht werden kann
`details`	Probleme auf Feldebene bei fehlgeschlagener Eingabevalidierung, sonst `undefined`

import { ApiError } from "octoparse-client";

try {
  await client.run("carol/reviews-query", {});
} catch (e) {
  if (e instanceof ApiError && e.code === "invalid-input") {
    for (const d of e.details ?? []) console.log(d.path, d.message);
  } else if (e instanceof ApiError && e.retryable) {
    // back off and retry
  } else {
    throw e;
  }
}

RunFailed wird geworfen, wenn call() mit raiseOnFailure: true aufgerufen wird und der Run mit FAILED / CANCELLED / EXPIRED endet. Die Eigenschaft run enthält das vollständige Run-Objekt.

App-Referenzen

getApp(), run(), call() und der Run-List-Filter dataApp akzeptieren beide Formen: zweisegmentig <namespace>/<app_name> (menschenlesbar, bricht nach Rename) und stabiles app_id (app_<hex>, überlebt Rename). Für langlebige Integrationen app_id speichern.