BULK API 가이드 : 대용량 처리
Last updated
Was this helpful?
Last updated
Was this helpful?
BULK API 는 1일, 1회 10만건 이상, 즉 대용량 처리를 위해서 사용하는 API로 한번에 처리해야할 SKU가 많은 고객들께 사용을 권고 드립니다.
BULK API를 사용하고자 하시는 경우, 별도 API Key를 발급 받으셔야 합니다.
문의 : biz@omnious.com
POST endpoint: POST /bulk
Append endpoint: PUT /bulk/{status id}
Status endpoint: GET /bulk/{task id}/status
Result endpoint: GET /bulk/{task id}?offset=0&size=100
클라이언트는 다량의 이미지(1회 요청당 최대 1,000개)를 담아 요청을 보내고 서버로부터 202(Accepted) 상태코드와 TASK ID를 응답받습니다.
해당 TASK ID에 이미지를 추가하기 원하면 Append endpoint에 요청을 보냅니다.
클라이언트는 Status endpoint GET 요청을 보내 TASK의 상태 정보를 받습니다. "TASK_DONE" 값을 받아야 Result endpoint를 통해 태깅 결과를 확인할 수 있습니다.
클라이언트는 Result endpoint GET 요청을 보내 TASK의 태깅 결과(1회 요청당 최대 100개)를 받습니다.
TAGGER BULK API의 요청 URI 및 요청에 필요한 헤더 정보는 다음과 같습니다.
메서드
요청 URI
필요 헤더
POST
x-api-key : 인증을 위한 API Key [Required].
[HTTP Request Header]
POST /tagger/v2.12/bulk/HTTP/1.1 Host : api.omnious.com Content-Type: application/json x-api-key : {omnious로부터 발급받은 API Key}
[HTTP Request Body]
필드 이름
데이터 타입
설명
필수
albumName
string
요청 이미지들이 담길 앨범명 미지정 시 자동 생성
X
option
array
현재 지원하는 값: "STRICT"
STRICT: request validation 단계에서 taggingRequest에 담긴 값들 중 하나라도 실패할 시 전체 요청 실패.
X
defaultDetection
array
taggingRequest에 detection이 없을 경우 해당 값 자동으로 적용
default: ["TOP", "BOTTOM", "WHOLEBODY", "SWIMWEAR"] 사용 가능 값: TOP, BOTTOM, WHOLEBODY, SWIMWEAR, SHOES, BAG, HAT, JEWELRY, ACCESSORY
X
description
string
해당 task에 대한 설명(1,024자 까지)
X
taggingRequest
string
고객사에서 관리하는 상품에 대한 ID
O
taggingRequest[].image
object
요청할 이미지에 대한 타입과 해당 타입의 정보를 가지는 객체
O
taggingRequest[].image.type
string
요청 이미지에 대한 타입 현재 url type만 지원
O
taggingRequest[].image.content
string
요청 이미지의 타입별 정보
url 타입 : 요청 이미지의 URL 정보
O
taggingRequest[].context
object
추가적인 정보를 가지는 객체
O
taggingRequest[].context.id
string
요청 이미지의 아이디.
한 task 내에서 고유값을 가져야 함.
O
taggingRequest[].context.detection
Array[string]
value : TOP, BOTTOM, WHOLEBODY, SWIMWEAR, SHOES, BAG, HAT, JEWELRY, ACCESSORY
미지정시 defaultDetection값 적용.
의류만 태깅을 원할 때
detection: ["TOP", "BOTTOM", "WHOLEBODY", "SWIMWEAR"]
잡화만 태깅을 원할 때
detection : ["ACCESSORY"]
잡화는 일정 기간 동안 Beta 서비스로 제공
주얼리만 태깅을 원할 때
detection: [“JEWELRY”]
주얼리는 일정 기간 동안 Beta 서비스로 제공
모자 만 태깅을 원할 때
detection :["HAT"]
모자는 일정 기간 동안 Beta 서비스로 제공
가방 만 태깅을 원할 때
detection:["BAG"]
신발 만 태깅을 원할 때
detection:["SHOES"]
의류의 치마와 바지 종류만 태깅을 원할 때
detection: ["BOTTOM"]
의류 전체와 신발을 태깅하고 싶을
detection: ["TOP", "BOTTOM", "WHOLEBODY", "SWIMWEAR", "SHOES"]
의류 상의와 신발을 태깅하고 싶을
detection: ["TOP", "SHOES"]
모든 상품 (의류 전체와 모자, 가방, 신발)을 태깅하고 싶을
detection: ["TOP", "BOTTOM", "WHOLEBODY", "SWIMWEAR", "SHOES", "HAT", "BAG", "JEWELRY", "ACCESSORY"]
X
taggingRequest[].context.gender
string
상품에 대한 gender 정보
예시) 남성, 여성, 유니섹스
X
taggingRequest[].context.brand
string
상품의 브랜드 명
X
taggingRequest[].context.currency
string
통화 단위 (KRW)
예시) KRW 또는 USD
X
taggingRequest[].context.price
string
상품에 대한 가격
X
taggingRequest[].context.age
Array[string]
상품에 대한 주 구매 고객사의 연령대
예시) 10대, 20대초, 20대중후, 30대초, 30대중후, 40대, 50대이상
X
taggingRequest[].context.keywords
string
상품에 대한 키워드
예시) 여름 원피스, 원피스
X
taggingRequest[].context.productContentName
string
요청 이미지의 상품명
X
taggingRequest[].context.season
string
상품의 시즌 정보
예시) 19SS, 19FW, 20SS, 20FW
X
필드 이름
데이터 타입
설명
taskId
string
생성된 Task ID
albumName
string
요청 이미지들의 앨범명
taskExpiredAt
string
task 만료 시간
만료 이후 해당 task에 PUT 요청 불가능.
validation
object
validation 결과. validation 통과한 요만 tagging됨.
예시 ) 총 10장의 이미지 요청 중 2장이 validation 실패한다면 accept:8 failure:2
validation.accept
int
validation 성공한 요청 개수
validation.failure
int
validation 실패한 요청 개수
failureList
object
array
실패한 요청에 대한 정보 요청시 보냈던 데이터와 에러메세지 정보
failureList[].request
object
실패한 요청에 대한 정보
failureList[].request.image
object
실패한 요청 이미지 정보
failureList[].request.image.type
string
실패한 요청 이미지 타입
failureList[].request.image.content
string
실패한 요청 이미지 타입별 정보
url 타입 : 요청 이미지의 URL 정보
failureList[].request.context
object
실패한 요청 추가 정보
failureList[].request.context.id
string
실패한 요청 이미지 아이디
failureList[].request.context.detection
array
실패한 요청 이미지 detection 정보
failureList[].request.context.gender
string
실패한 요청 젠더 정보
failureList[].request.context.brand
string
실패한 요청 브랜드 정보
failureList[].request.context.currency
string
실패한 요청 통화 종류 정보
failureList[].request.context.price
string
실패한 요청 가격 정보
failureList[].request.context.age
Array[string]
실패한 요청 나이대 정보
failureList[].request.context.keywords
string
실패한 요청 키워드 정보
failureList[].request.context.productContentName
string
실패한 요청 상품명 정보
failureList[].request.context.season
string
실패한 요청 시즌 정보
failureList[].errorMessage
string
실패한 요청에 대한 에러 메세지
TASK에 이미지 태깅 요청을 추가합니다. 만료 시점 (taskExpireAt) 이후에는 추가할 수 없습니다. 만료 시점은 최초 TASK 생성 시간으로부터 10분이며, PUT요청 성공 시 10분 연장됩니다.
해당 API는 POST /bulk API와 동일하나, `description`, `albumName` 항목은 요청 시 입력하여도 생성 시 전달한 결과에서 변경되지 않습니다.
TAGGER BULK PUT API의 요청 URI 및 요청에 필요한 헤더 정보는 다음과 같습니다.
메서드
요청 URI
필요 헤더
PUT
x-api-key : 인증을 위한 API Key [Required]
task id: post 요청의 응답으로 제공 받은 TASK ID
[Required]
[HTTP Request Header]
PUT /tagger/v2.12/bulk/{task id} HTTP/1.1 Host : api.omnious.com Content-Type: application/json x-api-key : {omnious로부터 발급받은 API Key} task id: post 요청의 응답으로 제공 받은 TASK ID
[HTTP Request Body]
POST /bulk API와 동일
POST /bulk API와 동일
TAGGER BULK GET API의 요청 URI 및 요청에 필요한 헤더 정보는 다음과 같습니다.
메서드
요청 URI
필요 헤더
GET
x-api-key : 인증을 위한 API Key [Required]
[HTTP Request Header]
GET /tagger/v2.12/bulk/HTTP/1.1 Host : api.omnious.com Content-Type: application/json x-api-key : {omnious로부터 발급받은 API Key}
필드 이름
데이터 타입
설명
data
object
task 정보를 가진 객체
data.tasks
array
task 정보를 가진 객체 배열
data.tasks[].taskId
string
task 아이디
data.tasks[].count
int
task 내에 있는 요청 개수 정보
data.tasks[].count.total
int
task 내 전체 요청 개수
data.tasks[].count.done
int
task 내에 성공한 요청 개수
data.tasks[].count.processing
int
task 내에 진행중인 요청 개수
data.tasks[].count.failure
int
task 내에 실패한 요청 개수
data.tasks[].description
string
task에 대한 설명
(요청시 입력한 정보)
data.tasks[].taskStatus
string
task 현재 상태
value: TASK_PROCESSING, TASK_DONE
data.tasks[].taskExpireAt
string
task 만료 시
만료 이후 해당 task에 PUT 요청 불가능
data.tasks[].resultExpiredAt
string
task 결과 만료 시간
만료 시간 이후 해당 task 결과 열람 불가
data.tasks[].createDate
string
task 생성 시간
error
string
요청 에러 정보
status
string
요청 성공 실패 여부
TAGGER BULK TASK STATUS GET API의 요청 URI 및 요청에 필요한 헤더 정보는 다음과 같습니다.
메서드
요청 URI
필요 헤더
GET
https://api.omnious.com/tagger/v2.12/bulk/ {task id}/status
x-api-key : 인증을 위한 API Key [Required]
task id: post 요청의 응답으로 제공 받은 TASK ID
[Required]
[HTTP Request Header]
GET /tagger/v2.12/bulk/{task id}/status HTTP/1.1 Host : api.omnious.com Content-Type: application/json x-api-key : {omnious로부터 발급받은 API Key} task id: post 요청의 응답으로 제공 받은 TASK ID
필드 이름
데이터 타입
설명
data
object
task 정보를 가진 객체
data.taskId
string
task 아이디
data.count
int
task 내에 있는 요청 개수 정보
data.count.total
int
task 내 전체 요청 개수
data.count.done
int
task 내에 성공한 요청 개수
data.count.processing
int
task 내에 진행중인 요청 개수
data.count.failure
int
task 내에 실패한 요청 개수
data.description
string
task에 대한 설명
(요청시 입력한 정보)
data.taskStatus
string
task 현재 상태
value: TASK_PROCESSING, TASK_DONE
data.taskExpireAt
string
task 만료 시
만료 이후 해당 task에 PUT 요청 불가능
data.resultExpiredAt
string
task 결과 만료 시간
만료 시간 이후 해당 task 결과 열람 불가
data.createDate
string
task 생성 시간
error
string
요청 에러 정보
status
string
요청 성공 실패 여부
TAGGER BULK TASK RESULT GET API의 요청 URI 및 요청에 필요한 헤더 정보는 다음과 같습니다.
메서드
요청 URI
필요 헤더t
GET
https://api.omnious.com/tagger/v2.12/bulk/ {task id}?offset=0&size=100
x-api-key : 인증을 위한 API Key [Required]
task id: post 요청의 응답으로 제공 받은 TASK ID
[Required]
accept-language : tagging 결과를 받아볼 언어 선택
en: English (default)
ko: Korean
zh: Chinese
ja: Japanese
offset: task의 어느 부분에서 결과를 받을 것인지에 대한 정보(task엔 요청한 순서대로 결과가 저장됩니다.)
size: offset부터 몇 개나 받을 것인지에 대한 정보
[HTTP Request Header]
GET /tagger/v2.12/bulk/{task id}?offset=0&size=100 HTTP/1.1 Host : api.omnious.com Content-Type: application/json x-api-key : {omnious로부터 발급받은 API Key} accept-language : {언어 선택} task id: post 요청의 응답으로 제공 받은 TASK ID
task 내의 모든 이미지 태깅 처리가 끝나야 결과를 볼 수 있습니다.
필드 이름
데이터 타입
설명
data
object
task 결과 정보를 가진 객체
data.taskInfo
object
task 기본 정보를 가진 객체
data.taskInfo.totalCount
int
task 내에 총 요청 이미지
data.taskInfo.offset
int
결과 데이터 offset 정보
data.taskInfo.size
int
결과 데이터 size 정보
data.results
array
object
이미지 태깅 정보를 담은 객체 배
data.results[].id
string
이미지 아이디
data.results[].taggingResult
object
태깅 정보(SINGLE API의 응답과 동일)
