統合と自動化

API、webhook、クラウドストレージ連携で Batch Processing を自動化します。

Batch Processing は、タスクの自動化に適しており、特に処理を定期的に実行する必要がある場合に向いています。このページでは、API と webhook を使用して Roboflow Batch Processing を外部システムと統合する方法を説明します。

概要

一般的な Batch Processing パイプラインは次の要素で構成されます:

データ取り込み — データを Data Staging（入力データと出力データの一時ストレージ）にアップロードします。
処理 — 取り込まれたデータに対して Workflow を実行し、CSV/JSONL の結果を生成します。これに続いて通常は export ステージがあり、圧縮アーカイブを作成して簡単に展開できるようにします。
データのエクスポート — ダウンロードリンクを使用して出力バッチから結果をダウンロードします。

API リファレンス

すべての CLI コマンドには同等の REST API エンドポイントがあります。以下に主要な API 操作を示します。

動画の取り込み

curl -X POST "https://api.roboflow.com/data-staging/v1/external/{workspace}/batches/{batch_id}/upload/video" \
  -G \
  --data-urlencode "api_key=YOUR_API_KEY" \
  --data-urlencode "fileName=your_video.mp4"

レスポンスには "signedURLDetails" が含まれており、内容は次のとおりです:

"uploadURL" — 動画を PUT するための URL
"extensionHeaders" — 追加で含めるヘッダー

動画をアップロードします:

curl -X PUT <url-from-the-response> \
  -H "Name: value" \
  --upload-file <path-to-your-video>

すべてのヘッダーを "extensionHeaders" レスポンスの field から含めてください。

画像の取り込み

単一画像アップロード

最大 5,000 枚までのバッチに最適です。同じバッチで一括アップロードと併用することはできません。

curl -X POST "https://api.roboflow.com/data-staging/v1/external/{workspace}/batches/{batch_id}/upload/image" \
  -G \
  --data-urlencode "api_key=YOUR_API_KEY" \
  --data-urlencode "fileName=your_image.jpg" \
  -F "your_image.jpg=@/path/to/your/image.jpg"

一括アップロード

5,000 枚を超える画像のバッチに推奨されます。1 つの *.tar アーカイブに最大 500 枚の画像をまとめます。

アップロード URL を要求します:

curl -X POST "https://api.roboflow.com/data-staging/v1/external/{workspace}/batches/{batch_id}/bulk-upload/image-files" \
  -G \
  --data-urlencode "api_key=YOUR_API_KEY"

画像を *.tar アーカイブにまとめ、API が返すサイズおよびファイル数の制限に従います。
レスポンスの署名付き URL と拡張ヘッダーを使用してアーカイブをアップロードします。

一括アップロードのバッチと、同じバッチでの単一画像アップロードは混在できません。

一括取り込みを行う場合、データはバックグラウンドでインデックス化されます。すべてのデータが利用可能になるまで少し遅延する場合があります。

バッチのステータスを確認

ジョブを開始する前に、すべてのデータが取り込まれていることを確認してください:

curl -X GET "https://api.roboflow.com/data-staging/v1/external/{workspace}/batches/{batch_id}/count" \
  -G \
  --data-urlencode "api_key=YOUR_API_KEY"

シャードのアップロード詳細を確認するには（ページネーションあり）:

curl -X GET "https://api.roboflow.com/data-staging/v1/external/{workspace}/batches/{batch_id}/shards" \
  -G \
  --data-urlencode "api_key=YOUR_API_KEY" \
  --data-urlencode "nextPageToken=OptionalNextPageToken"

ジョブを開始

curl -X POST "https://api.roboflow.com/batch-processing/v1/external/{workspace}/jobs/{job_id}?api_key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "simple-image-processing-v1",
    "jobInput": {
        "type": "staging-batch-input-v1",
        "batchId": "{batch_id}"
    },
    "computeConfiguration": {
        "type": "compute-configuration-v2",
        "machineType": "cpu",
        "workersPerMachine": 4
    },
    "processingTimeoutSeconds": 3600,
    "processingSpecification": {
        "type": "workflows-processing-specification-v1",
        "workspace": "{workspace}",
        "workflowId": "{workflow_id}",
        "aggregationFormat": "jsonl"
    }
}'

ジョブ ID の制約: 小文字の英字、数字、ハイフン、アンダースコアのみ。最大 20 文字。

ジョブのステータスを監視

一般的なジョブのステータス:

