> 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/roboflow-cloud/cloud-streaming/live-results.md).

# ライブ結果

実行中のCloud StreamingジョブのJSON結果をすべて、WebSocketフィード経由で独自のアプリケーションに受信し、接続が切断された後も再開できます。

ライブ結果フィードはWebSocketで、実行中のCloud Streamingジョブの各JSON結果を、Workflowが生成するたびにアプリケーションへ配信します。結果には番号が付いているため、クライアントは再接続して最後に受信した結果の次から再開し、結果がスキップされた場合も確認できます。

処理したすべてのフレームの結果が自社サービスで必要な場合（例：カウント、ログ記録、ダッシュボードへの反映）は、このフィードを使用します。選択した結果のみをHTTPSエンドポイントに送信するには、 [Workflow sink](https://docs.roboflow.com/deployment/ja/roboflow-cloud/cloud-streaming/consume-results.md#send-results-with-a-workflow-sink)を使用します。注釈付き動画を視聴するには、 [視聴許可](https://docs.roboflow.com/deployment/ja/roboflow-cloud/cloud-streaming/consume-results.md#watch-live-output).

をリクエストしてください。フィードはストリーミング用のオプションです。サブスクリプションでは、WebSocketを開いたままにできないクライアント向けに、同じ結果をページ分割されたJSONとして提供する `pollUrl` も返されます。Server-Sent Events用のURLは返されません。

{% hint style="info" %}
フィードが存在するのは、ジョブがclaim済みまたは実行中の場合のみです。終了していないその他のジョブでは、サブスクリプションはフィードの代わりに `retryAfterSeconds` を返します。接続前の結果は保存されません。結果を保持するには、フィードを継続的に読み取るか、Workflow sinkを使用してください。
{% endhint %}

## 開始する前に

必要なもの：

* Cloud Streamingジョブ。 [HTTP API](https://docs.roboflow.com/deployment/ja/roboflow-cloud/cloud-streaming/run-a-workflow.md#http-api) またはWebアプリでジョブを開始し、そのジョブIDをコピーします。
* 次のスコープを持つワークスペースAPIキー： `video-inference-job:read` 。詳しくは [スコープ付きAPIキー](https://docs.roboflow.com/reference/authentication/authentication/scoped-api-keys)を参照してください。キーはサーバー上で管理してください。

結果を読み取るには、2つの手順が必要です。まずRoboflow APIにジョブのフィードの場所を問い合わせ、次に返されたWebSocketを開きます。

## ジョブをサブスクライブする

サブスクライブしてもジョブには変更が加わらず、動画も開始されません。接続のたびに、また接続が終了するたびに、再度呼び出してください。

{% openapi src="/files/1398286bea32cc2689a4df3f30ae94e233631c05" path="/{workspace}/video-jobs/v1/{jobId}/results/subscribe" method="post" %}
[cloud-streaming.yaml](https://970637113-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-2927c06848d4341631bbd3bafea073b855e32b47%2Fcloud-streaming.yaml?alt=media)
{% endopenapi %}

応答は次の3種類のいずれかです。以下の順に確認してください。

1. `ended` が `true`の場合：ジョブはこれ以上結果を生成しません。 `successorJobId` が含まれている場合、ジョブはそのIDで続行されるため、そのIDをサブスクライブしてください。含まれていない場合は終了します。
2. `retryAfterSeconds` が含まれている場合：現在、ジョブにフィードはありません（例：キュー内にある、ソースを待機中、再起動中）。指定された秒数だけ待ってから、再度サブスクライブしてください。
3. `eventsUrl` と `accessToken` が含まれている場合：フィードに接続します。

## フィードに接続する

WebSocketを開き、返されたとおりの `eventsUrl` に接続し、 `accessToken` を `Authorization` ヘッダーに指定します。

```
GET /PROCESSOR_ID/events/ws?job=JOB_ID HTTP/1.1
Host: processor.example.invalid
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Version: 13
Sec-WebSocket-Key: ...
Authorization: Bearer lr1.1800000600.RESULTS_TOKEN_SIGNATURE
```

ヘッダーを設定できないクライアントは、トークンを次のものとして追加できます： `access_token` クエリパラメーター。クエリー文字列はログに記録されることが多いため、ヘッダーを使用してください。

接続が切断された後に再開するには、次を追加します： `after` 最後に受信した結果の `seq` を指定します（例： `&after=1041`）。フィードはその結果に続く結果を再送します。 `after`を指定しない場合、フィードは次の新しい結果から開始します。

フィードは15秒ごとにWebSocket pingを送信し、pingの後30秒間クライアントから応答がないと接続を閉じます。ほとんどのWebSocketライブラリはpingに自動で応答します。フィードは一方向です。クライアントが送信したメッセージは無視されます。

フィードが接続を拒否すると、通常のHTTPステータスを返します。

<table data-search="false"><thead><tr><th>ステータス</th><th>意味</th><th>対処方法</th></tr></thead><tbody><tr><td>400</td><td>リクエストが有効なWebSocketアップグレードではありません。</td><td>クライアントを修正してください。</td></tr><tr><td>401</td><td>トークンがないか、有効期限が切れているか、ジョブの以前の実行で発行されたものです。</td><td>新しいトークンを取得するため、再度サブスクライブしてください。</td></tr><tr><td>404</td><td>このプロセッサーではジョブがすでに実行されていません。</td><td>再度サブスクライブしてください。</td></tr><tr><td>429</td><td>このジョブのサブスクライバー数はすでに16です。</td><td>5秒以上待ってから、再度サブスクライブしてください。</td></tr></tbody></table>

## メッセージ

各メッセージは、次の `type`.

<table data-search="false"><thead><tr><th>タイプ</th><th>送信タイミング</th><th>フィールド</th></tr></thead><tbody><tr><td><code>hello</code></td><td>最初に1回</td><td><code>protocol</code>, <code>jobId</code>, <code>executionGeneration</code>, <code>nextSeq</code></td></tr><tr><td><code>result</code></td><td>Workflowの結果ごとに1回</td><td><code>seq</code>, <code>result</code></td></tr><tr><td><code>gap</code></td><td>結果がスキップされた場合</td><td><code>fromSeq</code>, <code>toSeq</code></td></tr><tr><td><code>end</code></td><td>実行停止時に最後に1回</td><td><code>reason</code></td></tr></tbody></table>

### hello

`nextSeq` は `seq` この接続が送信する次の結果の `protocol` は `1`.

```json
{"type": "hello", "protocol": 1, "jobId": "JOB_ID", "executionGeneration": 1, "nextSeq": 1042}
```

### 結果

`seq` は、ジョブの1回の実行内で結果を0から数えます。 `result` には、そのフレームのWorkflow出力が名前ごとに格納されます。画像はフィードで送信されず、画像出力は `image_ref` プレースホルダーとして表示されます。 `latencyMs` は `null`.

```json
{
  "type": "result",
  "seq": 1042,
  "result": {
    "frameId": 31260,
    "timestamp": "2026-01-15T17:04:05.123456Z",
    "latencyMs": 41.7,
    "outputs": {
      "predictions": {
        "image": {"width": 1920, "height": 1080},
        "predictions": [
          {
            "x": 812.5,
            "y": 440.0,
            "width": 96.0,
            "height": 210.0,
            "confidence": 0.91,
            "class": "person",
            "class_id": 0,
            "detection_id": "0f6b2c1e-7a4d-4c39-9d0e-5b1f8a2c3d4e"
          }
        ]
      },
      "bounding_box_visualization": {"type": "image_ref", "output": "bounding_box_visualization"}
    }
  }
}
```

outputs `outputs` の各エントリーの形式は、Workflowのブロックによって異なります。

### ギャップ

A `gap` は、接続で受信できなくなった結果を、 `fromSeq` から `toSeq` まで（両端を含む）報告します。結果がリプレイウィンドウから外れた後に再開した場合や、クライアントの読み取り速度がジョブの結果生成速度に追いつかない場合に送信されます。

```json
{"type": "gap", "fromSeq": 1043, "toSeq": 1100}
```

### 終了

実行が停止すると、フィードは `end` を送信し、コード1000でWebSocketを閉じます。 `reason` は `completed`, `error`, `stopped`、または `replaced` （ジョブの新しい実行に引き継がれた場合）です。

```json
{"type": "end", "reason": "completed"}
```

停止したジョブでは、 `end` メッセージを送信せずに接続が切断されることもあるため、 `end` ジョブの終了を知るためにこのメッセージに頼らないでください。

## 再接続してジョブを追跡する

原因にかかわらず、すべての接続終了を同じように扱います。再度サブスクライブし、レスポンスに従ってください。

1. 次の値を記録しておきます： `seq` （最後に受信した `result` のもの）。
2. 接続が終了したら、再度サブスクライブします。レスポンスには、ジョブが終了したか、後続の実行に移行したか、フィードがまだないか、または再接続できるフィードがあるかが示されます。
3. もし `executionGeneration` が読み取っていたものと異なる場合、ジョブが再起動され、番号は0から振り直されています。最後の `seq` を破棄し、次の値を指定せずに接続します： `after`.
4. それ以外の場合は、次の値を指定して接続します： `after` に設定するのは、最後の `seq`.
5. 接続の開始間隔は少なくとも1秒空けてください。フィードが接続を拒否し続ける場合は、待機時間を長くしてください（例：1秒、2秒、4秒と増やし、最大30秒まで）。

フィードには、再生用に1回の実行の最新300件の結果が保持されます。ただし、結果の合計が4 MiBを超える場合は、それより少なくなります（毎秒30件の結果で約10秒分）。それより前から再開すると、最初に次のメッセージが送られます： `gap`.

## Pythonクライアント

この例では、1回サブスクライブして接続し、各メッセージを表示します。次のパッケージが必要です： `websockets` （`pip install websockets`）。次の値を設定します： `ROBOFLOW_API_KEY` 。また、次の値を置き換えます： `YOUR_WORKSPACE` と `JOB_ID`.

```python
import json
import os
import urllib.request

from websockets.sync.client import connect

url = "https://api.roboflow.com/YOUR_WORKSPACE/video-jobs/v1/JOB_ID/results/subscribe"
headers = {"Authorization": f"Bearer {os.environ['ROBOFLOW_API_KEY']}", "Content-Type": "application/json"}
request = urllib.request.Request(url, method="POST", data=b"{}", headers=headers)
grant = json.load(urllib.request.urlopen(request))

token = {"Authorization": f"Bearer {grant['accessToken']}"}
with connect(grant["eventsUrl"], additional_headers=token) as feed:
    for message in feed:
        print(message)
```

## Node.js クライアント

この例では、Node.js 18 以降と `ws` パッケージ（`npm install ws`).

```javascript
const WebSocket = require("ws");

const url = "https://api.roboflow.com/YOUR_WORKSPACE/video-jobs/v1/JOB_ID/results/subscribe";
const headers = { Authorization: `Bearer ${process.env.ROBOFLOW_API_KEY}`, "Content-Type": "application/json" };

fetch(url, { method: "POST", headers, body: "{}" })
  .then((response) => response.json())
  .then((grant) => {
    const token = { Authorization: `Bearer ${grant.accessToken}` };
    const feed = new WebSocket(grant.eventsUrl, { headers: token });
    feed.on("message", (message) => console.log(message.toString()));
  });
```

どちらの例も接続が終了すると停止し、ジョブにまだフィードがない場合はエラーになります。実行し続けるクライアントを作成するには、3 種類のサブスクリプション応答を処理し、 [再接続してジョブを追跡する](#reconnect-and-follow-the-job).

## 制限とセキュリティ

* 1 つのジョブが同時に提供できる結果サブスクライバーは最大 16 です。17 番目の接続は HTTP 429 で拒否されます。
* 各サブスクライバーには、結果を 200 件保持できるキューがあります。クライアントがさらに遅れると、取りこぼした結果の代わりに `gap` が届きます。ジョブがサブスクライバーに合わせて処理速度を落とすことはありません。
* `accessToken` はサブスクリプション応答から 10 分後に有効期限が切れます（`accessTokenExpiresAt`。Unix 時刻のミリ秒単位）。有効期限前に開かれた接続は、期限後も開いたままです。接続するたびに再度サブスクライブしてください。
* ジョブが新しい実行に移ると、トークンは使えなくなります。現在の実行用のトークンを取得するには、再度サブスクライブしてください。
* このトークンで利用できるのは結果のみです。フィードと `pollUrl`を開けます。ライブ動画、ジョブのステータス、結果ファイルを開くことはできず、ジョブを変更することもできません。
* 次の情報は `eventsUrl` と `accessToken` 認証情報として扱い、ログ、共有リンク、ソース管理に含めないでください。API キーをブラウザーに渡してはいけません。サーバーからサブスクライブしてください。
