# CLI の使用方法

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

## セットアップ

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

クラウドストレージのサポートを利用する場合:

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

API キーの確認方法についてサポートが必要な場合は、こちらをご覧ください [authentication guide](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 %}

### クラウドストレージ

データがすでにクラウドストレージ（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 時間です。batch processing job がこの時間内に完了するようにしてください。
{% 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` 複数または大規模なモデルを含む Workflows の場合。
{% endhint %}

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

start コマンドは **Job ID**を出力します。これを使ってステータスを確認します:

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

## 結果をエクスポートする

ジョブの詳細には **output batch ID**が含まれます。これを使って結果をエクスポートします:

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

## Webhook 自動化

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

### データ取り込み Webhook

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

### ジョブ完了 Webhook

追加する `--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
}
```

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

### 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  # オプション
```

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 では 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 Token（推奨）:**

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

**Account Key:**

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