curl -X GET "https://api.roboflow.com/batch-processing/v1/external/{workspace}/jobs/{job_id}" \
  -G \
  --data-urlencode "api_key=YOUR_API_KEY"

ジョブのステージを一覧表示:

curl -X GET "https://api.roboflow.com/batch-processing/v1/external/{workspace}/jobs/{job_id}/stages" \
  -G \
  --data-urlencode "api_key=YOUR_API_KEY"

ステージのタスクを一覧表示（ページネーションあり）:

curl -X GET "https://api.roboflow.com/batch-processing/v1/external/{workspace}/jobs/{job_id}/stages/{stage_id}/tasks" \
  -G \
  --data-urlencode "api_key=YOUR_API_KEY" \
  --data-urlencode "nextPageToken={next_page_token}"

結果をエクスポート

出力バッチのパーツを一覧表示:

curl -X GET "https://api.roboflow.com/data-staging/v1/external/{workspace}/batches/{batch_id}/parts" \
  -G \
  --data-urlencode "api_key=YOUR_API_KEY"

パーツのダウンロード URL を一覧表示（ページネーションあり）:

curl -X GET "https://api.roboflow.com/data-staging/v1/external/{workspace}/batches/{batch_id}/list" \
  -G \
  --data-urlencode "api_key=YOUR_API_KEY" \
  --data-urlencode "nextPageToken=YOUR_NEXT_PAGE_TOKEN" \
  --data-urlencode "partName=YOUR_PART_NAME"

ファイルをダウンロード:

curl <download-url> -o <download-file-location>

Data Staging のバッチタイプ

