OlostepのAPIはオブジェクトを中心に設計されています。この設計を理解することで、より効果的な統合を構築することができます。この設計はStripeの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 |
| 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フィールドをチェックしてください。
リトリーブパターン
多くのオブジェクトは後で取得できるコンテンツを生成します。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
}
}
メタデータ: あなたのデータを私たちのデータと一緒に
メタデータを使用してオブジェクトにカスタムのキーと値のペアを添付します。これにより、Olostepリソースを内部システムにリンクできます。
{
"items": [{"url": "https://example.com"}],
"metadata": {
"order_id": "12345",
"customer": "acme-corp"
}
}
まとめ
| 概念 | 説明 |
|---|
| オブジェクト | すべてのリソースはユニークなIDを持ち、クエリ可能です |
| ライフサイクル | statusフィールドを通じて進捗を追跡 |
| リトリーブ | retrieve_idで後でコンテンツを取得 |
| Webhooks | 状態が変わったときに通知を受け取る |
| メタデータ | 任意のオブジェクトに独自のデータを添付 |
