> 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/roboflow/roboflow-jp/deploy/batch-processing/cli-usage.md).

# CLI の使い方

をインストールすることで `inference-cli` 、次にアクセスできます `inference rf-cloud` コマンドにより、Batch Processing と Data Staging を操作できます — これらは Roboflow Batch Processing の中核コンポーネントです。

## セットアップ

```bash
pip install inference-cli
export ROBOFLOW_API_KEY="YOUR-API-KEY-GOES-HERE"
```

クラウドストレージをサポートするには:

```bash
pip install 'inference-cli[cloud-storage]'
```

APIキーの見つけ方が必要な場合は、 [認証ガイド](https://docs.roboflow.com/api-reference/authentication).

## データを取り込む

### 画像

```bash
inference rf-cloud data-staging create-batch-of-images \\
  --images-dir <your-images-dir-path> \\
  --batch-id <your-batch-id>
```

### 動画

```bash
inference rf-cloud data-staging create-batch-of-videos \\
  --videos-dir <your-videos-dir-path> \\
  --batch-id <your-batch-id>
```

{% hint style="info" %}
**Batch ID 形式:** 小文字で、最大64文字、使用できるのは英字、数字、ハイフン（`-`）、およびアンダースコア（`_`).
{% endhint %}

### Cloud Storage

データがすでに cloud storage（S3、Google Cloud Storage、Azure）にある場合、ファイルをローカルにダウンロードせずに直接処理できます。

**画像の場合:**

```bash
inference rf-cloud data-staging create-batch-of-images \\
  --data-source cloud-storage \\
  --bucket-path <cloud-path> \\
  --batch-id <your-batch-id>
```

**動画の場合:**

```bash
inference rf-cloud data-staging create-batch-of-videos \\
  --data-source cloud-storage \\
  --bucket-path <cloud-path> \\
  --batch-id <your-batch-id>
```

この `--bucket-path` パラメータは次をサポートします:

* **S3**: `s3://bucket-name/path/`
* **Google Cloud Storage**: `gs://bucket-name/path/`
* **Azure Blob Storage**: `az://container-name/path/`

ファイルを絞り込むために glob パターンを含めることができます:

* `s3://my-bucket/training-data/**/*.jpg` — 再帰的にすべての JPG ファイル
* `gs://my-bucket/videos/2024-*/*.mp4` — 2024-\* フォルダ内の MP4 ファイル
* `az://container/images/*.png` — images フォルダ内の PNG ファイル

{% hint style="info" %}
クラウドストレージの認証情報は **CLI によって署名付きURLを生成するために** ローカルでのみ使用されます。それらは **決してアップロードされません** Roboflow サーバーへ。
{% endhint %}

{% hint style="warning" %}
生成された署名付きURLは24時間有効です。この時間内にバッチ処理ジョブが完了するようにしてください。
{% endhint %}

大規模データセットでは、システムが画像を自動的に20,000ファイルずつのチャンクに分割します。動画は1,000未満のバッチで最も適しています。

### 署名付き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>"}
```

{% hint style="info" %}
署名付きURLによる取り込みは、Growth Plan と Enterprise のお客様が利用できます。
{% endhint %}

## ステージ済みデータを確認

```bash
inference rf-cloud data-staging show-batch-details --batch-id <your-batch-id>
```

## ジョブを開始

### 画像を処理

```bash
inference rf-cloud batch-processing process-images-with-workflow \\
  --workflow-id <workflow-id> \\
  --batch-id <batch-id> \\
  --machine-type gpu
```

### 動画を処理

```bash
inference rf-cloud batch-processing process-videos-with-workflow \\
  --workflow-id <workflow-id> \\
  --batch-id <batch-id> \\
  --machine-type gpu \\
  --max-video-fps <your-desired-fps>
```

{% hint style="info" %}
**Workflow ID の見つけ方:** Roboflow App で Workflow Editor を開き、「Deploy」をクリックして、コードスニペット内の識別子を見つけます。
{% endhint %}

{% hint style="info" %}
デフォルトでは、処理はCPUで実行されます。 `--machine-type gpu` 複数のモデルや大規模モデルを含むWorkflowで使用してください。
{% endhint %}

## ジョブの進行状況を監視

開始コマンドは **Job ID**を出力します。ステータスの確認に使用してください:

```bash
inference rf-cloud batch-processing show-job-details --job-id <your-job-id>
```

## 結果をエクスポート

ジョブ詳細には **出力 batch ID**が含まれます。結果のエクスポートに使用してください:

```bash
inference rf-cloud data-staging export-batch \\
  --target-dir <dir-to-export-result> \\
  --batch-id <output-batch-of-a-job>
```

## Webhook 自動化

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

### データ取り込み Webhooks

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

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

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

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

```json
{
    "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": "信頼できないドメインが見つかりました: https://example.com/image.png"
        }
    },
    "delivery_attempt": 1
}
```

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

```json
{
    "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
}
```

### ジョブ完了 Webhooks

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

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

#### ジョブ完了通知

```json
{
  "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
}
```

## Cloud Storage 認証

### AWS S3 と S3互換ストレージ

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

1. **環境変数:**

```bash
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
```

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

**名前付きプロファイル:**

```bash
export AWS_PROFILE=production
```

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

```bash
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

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

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

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

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

### Azure Blob Storage

**SAS トークン（推奨）:**

```bash
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"
```

**アカウントキー:**

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

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

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

### カスタムスクリプト

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

* **AWS S3:** [generateS3SignedUrls.sh](https://raw.githubusercontent.com/roboflow/roboflow-python/main/scripts/generateS3SignedUrls.sh)
* **Google Cloud Storage:** [generateGCSSignedUrls.sh](https://github.com/roboflow/roboflow-python/blob/main/scripts/generateGCSSignedUrls.sh)
* **Azure Blob Storage:** [generateAzureSasUrls.sh](https://raw.githubusercontent.com/roboflow/roboflow-python/main/scripts/generateAzureSasUrls.sh)

## すべてのオプションを確認

```bash
inference rf-cloud --help
inference rf-cloud data-staging --help
inference rf-cloud batch-processing --help
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.roboflow.com/roboflow/roboflow-jp/deploy/batch-processing/cli-usage.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.