> 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 を作成

## 概要

A [Vision Event](/deployment/ja/to/vision-events.md) は、デプロイ済みのコンピュータビジョンモデルが観測したもののタイムスタンプ付き記録です。たとえば、検出された欠陥や在庫数などが含まれ、任意で画像、予測、カスタムメタデータも付けられます。このページでは、検索やフィルタリングが可能な本番履歴の一部として単一のイベントを記録する方法を示します。多数のイベントを一度に取り込むには、 [Batch Create Vision Events](/deployment/ja/to/vision-events/batch-create-vision-events.md)を使用してください。デプロイ先からクラウドへの経路がない場合は、 [Upload a Vision Event Bundle](/deployment/ja/to/vision-events/upload-a-vision-event-bundle.md).

## を参照してください。

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

**必要なスコープ:** `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-2afefc06c784ca78eb7ec96a99bee48f8a2daaa5%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`** (string, 最大 256 文字): イベントのグローバル一意識別子。UUID (v4) を使用してください。
* **`eventType`** (string): 次のいずれか `quality_check`, `inventory_count`, `safety_alert`, `custom`、または `operator_feedback`.
* **`useCaseId`** (string, 最大 256 文字): このイベントが属するユースケース。ユースケースの作成と管理方法については、 [ユースケース](/deployment/ja/to/vision-events/use-cases.md) を参照してください。
* **`timestamp`** (string, ISO 8601): イベントが発生した日時。1年前から明日までの範囲である必要があります。
* **`eventData`** (object): イベント種別固有のデータ。イベント種別ごとの必要な構造については、 [イベントデータスキーマ](#event-data-schemas) を以下で参照してください。

**任意の項目:**

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

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

の構造は `eventData` 次第です `eventType`:

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

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

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

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

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

* **`location`** (string, 最大 1000、任意): カウントを実施した場所。
* **`itemCount`** (integer, >= 0、任意): カウントしたアイテム数。
* **`itemType`** (string, 最大 1000、任意): カウントしたアイテムの種類。
* **`externalId`** (string, 最大 1000、任意): 外部参照 ID。
  {% endtab %}

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

```json
{
  "alertType": "no_hardhat",
  "severity": "high",
  "description": "Worker detected without required PPE in zone B3.",
  "externalId": "alert-2024-001"
}
```

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

{% tab title="custom" %}

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

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

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

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

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

レビュー担当者のメモは最上位の `comment` フィールドに入れ、 `eventData`.
{% endtab %}
{% endtabs %}

### 画像オブジェクト

イベントに画像を添付するには、まず各画像を次の [Vision Event 画像をアップロード](/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]]
    }
  ],
  "metadata": {
    "verdict": "pass",
    "angle": 42.5
  },
  "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`** (string, 任意): 画像のラベル。
* **`sourceId`** (string, 任意): `sourceId` から返される [注釈付き画像をアップロードしたときに](/deployment/ja/to/vision-events/upload-a-vision-event-image.md#http-api).
* **`inputSourceId`** (string, 任意): `sourceId` 元の注釈なし（入力）画像をアップロードしたときに返されます。
* **`objectDetections`** (array, 最大 1000、任意): 次の項目を持つバウンディングボックス検出。 `class`, `x`, `y`, `width`, `height`、および `confidence` (0-1).
* **`classifications`** (array, 最大 1000、任意): 次の項目を持つ分類結果。 `class` および `confidence` (0-1).
* **`instanceSegmentations`** (array, 最大 1000、任意): バウンディングボックスの項目に加えて `points` (の配列 `[x, y]` のペア、最小 3）。
* **`keypoints`** (array, 最大 1000、任意): バウンディングボックスの項目に加えて `keypoints` (を持つオブジェクトの配列 `id`, `x`, `y`、および任意の `occluded`を含むキーポイント検出。各検出につき少なくとも 1 つのキーポイントが必要です。
* **`metadata`** (object, 最大 100 キー、任意): この1枚の画像に関するキーと値のペア。 [画像メタデータ](#image-metadata) を以下で参照してください。

### 画像メタデータ

を使用すると、 `metadata` その画像だけに属する値を記録できます。たとえば、合否判定、シリアル番号、カメラ角度などです。値はイベント詳細ビューで画像と一緒に表示されます。イベント全体を説明する値を付けるには、代わりに [カスタムメタデータ](#custom-metadata) を使用してください。

**制約:**

* キーは次のパターンに一致する必要があります `[a-zA-Z0-9_ -]+` （英字、数字、アンダースコア、ハイフン、スペース）、最大 128 文字。
* 画像ごとに最大 100 キー、イベントごとに最大 200 の異なるキーまでです。
* 値は文字列（最大 1000 文字）、数値、またはブール値でなければなりません。ネストされたオブジェクトと配列は拒否されます。

これらのルールに違反するキーは削除され、 `warnings` 配列に報告されます。画像の残りの部分は引き続き保存されます。

イベントで使用しているキーを確認するには、 [画像メタデータスキーマを取得](/deployment/ja/to/vision-events/get-image-metadata-schema.md)を呼び出してください。画像メタデータは表示と検索のためのものです。 [イベントクエリ](/deployment/ja/to/vision-events/query-events.md) ではまだフィルタできません。

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

各イベントには、カスタムメタデータとして最大 100 個のキーと値のペアを付けられます。カスタムメタデータは [Vision Events のクエリ](/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 is required"
}
```

{% 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

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

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

**任意の項目:**

* **`eventData`** (dict): 種別固有のイベントデータ。
* **`deviceId`**, **`streamId`**, **`workflowId`** (list): 注釈付き画像オブジェクト。
* **`images`** を参照してください。 [Vision Event 画像をアップロード](/deployment/ja/to/vision-events/upload-a-vision-event-image.md#python-sdk).
* **`customMetadata`** (dict): カスタムメタデータのキーと値のペアを最大 100 個。
* **`comment`** (string): イベントに関するメモ。主に `operator_feedback`.

を参照すると、イベントの完全なスキーマ、種別ごとのイベントデータ構造、画像注釈形式を確認できます。 [REST API リファレンス](#http-api).