Table of Contents

Introdução às APIs de cloud recognition

Lista de APIs

Protocolo de interface REST API e mecanismo de autenticação

CRS API segue o padrão de transporte HTTP REST.

Http Header

    Authorization:

Parâmetros de request Http, divididos em dois tipos:

  • Parâmetros comuns (incluem todos estes; métodos de autenticação diferentes usam combinações diferentes):

    • appId
    • timestamp (inteiro Long: milissegundos decorridos desde 00:00:00 UTC de 1 de janeiro de 1970)
    • apiKey
    • signature (assinatura do request, alternativa à autenticação por token)

  • Parâmetros CRS API: parâmetros da própria API

    A documentação da API não descreve mais os parâmetros comuns usados para autenticação

Autenticação API Key

Os métodos de autenticação são divididos em dois tipos:

Autenticação baseada em Token

O Http header Authorization contém o Token. Os parâmetros comuns incluem:

  • appId

Autenticação por signature

Não se usa Http header Authorization.

Os parâmetros comuns contêm informações de signature. Todos os parâmetros entram no cálculo da assinatura, exceto imagens.

  • appId
  • timestamp
  • apiKey
  • signature

Para o algoritmo detalhado e o código de cálculo da assinatura, consulte método de signature de API Key.

Exemplos de uso e análise de propriedades

Exemplo de uso da API

Este exemplo chama uma API para criar uma target image, ajudando desenvolvedores a entender o processo de request da CRS API, a estrutura de propriedades da target image e a entrada e saída da interface.

Em ambiente de produção, são necessárias mais validações antes de criar uma target image. Para detalhes, consulte as best practices para criar uma nova target image.

Exemplo de request

Adicione um arquivo de target image chamado test-target.jpg. Ao criar uma target image, o arquivo de imagem deve ser codificado em base64.

A documentação da API descreve detalhadamente os parâmetros de request. Consulte API - Criar target image para solicitar a API com o arquivo de imagem codificado em 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"
}

Exemplo de resposta

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
}

Formato da resposta

Todas as respostas usam um formato unificado. Veja um exemplo:

{
  "statusCode": 119,
  "msg": "Parameter has errors",
  "date": "2022-06-15T09:56:30.000Z",
  "result":  //result existe somente quando statusCode é 0. Se ocorrer erro, o campo de resultado fica vazio
}

Como mostrado no exemplo acima, esta é a estrutura normal retornada de detalhes da target image. Uma target image inclui as seguintes propriedades.

Propriedade Descrição
targetId Id único da target image
trackingImage Codificação base64 da imagem em escala de cinza processada, usada para image tracking no lado do dispositivo
name Nome da target image
size Tamanho da imagem, o tamanho prático usado para sobrepor conteúdo virtual no aplicativo
meta Dados associados pelo usuário, que podem ser arquivo, texto ou url e precisam ser codificados em base64
type "ImageTarget"
active Somente target images ativadas podem ser reconhecidas. Após serem desativadas, não serão reconhecidas
trackableRate Pontuação de dificuldade de tracking. Quanto menor, melhor
detectableRate Pontuação de dificuldade geral de recognition. Quanto menor, melhor
detectableDistinctiveness Pontuação de dificuldade de distinção da recognition. Quanto menor, melhor
detectableFeatureCount Pontuação de dificuldade de features de recognition. Quanto menor, melhor
trackableDistinctiveness Pontuação de dificuldade de distinção do tracking. Quanto menor, melhor
trackableFeatureCount Pontuação de dificuldade de features de tracking. Quanto menor, melhor
trackableFeatureDistribution Pontuação de dificuldade de distribuição de features de tracking. Quanto menor, melhor

Códigos de erro

Descrição dos códigos de erro das cloud recognition APIs

Tópicos relacionados