Table of Contents

Введение в API cloud recognition

Список API

Протокол интерфейса REST API и механизм аутентификации

CRS API следует стандартному транспортному стандарту HTTP REST.

Http Header

    Authorization: <укажите Token, полученный из APIKey>

Параметры Http-запроса делятся на два типа:

  • Общие параметры (включают все перечисленное; разные способы аутентификации используют разные комбинации):

    • appId
    • timestamp (длинное целое Long: количество миллисекунд, прошедших с 00:00:00 UTC 1 января 1970 года)
    • apiKey
    • signature (подпись запроса, альтернатива token-аутентификации)

  • Параметры CRS API: собственные параметры API

    Документация API больше не описывает общие параметры, используемые для аутентификации

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

Способы аутентификации делятся на два типа:

Аутентификация на основе Token

Http header Authorization содержит Token. Общие параметры включают:

  • appId

Аутентификация с подписью

Http header Authorization не используется.

Общие параметры содержат информацию signature. Все параметры участвуют в расчете подписи, кроме изображений.

  • appId
  • timestamp
  • apiKey
  • signature

Подробный алгоритм и код расчета подписи см. в документе метод подписи API Key.

Примеры использования и разбор свойств

Пример использования API

В этом примере вызывается API для создания target image, чтобы помочь разработчикам понять процесс запроса CRS API, структуру свойств target image, а также входные и выходные данные интерфейса.

В production-среде перед созданием target image требуется больше проверок. Подробнее см. best practices для создания нового target image.

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

Добавьте файл target image с именем test-target.jpg. При создании target image файл изображения должен быть закодирован в base64.

В документации API подробно описываются параметры запроса. См. API - Создать target image, чтобы отправить запрос API с файлом изображения, закодированным в base64.

POST /targets HTTP/1.1
Host:
Date: Mon, 1 Jan 2018 00:00:00 GMT
Content-Type: application/json
{
    "image":"/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAMCAgM...",
    "active":"1",
    "name":"easyar",
    "size":"5",
    "meta":"496fbbabc2b38ecs3460a...",
    "type":"ImageTarget",
    "timestamp": 1514736000000,
    "apiKey": "8b485c648c3056e79c2a85ee9b51f9dc",
    "appId": "C:CN1:f9f903c36da8bd64d71d491077bba...",
    "signature": "89985e2420899196db5bdf16b3c2ed0922c0c221"
}

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

HTTP/1.1 200 OK
Content-Type: application/json
{
    "statusCode": 0,
    "result": {
        "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
}

Формат ответа

Все ответы используют единый формат. Ниже приведен пример:

{
  "statusCode": 119,
  "msg": "Parameter has errors",
  "date": "2022-06-15T09:56:30.000Z",
  "result":  //result есть только когда statusCode равен 0. При ошибке поле результата пустое
}

Как показано в примере выше, это нормальная структура возвращаемых сведений о target image. Target image включает следующие свойства.

Свойство Описание
targetId Уникальный Id target image
trackingImage Base64-кодирование обработанного изображения в градациях серого, используется для image tracking на стороне устройства
name Имя target image
size Размер изображения, практический размер для наложения виртуального контента в приложении
meta Пользовательские связанные данные; могут быть файлом, текстом или url и должны быть закодированы в base64
type "ImageTarget"
active Распознаются только включенные target image. После отключения они распознаваться не будут
trackableRate Оценка сложности tracking. Чем меньше, тем лучше
detectableRate Общая оценка сложности recognition. Чем меньше, тем лучше
detectableDistinctiveness Оценка сложности различимости recognition. Чем меньше, тем лучше
detectableFeatureCount Оценка сложности признаков recognition. Чем меньше, тем лучше
trackableDistinctiveness Оценка сложности различимости tracking. Чем меньше, тем лучше
trackableFeatureCount Оценка сложности признаков tracking. Чем меньше, тем лучше
trackableFeatureDistribution Оценка сложности распределения признаков tracking. Чем меньше, тем лучше

Коды ошибок

Описание кодов ошибок cloud recognition APIs

Связанные темы