Vision Eventを作成

HTTP API を介して 1 件の Vision Event を記録し、デプロイ済みモデルからの観測をログに保存します。

概要

A Visionイベントは、デプロイ済みのコンピュータビジョンモデルが観測したもののタイムスタンプ付き記録です。たとえば、検出された欠陥や在庫数のカウントなどです。これには、任意の画像、予測、カスタムメタデータも含められます。このページでは、1つのイベントを記録して、検索・フィルタ可能な本番履歴の一部にする方法を示します。多数のイベントを一度に取り込むには、 Visionイベントの一括作成.

HTTP API

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

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

Create a Vision Event

post

Create a single vision event.

認可

Authorizationstring必須

Roboflow API key passed as a Bearer token.

本文

eventIdstring · 最大: 256必須

Globally unique identifier. Use a UUID (v4).

eventTypestring · enum必須可能な値:

useCaseIdstring · 最大: 256必須

The use case this event belongs to.

timestampstring · date-time必須

ISO 8601 timestamp. Must be between one year ago and tomorrow.

deviceIdstring · 最大: 256オプション

streamIdstring · 最大: 256オプション

workflowIdstring · 最大: 256オプション

workflowVersionstring · 最大: 64オプション

displayImagePositioninteger · 最大: 999オプション

eventDataobject必須

Type-specific event data. Structure depends on eventType.

レスポンス

201

Event created successfully.

application/json

eventIdstringオプション

createdbooleanオプション

deprecationsstring[]オプション

400

Validation error.

application/json

403

Insufficient permissions for this resource.

application/json

post/vision-events

POST /vision-events HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 720

{
  "eventId": "text",
  "eventType": "quality_check",
  "useCaseId": "text",
  "timestamp": "2026-08-09T06:31:05.695Z",
  "deviceId": "text",
  "streamId": "text",
  "workflowId": "text",
  "workflowVersion": "text",
  "images": [
    {
      "label": "text",
      "sourceId": "text",
      "inputSourceId": "text",
      "objectDetections": [
        {
          "class": "text",
          "x": 1,
          "y": 1,
          "width": 1,
          "height": 1,
          "confidence": 1
        }
      ],
      "classifications": [
        {
          "class": "text",
          "confidence": 1
        }
      ],
      "instanceSegmentations": [
        {
          "class": "text",
          "x": 1,
          "y": 1,
          "width": 1,
          "height": 1,
          "confidence": 1,
          "points": [
            [
              1
            ]
          ]
        }
      ],
      "keypoints": [
        {
          "class": "text",
          "x": 1,
          "y": 1,
          "width": 1,
          "height": 1,
          "confidence": 1,
          "keypoints": [
            {
              "id": 1,
              "x": 1,
              "y": 1,
              "occluded": true
            }
          ]
        }
      ]
    }
  ],
  "displayImagePosition": 1,
  "eventData": {},
  "customMetadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

{
  "eventId": "text",
  "created": true,
  "warnings": [
    {
      "type": "text",
      "path": "text",
      "value": "text",
      "valueType": "text"
    }
  ],
  "deprecations": [
    "text"
  ]
}

リクエスト例

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
    }
  }'

リクエスト本文のパラメータ

各イベントにはグローバルに一意な eventIdが必要です。衝突を避けるためにUUID（v4）の使用を推奨します。重複したevent IDは、以前に取り込まれたイベントを上書きします。

必須フィールド：

eventId (string, max 256 characters): イベントのグローバル一意識別子。UUID（v4）を使用してください。
eventType (string): 次のいずれか： quality_check, inventory_count, safety_alert, custom、または operator_feedback.
useCaseId (string, max 256 characters): このイベントが属するユースケース。ユースケースの作成と管理方法についてはユースケースを参照してください。
timestamp (string, ISO 8601): イベントが発生した日時。1年前から明日までの範囲でなければなりません。
eventData (object): 種別固有のイベントデータ。必要な構造については以下のイベントデータスキーマを参照してください。

任意フィールド：

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

イベントデータスキーマ

の構造は eventData 次第です eventType:

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

result (string, optional): "pass" または "fail".
externalId (string, max 1000, optional): 外部参照ID。

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

location (string, max 1000, optional): 個数を取得した場所。
itemCount (integer, >= 0, optional): 数えたアイテム数。
itemType (string, max 1000, optional): 数えたアイテムの種類。
externalId (string, max 1000, optional): 外部参照ID。

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

alertType (string, max 256, optional): アラートの種類（英数字、アンダースコア、ダッシュ）。
severity (string, optional): "low", "medium"、または "high".
description (string, max 10000, optional): アラートの説明。
externalId (string, max 1000, optional): 外部参照ID。

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

value (string, max 10000, optional): 自由形式のイベントデータ。
externalId (string, max 1000, optional): 外部参照ID。

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

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

レビュー担当者のメモはトップレベルの comment フィールドではなく eventData.

画像オブジェクト

イベントに画像を添付するには、まず各画像を Visionイベント画像のアップロードエンドポイントを使ってアップロードし、 sourceIdを取得する必要があります。 images 配列内の各画像オブジェクトは、注釈付き（出力）画像を表します。元の未注釈（入力）画像も関連付けたい場合は、別途アップロードして、その sourceId を inputSourceId.

{
  "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 (string, optional): 画像のラベル。
sourceId (string, optional): sourceId が注釈付き画像のアップロードから返されます.
inputSourceId (string, optional): sourceId 元の未注釈（入力）画像のアップロードから返されます。
objectDetections (array, max 1000, optional): class、x、y、width、height、confidenceを含むバウンディングボックス検出。 class, x, y, width, height、および confidence (0-1).
classifications (array, max 1000, optional): class と confidence を含む分類結果。 class と confidence (0-1).
instanceSegmentations (array, max 1000, optional): バウンディングボックス項目に加えてpointsを含むセグメンテーション結果。 points (array of [x, y] のペア、最小3個）。
keypoints (array, max 1000, optional): バウンディングボックス項目に加えてkeypointsを含むキーポイント検出。 keypoints (array of objects with id, x, yを持ち、任意で occludedを含むオブジェクトの配列、1検出につき少なくとも1つのキーポイントが必要）。

カスタムメタデータ

各イベントには最大100個のキーと値のカスタムメタデータを付加できます。カスタムメタデータは Visionイベントのクエリエンドポイントから検索できます。

制約：

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

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

レスポンス例

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

{
  "error": "eventType is required"
}

{
  "error": "このリソースに対する権限が不足しています。"
}

検証と警告

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

必須ではないフィールドに問題がある場合は、拒否されるのではなく、レスポンス内の warnings 配列として返されます。これには以下が含まれます：

内の必須フィールドの欠落 eventData （例： relatedEventId について operator_feedback)
の無効な値 eventData フィールド severity)
スキーマに含まれない認識されないフィールド

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

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

レスポンスには deprecated項目 の配列が含まれることもあります。

Python SDK

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

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

任意フィールド：

eventData (dict): 種別固有のイベントデータ。
deviceId, streamId, workflowId (string): コンテキスト識別子。
images (list): 注釈付き画像オブジェクト。以下を参照してください。 Visionイベント画像のアップロード.
customMetadata (dict): 最大100個のキーと値のカスタムメタデータ。
comment (string): イベントに関するメモ。主に operator_feedback.

の完全なイベントスキーマ、種別ごとのイベントデータ構造、画像注釈フォーマットについては、 REST APIリファレンス.

前へVision Eventを一括作成次へイベントを削除

最終更新 1 日前

役に立ちましたか？