OlostepのAPIはオブジェクトを中心に設計されています。この設計を理解することで、より効果的な統合を構築できます。
すべてはオブジェクト
Olostepのすべてのリソースは、ユニークな識別子を持つオブジェクトです。API、SDK、またはダッシュボードを介して作成する場合でも、参照、更新、クエリが可能なオブジェクトが返されます。
| リソース | オブジェクトID形式 | 例 |
|---|
| 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 |
オブジェクトにはライフサイクルがある
一部のOlostepオブジェクトは、statusフィールドを通じて状態を追跡します。この状態機械パターンにより、各リソースがライフサイクルのどこにあるかを正確に知ることができます。
バッチ
バッチには、バッチ自体と個々のアイテムの2つのステータスレベルがあります。
バッチステータス:
| ステータス | 説明 |
|---|
in_progress | URLがスクレイプされています |
completed | 処理が完了しました |
バッチレベルの失敗は非常に稀です。 バッチはほぼ必ず完了します — 一部のURLが失敗しても、バッチ自体はcompletedステータスに達します。壊滅的なインフラストラクチャの失敗（例：エンリッチメント中のLLMサービスの停止）の場合にのみ、バッチが失敗することがあります。これはバッチの0.01%未満に影響します。
| ステータス | 説明 |
|---|
success | URLが正常にスクレイプされました |
failed | URLをスクレイプできませんでした |
- URLがブロックされているかエラーを返す
- パーサーの出力が欠落している
- ネットワーク/フェッチエラー
失敗したアイテムには、失敗を説明するcodeとmessageを含むerrorオブジェクトが含まれます。バッチは依然として完了します — 結果を処理する際に各アイテムのステータスを確認してください。
クローラー
| ステータス | 説明 |
|---|
in_progress | URLを積極的に発見および処理しています |
completed | クロールが完了しました |
クローラーは常に完了します。 たとえクロールが0 URLを発見した場合（robots.txtによるブロックや無効な開始URLのため）、クロールステータスはcompletedになります。結果を確認するにはpages_countフィールドを確認してください。
モニター
モニターは、ワンショットリソースよりも豊富なライフサイクルを持つ長寿命のオブジェクトです：
provisioning → active ⇄ paused
↘ failed
| ステータス | 説明 |
|---|
provisioning | エージェント、仕様、プランナー、およびスケジュールが設定されています |
active | スケジュールが有効になり、schedule.frequencyで実行されます |
paused | POST /v1/monitors/:monitor_id/pauseでスケジュールが無効化されます |
failed | プロビジョニングまたはスケジュール更新に失敗しました（error_messageが設定されます） |
deleted | DELETE /v1/monitors/:monitor_idでソフト削除されます |
202がstatus: provisioningで返されます。モニターは、計画が追跡対象を解決するとactiveになります — GET /v1/monitors/:monitor_idをポーリングするか、?stream=1でプロビジョニングイベントをストリーミングします。activeなモニターのみが一時停止でき、pausedなモニターのみが再開できます。更新はモニターがまだprovisioning中の場合、409を返します。
リトリーブパターン
多くのオブジェクトは、後で取得できるコンテンツを生成します。retrieve_idパターンを使用すると、再処理せずにコンテンツを取得できます。
# retrieve_idを使用してコンテンツを取得
curl "https://api.olostep.com/v1/retrieve?retrieve_id=6h89o8u1kt" \
-H "Authorization: Bearer <your_token>"
- バッチアイテム — 処理された各URLに
retrieve_idが付与されます
- クロールページ — クロールされた各ページに
retrieve_idが付与されます
/v1/retrieveエンドポイントは、返すコンテンツタイプを指定するformatsパラメータを受け入れます（html、markdown、json、text）。
Webhooks: イベント駆動型の更新
状態の変化をポーリングする代わりに、オブジェクトの状態が変化したときにイベントを受け取るようにwebhooksを設定してください。
{
"event": "batch.completed",
"data": {
"id": "batch_xyz789",
"status": "completed",
"items_total": 100,
"items_completed": 100
}
}
メタデータ: あなたのデータを私たちのデータと一緒に
metadataを使用して、オブジェクトにカスタムのキーと値のペアを添付します。これにより、Olostepリソースを内部システムにリンクできます。
{
"items": [{"url": "https://example.com"}],
"metadata": {
"order_id": "12345",
"customer": "acme-corp"
}
}
まとめ
| コンセプト | 説明 |
|---|
| オブジェクト | すべてのリソースにはユニークなIDがあり、クエリ可能です |
| ライフサイクル | statusフィールドを通じて進行状況を追跡 |
| リトリーブ | retrieve_idで後でコンテンツを取得 |
| Webhooks | 状態が変化したときに通知を受け取る |
| メタデータ | 任意のオブジェクトに独自のデータを添付 |
