メタデータ

現在、Batchesで利用可能です。 Scrapes、Crawls、Maps、Answersへのサポートは近日中に追加予定です。

メタデータを使用すると、Olostepリソースにカスタムのキーと値のペアを添付できます。これは、トラッキング、フィルタリング、整理、およびAPIリクエストに関連するコンテキストの保存に役立ちます。メタデータはStripeのアプローチに従っており、シンプルで柔軟、かつすべてのエンドポイントで一貫しています。

ユースケース

トラッキングと整理

注文ID、顧客ID、またはプロジェクト名でリソースを内部システムにリンクします。

フィルタリングと検索

アプリケーション内で簡単に取得およびフィルタリングできるようにリソースにタグを付けます。

ワークフローコンテキスト

パイプラインステージ、優先度レベル、または処理指示を保存します。

監査証跡

リクエストを開始した人、タイムスタンプ、またはバージョン情報を記録します。

作成時にメタデータを追加する

リソースを作成する際にmetadataパラメータを含めます：

{
  "url": "https://example.com",
  "metadata": {
    "order_id": "12345",
    "customer_name": "John Doe",
    "priority": "high",
    "internal_ref": "proj-2024-001"
  }
}

import requests

response = requests.post(
    "https://api.olostep.com/v1/batches",
    headers={"Authorization": "Bearer <your_token>"},
    json={
        "items": [{"custom_id": "1", "url": "https://example.com"}],
        "metadata": {
            "project": "q4-analysis",
            "team": "data-ops",
            "priority": "high"
        }
    }
)

const response = await fetch("https://api.olostep.com/v1/batches", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <your_token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    items: [{ custom_id: "1", url: "https://example.com" }],
    metadata: {
      project: "q4-analysis",
      team: "data-ops",
      priority: "high"
    }
  })
});

メタデータは、そのリソースに対するすべての後続のGETレスポンスで返されます。

検証ルール

制約	制限	エラー例
最大キー数	50	`"メタデータは最大50個のキーを持つことができます。51個のキーが提供されました。"`
キーの長さ	40文字	`"メタデータキー \"my_very_long_key_name...\" は40文字の制限を超えています。"`
キーの形式	角括弧なし	`"メタデータキー \"items[0]\" は角括弧（[または]）を含めることはできません。"`
値の長さ	500文字	`"キー \"description\" のメタデータ値が500文字の制限を超えています。"`
値の型	文字列のみ	`"キー \"count\" のメタデータ値は文字列でなければなりません。オブジェクトが取得されました。"`

型の強制: 数字とブール値は自動的に文字列に変換されます。

42 → "42"
true → "true"
3.14 → "3.14"

オブジェクトと配列は拒否されます。

メタデータの更新 (PATCH)

現在利用可能: Batches のみ。Crawls、Scrapes、Maps、Answersは作成後のメタデータ更新をまだサポートしていません。

既存のバッチに対してPATCHエンドポイントを使用してメタデータを更新できます。更新はマージ動作を使用します。

更新操作

新しいキーを追加

既存のキーを保持しながら新しいキーを追加します。

curl -X PATCH "https://api.olostep.com/v1/batches/batch_abc123" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"new_key": "new_value"}}'

Before: {"project": "alpha"}
After: {"project": "alpha", "new_key": "new_value"}

既存のキーを更新

既存のキーは新しい値で上書きされます。

curl -X PATCH "https://api.olostep.com/v1/batches/batch_abc123" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"project": "beta"}}'

Before: {"project": "alpha", "priority": "high"}
After: {"project": "beta", "priority": "high"}

特定のキーを削除

キーをnullまたは""（空文字列）に設定して削除します。

curl -X PATCH "https://api.olostep.com/v1/batches/batch_abc123" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"priority": null}}'

Before: {"project": "alpha", "priority": "high"}
After: {"project": "alpha"}

すべてのメタデータをクリア

メタデータフィールド全体をnullまたは""に設定してすべてのキーを削除します。

curl -X PATCH "https://api.olostep.com/v1/batches/batch_abc123" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"metadata": null}'

Before: {"project": "alpha", "priority": "high"}
After: {}

混合操作

1つのリクエストでキーを追加、更新、削除します。

curl -X PATCH "https://api.olostep.com/v1/batches/batch_abc123" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"project": "gamma", "new_field": "value", "old_field": null}}'

Before: {"project": "alpha", "old_field": "remove_me"}
After: {"project": "gamma", "new_field": "value"}

PATCH動作の概要

操作	リクエスト	結果
キーを追加	`{"metadata": {"new": "value"}}`	キーが追加され、他は保持されます
キーを更新	`{"metadata": {"existing": "new_value"}}`	キーが更新され、他は保持されます
キーを削除	`{"metadata": {"key": null}}`	キーが削除され、他は保持されます
キーを削除	`{"metadata": {"key": ""}}`	キーが削除され、他は保持されます
すべてをクリア	`{"metadata": null}`	すべてのキーが削除されます
すべてをクリア	`{"metadata": ""}`	すべてのキーが削除されます
No-op	`{"metadata": {}}`	変更なし

共通

スクレイプ

バッチ

クロール

地図

回答

検索

モニター

ファイル

スケジュール

取得

残高と請求書

ユースケース

トラッキングと整理

フィルタリングと検索

ワークフローコンテキスト

監査証跡

作成時にメタデータを追加する

検証ルール

メタデータの更新 (PATCH)

更新操作

PATCH動作の概要

​ユースケース

トラッキングと整理

フィルタリングと検索

ワークフローコンテキスト

監査証跡

​作成時にメタデータを追加する

​検証ルール

​メタデータの更新 (PATCH)

​更新操作

​PATCH動作の概要

ユースケース

作成時にメタデータを追加する

検証ルール

メタデータの更新 (PATCH)

更新操作

PATCH動作の概要