メインコンテンツへスキップ
OlostepのAPIはオブジェクトを中心に設計されています。この設計を理解することで、より効果的な統合を構築することができます。

すべてはオブジェクト

Olostepのすべてのリソースは、ユニークな識別子を持つオブジェクトです。API、SDK、またはダッシュボードを通じて作成するかどうかにかかわらず、参照、更新、クエリが可能なオブジェクトが返されます。

単数形のパス / アクション指向のAPI

オブジェクト指向API設計の理念的な純粋性に関しては常に激しく議論する用意がありますが (/crawlsへのPOSTはcrawlオブジェクトを作成し、/crawls/{crawl_id}へのGETはそのオブジェクトを取得し、メタデータを更新できるようにするべきです)、 すべてのコレクションはその単数形の名前にも応答します:POST /v1/answerはPOST /v1/answersと同じように動作し、GET /v1/scrape/{scrape_id}はGET /v1/scrapes/{scrape_id}と同様に動作します。他のbatch、crawl、map、search、schedule、monitor、file、feedbackも同様です。 複数形が標準の形式であり、このリファレンスが文書化しているものです。単数形は、オブジェクトではなくアクションを考えるときのエイリアスです。

オブジェクトはライフサイクルを持つことができる

一部のOlostepオブジェクトは、statusフィールドを通じて状態を追跡します。この状態機械パターンにより、各リソースがライフサイクルのどこにあるかを正確に知ることができます。

バッチ

バッチには、バッチ自体と個々のアイテムの2つのレベルのステータスがあります。 バッチステータス:
バッチレベルの失敗は非常にまれです。 バッチはほとんど常に完了します — 一部のURLが失敗しても、バッチ自体はcompletedステータスに達します。インフラストラクチャの壊滅的な障害(例:エンリッチメント中のLLMサービスの停止)が発生した場合、バッチが失敗することがあります。これはバッチの0.01%未満に影響します。
アイテムステータス: バッチ内の各URLは、独自のステータスを持つ個別のアイテムとして追跡されます: アイテムが失敗する理由:
  • URLがブロックされているかエラーを返す
  • パーサーの出力が欠落している
  • ネットワーク/フェッチエラー
失敗したアイテムには、失敗を説明するcodeとmessageを含むerrorオブジェクトが含まれます。バッチは完了しますが、結果を処理する際に各アイテムのステータスを確認してください。

クローラー

クローラーは常に完了します。 クローラーが0のURLを見つけた場合でも(robots.txtのブロックや無効な開始URLのため)、クローラーステータスはcompletedになります。結果を確認するにはpages_countフィールドを確認してください。

モニター

モニターは、一回限りのリソースよりも豊かなライフサイクルを持つ長寿命のオブジェクトです:
モニターを作成すると、HTTP 202がstatus: provisioningとともに返されます。モニターは、計画が追跡対象を解決するとactiveになります — GET /v1/monitors/:monitor_idをポーリングするか、?stream=1でプロビジョニングイベントをストリーミングします。activeなモニターのみが一時停止でき、pausedなモニターのみが再開できます。モニターがまだprovisioning中の場合、更新は409を返します。

リトリーブパターン

多くのオブジェクトは、後で取得できるコンテンツを生成します。retrieve_idパターンを使用すると、再処理せずにコンテンツを取得できます。
このパターンは以下で使用されます:
  • バッチアイテム — 処理された各URLにretrieve_idが付与されます
  • クローラーページ — クロールされた各ページにretrieve_idが付与されます
/v1/retrieveエンドポイントは、返すコンテンツタイプを指定するためのformatsパラメータを受け入れます(html、markdown、json、text)。

Webhooks: イベント駆動の更新

ステータスの変更をポーリングする代わりに、オブジェクトの状態が変わったときにイベントを受け取るようにwebhooksを設定します。

メタデータ: あなたのデータを私たちのデータと一緒に

metadataを使用して、オブジェクトにカスタムのキーと値のペアを添付します。これにより、Olostepリソースを内部システムにリンクできます。

まとめ