シンプルバッチ (type: simple-batch）— データを 1 件ずつ取り込むときに作成されます。最大 5,000〜10,000 件に最適です。
シャードバッチ (type: sharded-batch）— 一括取り込み（画像のみ）で作成されます。自動シャーディングにより、数百万件のデータポイント向けに設計されています。
マルチパートバッチ (type: multipart-batch）— システムによって内部的に作成されます。サブバッチを 1 つのエンティティとして管理する論理的なグループです。

Webhook 自動化

ステータスをポーリングする代わりに、取り込みや処理が完了したときに通知を受け取るために webhook を使用できます。

データ取り込み Webhook

CLI コマンド create-batch-of-images および create-batch-of-videos は次をサポートします:

--notifications-url <webhook_url> — 通知用の webhook エンドポイント。
--notification-category <value> — 通知をフィルタリング:
- ingest-status （デフォルト）— 取り込みプロセス全体のステータス。
- files-status — 個々のファイル処理ステータス。

通知は、 Authorization ヘッダーに Roboflow Publishable Key を含めた HTTP POST で配信されます。

取り込みステータス通知

{
    "type": "roboflow-data-staging-notification-v1",
    "event_id": "8c20f970-fe10-41e1-9ef2-e057c63c07ff",
    "ingest_id": "8cd48813430f2be70b492db67e07cc86",
    "batch_id": "test-batch-117",
    "shard_id": null,
    "notification": {
        "type": "ingest-status-notification-v1",
        "success": false,
        "error_details": {
            "type": "unsafe-url-detected",
            "reason": "Untrusted domain found: https://example.com/image.png"
        }
    },
    "delivery_attempt": 1
}

ファイルステータス通知

{
    "type": "roboflow-data-staging-notification-v1",
    "event_id": "8f42708b-aeb7-4b73-9d83-cf18518b6d81",
    "ingest_id": "d5cb69aa-b2d1-4202-a1c1-0231f180bda9",
    "batch_id": "prod-batch-1",
    "shard_id": "0d40fa12-349e-439f-83f8-42b9b7987b33",
    "notification": {
        "type": "ingest-files-status-notification-v1",
        "success": true,
        "ingested_files": [
            "000000494869.jpg",
            "000000186042.jpg"
        ],
        "failed_files": [
            {
                "type": "file-size-limit-exceeded",
                "file_name": "big_image.png",
                "reason": "単一画像の最大サイズは 20971520B です。"
            }
        ],
        "content_truncated": false
    },
    "delivery_attempt": 1
}

ジョブ完了 Webhook

追加 --notifications-url をジョブ開始時に指定します:

inference rf-cloud batch-processing process-images-with-workflow \
  --workflow-id <workflow-id> \
  --batch-id <batch-id> \
  --notifications-url <webhook_url>

ジョブ完了通知

{
  "type": "roboflow-batch-job-notification-v1",
  "event_id": "8f42708b-aeb7-4b73-9d83-cf18518b6d81",
  "job_id": "<your-batch-job-id>",
  "job_state": "success | fail",
  "delivery_attempt": 1
}

署名付き URL による取り込み

高度な自動化では、ローカルファイルの代わりに署名付き URL を介してデータを取り込むことができます:

--data-source references-file — 署名付き URL で参照されたファイルを処理します。
--references <path_or_url> — ファイル URL を含む JSONL ファイルへのパス、またはそのファイルを指す署名付き URL。

参照ファイル形式（JSONL）

{"name": "<unique-file-name-1>", "url": "https://<signed-url>"}
{"name": "<unique-file-name-2>", "url": "https://<signed-url>"}

署名付き URL による取り込みは、Growth Plan および Enterprise のお客様が利用できます。

クラウドストレージ認証

AWS S3 と S3 互換ストレージ

認証情報は次から自動的に検出されます:

環境変数:

export AWS_ACCESS_KEY_ID=your-access-key-id
export AWS_SECRET_ACCESS_KEY=your-secret-access-key
export AWS_SESSION_TOKEN=your-session-token  # Optional

AWS 認証情報ファイル (~/.aws/credentials, ~/.aws/config)
IAM ロール (EC2, ECS, Lambda)

名前付きプロファイル:

export AWS_PROFILE=production

S3 互換サービス（Cloudflare R2、MinIO など）:

export AWS_ENDPOINT_URL=https://account-id.r2.cloudflarestorage.com
export AWS_REGION=auto  # R2 requires region='auto'
export AWS_ACCESS_KEY_ID=your-r2-access-key
export AWS_SECRET_ACCESS_KEY=your-r2-secret-key

Google Cloud Storage

認証情報は次から検出されます:

サービスアカウントキーファイル （自動化に推奨）:

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json

ユーザー認証情報 gcloud CLI から (gcloud auth login)
GCP メタデータサービス （Google Cloud Platform 上で実行している場合）

Azure Blob Storage

SAS トークン（推奨）:

export AZURE_STORAGE_ACCOUNT_NAME=mystorageaccount
export AZURE_STORAGE_SAS_TOKEN="sv=2021-06-08&ss=b&srt=sco&sp=rl&se=2024-12-31"

アカウントキー:

export AZURE_STORAGE_ACCOUNT_NAME=mystorageaccount
export AZURE_STORAGE_ACCOUNT_KEY=your-account-key

Azure CLI で SAS トークンを生成します:

az storage container generate-sas \
  --account-name mystorageaccount \
  --name my-container \
  --permissions rl \
  --expiry 2024-12-31T23:59:59Z

カスタムスクリプト

高度なユースケースでは、署名付き URL ファイルを生成するためのスクリプトを参照してください:

AWS S3: generateS3SignedUrls.sh
Google Cloud Storage: generateGCSSignedUrls.sh
Azure Blob Storage: generateAzureSasUrls.sh

PreviousCLI の使い方 Nextトラブルシューティング

Last updated 16 hours ago

Was this helpful?

hashtag概要

hashtagAPI リファレンス

hashtag動画の取り込み

hashtag画像の取り込み

hashtag単一画像アップロード

hashtag一括アップロード

hashtagバッチのステータスを確認

hashtagジョブを開始

hashtagジョブのステータスを監視

hashtag結果をエクスポート

hashtagData Staging のバッチタイプ

hashtagWebhook 自動化

hashtagデータ取り込み Webhook

hashtag取り込みステータス通知

hashtagファイルステータス通知

hashtagジョブ完了 Webhook

hashtagジョブ完了通知

hashtag署名付き URL による取り込み

hashtag参照ファイル形式（JSONL）

hashtagクラウドストレージ認証

hashtagAWS S3 と S3 互換ストレージ

hashtagGoogle Cloud Storage

hashtagAzure Blob Storage

hashtagカスタムスクリプト

概要

API リファレンス

動画の取り込み

画像の取り込み

単一画像アップロード

一括アップロード

バッチのステータスを確認

ジョブを開始

ジョブのステータスを監視

結果をエクスポート

Data Staging のバッチタイプ

Webhook 自動化

データ取り込み Webhook

取り込みステータス通知

ファイルステータス通知

ジョブ完了 Webhook

ジョブ完了通知

署名付き URL による取り込み

参照ファイル形式（JSONL）

クラウドストレージ認証

AWS S3 と S3 互換ストレージ

Google Cloud Storage

Azure Blob Storage

カスタムスクリプト