> ## Documentation Index
> Fetch the complete documentation index at: https://docs.olostep.com/llms.txt
> Use this file to discover all available pages before exploring further.

# メタデータ

> APIリソースにカスタムのキーと値のペアを添付する

<Info>
  **現在、[Batches](/api-reference/batches/create)で利用可能です。** Scrapes、Crawls、Maps、Answersへのサポートは近日中に追加予定です。
</Info>

メタデータを使用すると、Olostepリソースにカスタムのキーと値のペアを添付できます。これは、トラッキング、フィルタリング、整理、およびAPIリクエストに関連するコンテキストの保存に役立ちます。

メタデータは[Stripeのアプローチ](https://stripe.com/docs/api/metadata)に従っており、シンプルで柔軟、かつすべてのエンドポイントで一貫しています。

***

## ユースケース

<CardGroup cols={2}>
  <Card title="トラッキングと整理" icon="folder">
    注文ID、顧客ID、またはプロジェクト名でリソースを内部システムにリンクします。
  </Card>

  <Card title="フィルタリングと検索" icon="magnifying-glass">
    アプリケーション内で簡単に取得およびフィルタリングできるようにリソースにタグを付けます。
  </Card>

  <Card title="ワークフローコンテキスト" icon="diagram-project">
    パイプラインステージ、優先度レベル、または処理指示を保存します。
  </Card>

  <Card title="監査証跡" icon="clock-rotate-left">
    リクエストを開始した人、タイムスタンプ、またはバージョン情報を記録します。
  </Card>
</CardGroup>

***

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

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

<CodeGroup>
  ```json Request Body theme={null}
  {
    "url": "https://example.com",
    "metadata": {
      "order_id": "12345",
      "customer_name": "John Doe",
      "priority": "high",
      "internal_ref": "proj-2024-001"
    }
  }
  ```

  ```python Python theme={null}
  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"
          }
      }
  )
  ```

  ```javascript Node.js theme={null}
  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"
      }
    })
  });
  ```
</CodeGroup>

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

***

## 検証ルール

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

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

  * `42` → `"42"`
  * `true` → `"true"`
  * `3.14` → `"3.14"`

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

***

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

<Info>
  **現在利用可能:** [Batches](/api-reference/batches/update) のみ。

  Crawls、Scrapes、Maps、Answersは作成後のメタデータ更新をまだサポートしていません。
</Info>

既存のバッチに対して[PATCHエンドポイント](/api-reference/batches/update)を使用してメタデータを更新できます。更新はマージ動作を使用します。

### 更新操作

<AccordionGroup>
  <Accordion title="新しいキーを追加" icon="plus">
    既存のキーを保持しながら新しいキーを追加します。

    ```bash theme={null}
    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"}`
  </Accordion>

  <Accordion title="既存のキーを更新" icon="pen">
    既存のキーは新しい値で上書きされます。

    ```bash theme={null}
    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"}`
  </Accordion>

  <Accordion title="特定のキーを削除" icon="trash">
    キーを`null`または`""`（空文字列）に設定して削除します。

    ```bash theme={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"}`
  </Accordion>

  <Accordion title="すべてのメタデータをクリア" icon="eraser">
    メタデータフィールド全体を`null`または`""`に設定してすべてのキーを削除します。

    ```bash theme={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:** `{}`
  </Accordion>

  <Accordion title="混合操作" icon="shuffle">
    1つのリクエストでキーを追加、更新、削除します。

    ```bash theme={null}
    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"}`
  </Accordion>
</AccordionGroup>

### PATCH動作の概要

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