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

HTTP API 経由で 1 件の Vision Event を記録し、デプロイしたモデルからの観測をログに残します。

## 概要

1つの [ビジョンイベント](https://docs.roboflow.com/deployment/ja/to/vision-events.md) とは、デプロイ済みのコンピュータービジョンモデルが観測した事象（検出された欠陥や在庫数など）を、タイムスタンプ付きで記録したものです。画像、予測結果、カスタムメタデータを任意で添付できます。このページでは、単一のイベントを記録し、検索やフィルタリングが可能な本番環境の履歴に追加する方法を説明します。一度に多数のイベントを取り込むには、 [ビジョンイベントの一括作成](https://docs.roboflow.com/deployment/ja/to/vision-events/batch-create-vision-events.md)を使用してください。デプロイ環境からクラウドへの経路がない場合は、 [ビジョンイベントバンドルのアップロード](https://docs.roboflow.com/deployment/ja/to/vision-events/upload-a-vision-event-bundle.md).

## HTTP API

コンピュータービジョンのデプロイ環境での観測結果を記録するには、単一のビジョンイベントを作成します。

**必須スコープ：** `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-0988c6c6c600d725f72d1ecfe0cbeba9b717363f%2Fopenapi.yaml?alt=media)
{% endopenapi %}

### 画像のメタデータ

使用します `metadata` を画像オブジェクトに指定すると、その画像だけに属する値（合否判定、シリアル番号、カメラの角度など）を記録できます。値はイベント詳細ビューで画像とともに表示されます。イベント全体を説明する値を付加するには、代わりに `customMetadata` を使用します。

次の条件を満たさないキーは `metadata` 上限を超えた値は破棄され、次の場所に報告されます。 `warnings` 配列に記録されます。画像の残りの部分は引き続き保存されます。

イベントで使用されているキーを確認するには、次を呼び出します。 [画像メタデータスキーマを取得](https://docs.roboflow.com/deployment/ja/to/vision-events/get-image-metadata-schema.md)。これらのキーでイベントをフィルタリングするには、次を使用します。 `imageMetadataFilters` の [イベントをクエリ](https://docs.roboflow.com/deployment/ja/to/vision-events/query-events.md#query-vision-events).

### 検証と警告

Vision Events API は先行取り込み方式を採用しています。必須フィールドのうち、厳密に検証されるのは次の4つのみです（`eventId`, `eventType`, `useCaseId`, `timestamp`）。これらの検証に通れば、ほかのフィールドにエラーが含まれていても、イベントは必ず受け付けられ、保存されます。

必須ではないフィールドに問題がある場合は、リクエストが拒否されるのではなく、レスポンスの `warnings` 配列に返されます。これには次のものが含まれます。

* 次の中の必須フィールドの欠落 `eventData` （例： `relatedEventId` の `operator_feedback`)
* 次の値が無効です： `eventData` フィールド（例： `severity`)
* スキーマに含まれていない未認識のフィールド

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

レスポンスには、非推奨のフィールド名が使用された場合、 `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`** （文字列、最大256文字）：グローバルに一意な識別子。UUID（v4）を使用します。
* **`eventType`** （文字列）：次のいずれかです。 `quality_check`, `inventory_count`, `safety_alert`, `custom`、または `operator_feedback`.
* **`useCaseId`** （文字列）：このイベントが属するユースケース。
* **`timestamp`** （文字列、ISO 8601）：イベントが発生した日時。

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

* **`eventData`** （辞書）：イベントタイプ固有のデータ。
* **`deviceId`**, **`streamId`**, **`workflowId`** （文字列）：コンテキスト識別子。
* **`images`** （リスト）：アノテーション付きの画像オブジェクト。「 [Visionイベント画像をアップロード](https://docs.roboflow.com/deployment/ja/to/vision-events/upload-a-vision-event-image.md#python-sdk).
* **`videos`** （リスト）：動画オブジェクト。各 `sourceId` から取得します [Vision Event Video をアップロードする](https://docs.roboflow.com/deployment/ja/to/vision-events/upload-a-vision-event-video.md#http-api).
* **`customMetadata`** （辞書）：カスタムメタデータのキーと値のペアを最大100個指定します。
* **`comment`** （文字列）：イベントに関するメモ。主に `operator_feedback`.

イベントの完全なスキーマ、タイプ別のイベントデータ構造、画像アノテーション形式については、 [REST API リファレンスを参照してください](#http-api).
