> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/deployment/ja/to/vision-events/create-a-vision-event.md).

# Vision Event を作成する

## 概要

1つの [ビジョンイベント](/deployment/ja/to/vision-events.md) は、デプロイ済みのコンピュータビジョンモデルが観測した内容のタイムスタンプ付き記録です。たとえば、検出された欠陥や在庫数などです。任意の画像、予測結果、カスタムメタデータも含められます。このページでは、1件のイベントを記録して、検索・フィルタ可能な本番履歴の一部にする方法を示します。多数のイベントを一度に取り込むには、次を使用してください [ビジョンイベントを一括作成](/deployment/ja/to/vision-events/batch-create-vision-events.md).

## HTTP API

コンピュータビジョンのデプロイからの観測を記録するために、1件のビジョンイベントを作成します。

**必要なスコープ:** `vision-events:write` または `device:update`

{% openapi src="/files/934e54fa9aa57656316a422a76238b867f081de5" path="/vision-events" method="post" %}
[openapi.yaml](https://970637113-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-dfdc1702ad3d1a62ad0a661e9609f6bbe2fc8d4c%2Fopenapi.yaml?alt=media)
{% endopenapi %}

### リクエスト例

```bash
curl -X POST "https://api.roboflow.com/vision-events" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "eventType": "quality_check",
    "useCaseId": "a1b3c8e1",
    "timestamp": "2024-01-15T10:30:00Z",
    "eventData": {
      "result": "fail",
      "externalId": "batch-001"
    },
    "customMetadata": {
      "line": "A1",
      "operator": "John Doe",
      "temperature": 72.5
    }
  }'
```

### リクエストボディのパラメータ

{% hint style="info" %}
各イベントには、グローバルに一意な `eventId`。衝突を避けるため、UUID (v4) の使用を推奨します。重複したイベントIDは、以前に取り込まれたイベントを上書きします。
{% endhint %}

**必須フィールド:**

* **`eventId`** (文字列): イベントのグローバル一意識別子。UUID (v4) を使用してください。
* **`eventType`** (文字列): 次のいずれか `quality_check`, `inventory_count`, `safety_alert`, `custom`、または `operator_feedback`.
* **`useCaseId`** (文字列、最大256文字): このイベントが属するユースケース。 [ユースケース](/deployment/ja/to/vision-events/use-cases.md) ユースケースの作成と管理方法については、こちらを参照してください。
* **`timestamp`** (文字列、ISO 8601): イベントが発生した日時。1年前から明日までの範囲でなければなりません。
* **`eventData`** (オブジェクト): イベント種別固有のデータ。 [イベントデータスキーマ](#event-data-schemas) 以下で、イベント種別ごとの必須構造を確認してください。

**任意フィールド:**

* **`deviceId`** (文字列、最大256): イベントを生成したデバイスの識別子。
* **`streamId`** (文字列、最大256): 動画ストリームの識別子。
* **`workflowId`** (文字列、最大256): イベントを生成したワークフローの識別子。
* **`workflowVersion`** (文字列、最大64): ワークフローのバージョン。
* **`images`** (配列、最大1000): 注釈付き画像オブジェクトの配列。 [画像オブジェクト](#image-objects) を参照してください。
* **`displayImagePosition`** (数値、0〜999): 次の配列内における画像のインデックス位置。 `images` プライマリ表示画像として使用するための配列です。たとえば、 `0` 1枚目の画像には `1` 2枚目には、というように指定します。
* **`customMetadata`** (オブジェクト、最大100キー): カスタムメタデータのキーと値のペア。 [カスタムメタデータ](#custom-metadata) を参照してください。
* **`comment`** (文字列、最大1000): イベントに関するメモ。 `operator_feedback`これにはレビュアーのメモが入ります。

### イベントデータスキーマ

の構造は `eventData` は次に依存します: `eventType`:

{% tabs %}
{% tab title="quality\_check" %}

```json
{
  "result": "pass",
  "externalId": "batch-001"
}
```

* **`result`** (文字列、任意): `"pass"` または `"fail"`.
* **`externalId`** (文字列、最大1000、任意): 外部参照ID。
  {% endtab %}

{% tab title="inventory\_count" %}

```json
{
  "location": "warehouse-a",
  "itemCount": 42,
  "itemType": "pallets",
  "externalId": "inv-2024-001"
}
```

* **`location`** (文字列、最大1000、任意): 計測場所。
* **`itemCount`** (整数、0以上、任意): カウントした項目数。
* **`itemType`** (文字列、最大1000、任意): カウントした項目の種類。
* **`externalId`** (文字列、最大1000、任意): 外部参照ID。
  {% endtab %}

{% tab title="safety\_alert" %}

```json
{
  "alertType": "no_hardhat",
  "severity": "high",
  "description": "ゾーンB3で必要なPPEを着用していない作業者が検出されました。",
  "externalId": "alert-2024-001"
}
```

* **`alertType`** (文字列、最大256、任意): アラートの種類（英数字、アンダースコア、ハイフン）。
* **`severity`** (文字列、任意): `"low"`, `"medium"`、または `"high"`.
* **`description`** (文字列、最大10000、任意): アラートの説明。
* **`externalId`** (文字列、最大1000、任意): 外部参照ID。
  {% endtab %}

{% tab title="custom" %}

```json
{
  "value": "文字列としてのカスタムイベントデータ",
  "externalId": "custom-2024-001"
}
```

* **`value`** (文字列、最大10000、任意): 自由形式のイベントデータ。
* **`externalId`** (文字列、最大1000、任意): 外部参照ID。
  {% endtab %}

{% tab title="operator\_feedback" %}

```json
{
  "relatedEventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "feedback": "incorrect"
}
```

* **`relatedEventId`** (文字列、必須): このフィードバックの対象となるイベントのイベントID（UUID）。
* **`feedback`** (文字列、必須): `"correct"`, `"incorrect"`、または `"inconclusive"`.

レビュアーのメモはトップレベルの `comment` フィールドに入れ、 `eventData`.
{% endtab %}
{% endtabs %}

### 画像オブジェクト

イベントに画像を添付するには、まず各画像を次の手順でアップロードする必要があります。 [ビジョンイベント画像をアップロード](/deployment/ja/to/vision-events/upload-a-vision-event-image.md#http-api) エンドポイントを使用して、 `sourceId`を取得します。 `images` 配列内の各画像オブジェクトは、注釈付き（出力）画像を表します。元の注釈なし（入力）画像も関連付けたい場合は、別途アップロードして、その `sourceId` を `inputSourceId`.

```json
{
  "label": "inspection-photo",
  "sourceId": "img-source-123",
  "inputSourceId": "camera-1",
  "objectDetections": [
    {
      "class": "defect",
      "x": 100,
      "y": 200,
      "width": 50,
      "height": 30,
      "confidence": 0.95
    }
  ],
  "classifications": [
    {
      "class": "damaged",
      "confidence": 0.87
    }
  ],
  "instanceSegmentations": [
    {
      "class": "crack",
      "x": 100,
      "y": 200,
      "width": 50,
      "height": 30,
      "confidence": 0.92,
      "points": [[100, 200], [120, 210], [110, 230]]
    }
  ],
  "keypoints": [
    {
      "class": "joint",
      "x": 100,
      "y": 200,
      "width": 50,
      "height": 30,
      "confidence": 0.88,
      "keypoints": [
        { "id": 0, "x": 105, "y": 205, "occluded": false },
        { "id": 1, "x": 115, "y": 215 }
      ]
    }
  ]
}
```

**画像フィールド:**

* **`label`** (文字列、任意): 画像のラベル。
* **`sourceId`** (文字列、任意): `sourceId` 返される [注釈付き画像のアップロード時に](/deployment/ja/to/vision-events/upload-a-vision-event-image.md#http-api).
* **`inputSourceId`** (文字列、任意): `sourceId` 元の注釈なし（入力）画像をアップロードすると返されます。
* **`objectDetections`** (配列、最大1000、任意): 次を含むバウンディングボックス検出結果: `class`, `x`, `y`, `width`, `height`、および `confidence` (0-1).
* **`classifications`** (配列、最大1000、任意): 次を含む分類結果: `class` および `confidence` (0-1).
* **`instanceSegmentations`** (配列、最大1000、任意): バウンディングボックス項目に加えて次を含むセグメンテーション結果: `points` (配列の `[x, y]` のペア、最小3つ)。
* **`keypoints`** (配列、最大1000、任意): バウンディングボックス項目に加えて次を含むキーポイント検出結果: `keypoints` (オブジェクトの配列、 `id`, `x`, `y`および任意の `occluded`を含み、検出ごとにキーポイントは最低1つ)。

### カスタムメタデータ

各イベントには、最大100件のカスタムメタデータのキーと値のペアを添付できます。カスタムメタデータは次の [ビジョンイベントを検索](/deployment/ja/to/vision-events/query-events.md#http-api) エンドポイントからクエリできます。

**制約:**

* キーは次のパターンに一致する必要があります: `[a-zA-Z0-9_ -]+` (文字、数字、アンダースコア、ハイフン、スペース）、最大100文字。
* 文字列値は1000文字までです。
* 数値は小数点以下6桁まで対応します。
* ブール値がサポートされています。

```json
{
  "customMetadata": {
    "production_line": "A1",
    "shift": "morning",
    "temperature": 72.5,
    "is_overtime": false
  }
}
```

### レスポンス例

{% tabs %}
{% tab title="201" %}

```json
{
  "eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created": true
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "eventType は必須です"
}
```

{% endtab %}

{% tab title="403" %}

```json
{
  "error": "このリソースに対する権限が不十分です。"
}
```

{% endtab %}
{% endtabs %}

### 検証と警告

Vision Events API は eager ingestion を使用します。必須フィールド4つ（`eventId`, `eventType`, `useCaseId`, `timestamp`）のみが厳密に検証されます。これらが通れば、他のフィールドにエラーがあってもイベントは常に受け入れられ、保存されます。

必須でないフィールドに問題がある場合は、 `warnings` 配列としてレスポンスに返され、拒否の原因にはなりません。これには次が含まれます:

* 内の必須フィールドの欠落 `eventData` （例: `relatedEventId` の `operator_feedback`)
* に対する無効な値 `eventData` フィールド（例: `severity`)
* スキーマの一部ではない認識されないフィールド

警告がある場合、無効な `eventData` は空のオブジェクトとして保存されます `{}`が、イベント自体は作成されます。

```json
{
  "eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created": true,
  "warnings": [
    {
      "type": "any.required",
      "path": "eventData.relatedEventId",
      "value": null,
      "valueType": "object"
    }
  ]
}
```

レスポンスには、 `deprecations` 配列が含まれる場合があります（非推奨のフィールド名が使用された場合）。

## Python SDK

コンピュータビジョンのデプロイからの観測を記録するために、1件のビジョンイベントを作成します。

```python
import roboflow

roboflow.login()

rf = roboflow.Roboflow()
ws = rf.workspace()

ws.write_vision_event({
    "eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "eventType": "quality_check",
    "useCaseId": "a1b3c8e1",
    "timestamp": "2024-01-15T10:30:00Z",
    "eventData": {
        "result": "fail",
        "externalId": "batch-001",
    },
    "customMetadata": {
        "line": "A1",
        "operator": "John Doe",
        "temperature": 72.5,
    },
})
```

イベントペイロードはクライアント側の検証なしでサーバーに直接送られるため、新しいイベント種別やフィールドもSDKの更新なしで利用できます。

**必須フィールド:**

* **`eventId`** (文字列): グローバルに一意な識別子。UUID (v4) を使用してください。
* **`eventType`** (文字列): 次のいずれか `quality_check`, `inventory_count`, `safety_alert`, `custom`、または `operator_feedback`.
* **`useCaseId`** (文字列): このイベントが属するユースケース。
* **`timestamp`** (文字列、ISO 8601): イベントが発生した日時。

**任意フィールド:**

* **`eventData`** (辞書): イベント種別固有のデータ。
* **`deviceId`**, **`streamId`**, **`workflowId`** (文字列): コンテキスト識別子。
* **`images`** (リスト): 注釈付きの画像オブジェクト。 [ビジョンイベント画像をアップロード](/deployment/ja/to/vision-events/upload-a-vision-event-image.md#python-sdk).
* **`customMetadata`** (辞書): 最大100件のカスタムメタデータのキーと値のペア。
* **`comment`** (文字列): イベントに関するメモ。主に次と併用されます: `operator_feedback`.

イベントの完全なスキーマ、種別ごとのイベントデータ構造、および画像注釈フォーマットについては、次を参照してください。 [REST APIリファレンス](#http-api).