통합 및 자동화

API, webhook, 클라우드 스토리지 통합으로 Batch Processing을 자동화하세요.

Batch Processing은 작업 자동화에 적합하며, 특히 프로세스가 반복적으로 실행되어야 할 때 유용합니다. 이 페이지에서는 API와 webhook을 사용해 Roboflow Batch Processing을 외부 시스템과 통합하는 방법을 다룹니다.

개요

일반적인 Batch Processing 파이프라인은 다음으로 구성됩니다:

1. 데이터 수집 — 데이터를 Data Staging(입력 및 출력 데이터용 임시 저장소)에 업로드합니다).

2. 처리 — 수집된 데이터에 대해 Workflow를 실행하여 CSV/JSONL 결과를 생성합니다. 일반적으로 이어서 export 압축 아카이브를 만들어 쉽게 추출할 수 있게 하는 단계가 뒤따릅니다.

3. 데이터 내보내기 — 다운로드 링크를 통해 출력 배치에서 결과를 다운로드합니다.

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" 응답 필드

이미지 수집

단일 이미지 업로드

최대 5,000장의 이미지 배치에 적합합니다. 같은 배치에 대해 bulk upload와 함께 사용할 수 없습니다.

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"

Bulk Upload

5,000장을 초과하는 배치에 권장됩니다. 배치당 최대 500장의 이미지를 *.tar 아카이브로 묶을 수 있습니다.

1. 업로드 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"

1. 이미지를 *.tar 아카이브로 묶고 API가 반환한 크기 및 파일 수 제한을 따르세요.

2. 응답의 signed URL과 extension headers를 사용해 아카이브를 업로드합니다.

bulk-upload 배치는 같은 배치의 단일 이미지 업로드와 섞어서 사용할 수 없습니다.

bulk 수집을 수행할 때 데이터는 백그라운드에서 인덱싱됩니다. 모든 데이터를 사용할 수 있게 되기까지 잠시 지연될 수 있습니다.

배치 상태 확인

작업을 시작하기 전에 모든 데이터가 수집되었는지 확인하세요:

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) — 데이터를 한 번에 하나씩 수집할 때 생성됩니다. 최대 5,000~10,000개 항목에 적합합니다.

• 샤딩 배치 (type: sharded-batch) — bulk 수집을 통해 생성됩니다(이미지만). 자동 샤딩으로 수백만 개의 데이터 포인트를 처리하도록 설계되었습니다.

• 멀티파트 배치 (type: multipart-batch) — 시스템이 내부적으로 생성합니다. 하위 배치들을 하나의 엔터티로 관리하는 논리적 그룹입니다.

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가 포함됩니다.

수집 상태 알림

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

Signed URL 수집

고급 자동화의 경우, 로컬 파일 대신 signed URL을 통해 데이터를 수집할 수 있습니다:

• --data-source references-file — signed URL로 참조되는 파일을 처리합니다.

• --references <path_or_url> — 파일 URL이 포함된 JSONL 파일 경로나, 해당 파일을 가리키는 signed URL 경로입니다.

참조 파일 형식(JSONL)

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

Signed URL 수집은 Growth Plan 및 Enterprise 고객에게 제공됩니다.

클라우드 스토리지 인증

AWS S3 및 S3 호환 스토리지

자격 증명은 다음에서 자동 감지됩니다:

1. 환경 변수:

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  # 선택 사항

1. AWS 자격 증명 파일 (~/.aws/credentials, ~/.aws/config)

2. 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는 region='auto'가 필요합니다
export AWS_ACCESS_KEY_ID=your-r2-access-key
export AWS_SECRET_ACCESS_KEY=your-r2-secret-key

Google Cloud Storage

자격 증명은 다음에서 감지됩니다:

1. 서비스 계정 키 파일 (자동화에 권장):

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

1. 사용자 자격 증명 gcloud CLI에서 (gcloud auth login)

2. 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

사용자 정의 스크립트

고급 사용 사례의 경우, signed URL 파일 생성을 위한 스크립트를 참조하세요:

• AWS S3: generateS3SignedUrls.sh

• Google Cloud Storage: generateGCSSignedUrls.sh

• Azure Blob Storage: generateAzureSasUrls.sh