Table of Contents

Поиск и распознавание цели| POST /v2/search

Поиск изображений цели, интерфейс распознавания по изображению.

Действие

POST /v2/search

Аутентификация

Требуется

Http-заголовок

Content-Type : multipart/form-data

Authorization (только при аутентификации с помощью API Key Token)

Параметры запроса

Поле Тип Обязательно Описание
image Multipart Да Строка в кодировке base64 с содержимым изображения. Поддерживаются форматы JPG и PNG.
notracking String Нет "false" — возвращает trackingImage (отслеживаемое изображение). "true" — возвращает только обнаруженное свойство targetId без отслеживаемого изображения. Для WebAR рекомендуется передавать для снижения задержки запроса.

Пример запроса с аутентификацией по токену

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

Пример запроса с аутентификацией по подписи

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 как точку входа для распознавания, https использует порт 8443
  • Установите в http-заголовке Connection: Keep-Alive для оптимизации затрат на повторные подключения

Возвращаемые поля

Поле Описание
statusCode Код состояния: 0 означает корректную аутентификацию. Подробнее см. Коды состояния
result Сообщение об ошибке или информация о целевой картинке
timestamp Время на сервере при возврате ответа. В формате Unix timestamp (миллисекунды)
result.targetId Уникальный ID целевой картинки
result.trackingImage Строка в кодировке base64 с отслеживаемым изображением
result.name Название цели
result.size Ширина распознаваемой картинки (в см). Высота будет автоматически рассчитана системой на основе загруженного изображения. Размер распознаваемой картинки соответствует размеру накладываемого виртуального контента
result.meta Дополнительная информация в кодировке base64, например строка, сгенерированная после кодирования json-строки в base64
result.type Фиксированное значение: ImageTarget
result.active "1" — активно, "0" — отключено

Основные коды возврата

Ответ HTTP-код Статус Результат
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" }

Коды ошибок

См. Полный список кодов состояния и ошибок

Пример запроса

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

Пример ответа

  • При успешном распознавании возвращается структура:

    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
    }
  • Если совпадений не найдено:

    HTTP/1.1 404 NOT FOUND
    Content-Type: application/json
    {
      "statusCode": 17,
      "result": {
        "message": "No result: there is no matching."
      }
    }