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フィールドを通じて状態を追跡します。この状態機械パターンにより、各リソースがライフサイクルのどこにあるかを正確に把握できます。
Batches
バッチには、バッチ自体と個々のアイテムの2つのステータスレベルがあります。
バッチステータス:
| ステータス | 説明 |
|---|
in_progress | URLがスクレイプされています |
completed | 処理が完了しました |
バッチレベルの失敗は非常に稀です。 バッチはほぼ常に完了します。いくつかのURLが失敗しても、バッチ自体はcompletedステータスに達します。大規模なインフラ障害（例：エンリッチメント中のLLMサービスの停止）の場合、バッチが失敗することがあります。これはバッチの0.01%未満に影響します。
| ステータス | 説明 |
|---|
success | URLが正常にスクレイプされました |
failed | URLをスクレイプできませんでした |
- URLがブロックされているかエラーを返す
- パーサーの出力が欠落している
- ネットワーク/フェッチエラー
失敗したアイテムには、失敗を説明するcodeとmessageを含むerrorオブジェクトが含まれています。バッチは完了しますが、結果を処理する際に各アイテムのステータスを確認してください。
Crawls
| ステータス | 説明 |
|---|
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
}
}
メタデータ: あなたのデータを私たちのデータと共に
metadataを使用して、オブジェクトにカスタムのキーと値のペアを添付します。これにより、Olostepリソースを内部システムにリンクできます。
{
"items": [{"url": "https://example.com"}],
"metadata": {
"order_id": "12345",
"customer": "acme-corp"
}
}
まとめ
| コンセプト | 説明 |
|---|
| オブジェクト | すべてのリソースはユニークなIDを持ち、クエリ可能 |
| ライフサイクル | statusフィールドを通じて進捗を追跡 |
| リトリーブ | retrieve_idで後でコンテンツを取得 |
| Webhooks | 状態が変わったときに通知を受け取る |
| メタデータ | 任意のオブジェクトに独自のデータを添付 |
