Recognition target 검색 | POST /v2/search
Image target을 검색하는, 이미지로 이미지를 검색하는 recognition interface입니다.
Action
POST /v2/search
인증
Http Header
Content-Type : multipart/form-data
Authorization (API Key Token 방식 인증을 사용하는 경우에만)
요청 파라미터
| Field | Type | Required | Description |
|---|---|---|---|
| image | Multipart | Yes | 이미지 내용의 base64 encoding 문자열이며, JPG 및 PNG 형식 이미지를 지원합니다. |
| notracking | String | No | "false"는 trackingImage 추적 이미지를 반환함을 의미합니다. "true"는 감지된 targetId 속성만 반환하고 tracking image는 반환하지 않음을 의미합니다. WebAR에서는 요청 지연을 줄이기 위해 기본적으로 포함하는 것을 권장합니다. |
Token 인증 요청 예시
curl -X POST -H "Authorization:xxx" --form "image=@trackingImage.jpg;type=image/jpg" --form appId=YOUR-APPID
https://<your-domain>-cn1.crs.easyar.com:8443/v2/search
Signature 인증 요청 예시
curl -X POST --form "image=@trackingImage;type=image/jpg"
--form apiKey=YOUR-APIKEY --form appId=YOUR-APPID
--form timestamp=1514736000000
--form signature=xxx
https://<your-domain>-cn1.crs.easyar.com:8443/v2/search
중요
- 반드시 Client-end-URL을 recognition entry로 사용해야 하며, https는 8443 포트입니다.
- http header에 Connection: Keep-Alive를 설정하여 반복 연결 비용을 최적화하십시오.
반환 필드
| Field | Description |
|---|---|
| statusCode | Status code 0은 인증이 올바름을 나타냅니다. 자세한 내용은 status code를 참고하십시오 |
| result | 오류 메시지 또는 target image 정보 |
| timestamp | response가 반환될 때의 서버 측 시간. 밀리초 단위의 Unix timestamp 형식을 사용합니다 |
| result.targetId | Target image의 고유 ID |
| result.trackingImage | Tracking image의 base64 encoding 문자열 |
| result.name | Target 이름 |
| result.size | Recognition image 너비(단위 cm). Recognition image의 높이는 업로드한 이미지에 따라 시스템이 자동 계산합니다. Recognition image의 크기는 중첩되는 virtual content의 크기에 대응합니다 |
| result.meta | base64로 인코딩된 추가 정보. 예: json 문자열을 base64 인코딩한 후 생성된 문자열 |
| result.type | ImageTarget으로 고정 |
| result.active | "1" 활성화, "0" 비활성화 |
주요 반환 코드
| Response | HTTPCODE | Status | Result |
|---|---|---|---|
| OK | 200 | 0 | result: { imageBody } |
| NO_RESULT | 404 | 17 | result: { message: "No result: there is no matching." } |
| NO_TARGET | 500 | 18 | result: { message: "Target not found: there is a matching but no target, please report this issue: IMAGE-UUID" } |
| TIMEOUT | 408 | 19 | result: { message: "Request timeout." } |
| OUT_OF_LIMIT | 402 | 21 | result: { message: "You have exceeded the limit of daily scanning." } |
| OUT_OF_QPS | 200 | 21 | result: { message: "Exceed your QPS limitation." } |
| RPC_ERROR | 500 | 20 | result: { message: "Error retrieving results." } |
| OTHER_ERROR | 501 | 30 | result: { message: "Other error occur: details" } |
오류 코드
Status code 및 error code 전체 목록을 참조하십시오.
요청 예시
POST /search/ HTTP/1.1
Host:
Date: Mon, 1 Jan 2018 00:00:00 GMT
Content-Type: application/json
{
"image":"/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAMCAgM...",
"timestamp": 1514736000000,
"appKey": "test_app_key",
"signature": "89985e2420899196db5bdf16b3c2ed0922c0c221"
}
응답 예시
- Recognition에 성공적으로 매칭된 경우 반환 구조는 다음과 같습니다.
HTTP/1.1 200 OK
Content-Type: application/json
{
"statusCode": 0,
"result": {
"target": {
"targetId":"e61db301-e80f-4025-b822-9a00eb48d8d2",
"trackingImage":"/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAMCAgM..."，
"name": "easyar",
"size": "5",
"meta": "496fbbabc2b38ecs3460a...",
"type": "ImageTarget",
"modified":1514735000000
"active":"1"，
"trackableRate": 0,
"detectableRate": 0,
"detectableDistinctiveness"：0,
"detectableFeatureCount": 0,
"trackableDistinctiveness": 0,
"trackableFeatureCount": 0,
"trackableFeatureDistribution": 0,
"trackablePatchContrast": 0,
"trackablePatchAmbiguity": 0
}
},
"timestamp": 1514736000000
}
- 일치하는 target image가 없는 경우 반환 예시는 다음과 같습니다.
HTTP/1.1 404 NOT FOUND
Content-Type: application/json
{
"statusCode": 17,
"result": {
"message": "No result: there is no matching."
}
}