Obter e usar chave de API

Na EasyAR Developer Center, criar chaves de API não tem limite de quantidade. Recomenda-se atribuir chaves de API independentes para diferentes aplicativos, a fim de controlar permissões de forma mais granular.

Criar chave de API

Faça login no EasyAR Developer Center. Se for sua primeira vez usando uma chave de API, crie uma primeiro seguindo estas etapas:

Em "Autorização", clique em "Chave de API de serviços em nuvem"
Na página "Chave de API", clique no botão "Criar chave de API"

APIKey

Preencha o "Nome do aplicativo"
Marque os serviços em nuvem necessários de acordo com os requisitos do seu aplicativo. Não é recomendado autorizar todos.
Clique em "Confirmar"

Dica

Para usar SpatialMap, marque SpatialMap.

Para usar Reconhecimento em nuvem, marque Reconhecimento em nuvem.

Para usar Mega Landmark, marque Mega Landmark. É necessário solicitar permissão comercial antes de usar este recurso.

Para usar Centro de operações AR, marque Centro de operações AR. É necessário solicitar permissão comercial antes de usar este recurso.

Para usar Localização em nuvem Mega Block, marque Mega Block.

APIKey

Neste momento, a chave de API e o segredo da API serão gerados na página, conforme mostrado abaixo. Tome cuidado para não divulgá-los.

APIKey

Aviso

Não use a chave de API e o segredo da API diretamente em aplicativos clientes (como Web, mini programas WeChat, etc.).

Obter token

Existem duas maneiras de obter um token: 1. Diretamente do Developer Center; 2. Escrevendo código. Se você precisa controlar permissões de acesso a recursos, recomenda-se usar a segunda opção. Abaixo estão descritas as duas formas de obtenção. Escolha conforme sua necessidade.

Obter token do Developer Center

Selecione a chave de API que deseja usar e clique em "Gerenciar" à direita

APIKeyToken

Selecione um período de validade para o token
Clique em "Gerar token"
Clique em "Copiar"

APIKeyToken

Nota

‌A segurança é a principal razão para definir um período de validade para o token.‌ Se o token tiver validade muito longa, em caso de vazamento ou roubo, um atacante pode usá-lo por um longo período, causando vazamento de dados ou operações não autorizadas; a validade limita a janela de tempo efetiva do token, reduzindo o dano mesmo em caso de vazamento.

Gerar token usando chave de API e segredo da API

O processo de geração do token requer a assinatura de parâmetros principais para garantir a segurança da transmissão. Em seguida, esses dados assinados são enviados ao serviço STS (Security Token Service) para autenticação. Após a validação bem-sucedida pelo STS, um token de acesso temporário é emitido, válido apenas dentro de uma janela de tempo específica. Após expirar, um novo processo de autenticação deve ser iniciado.

Aviso

Não gere o token em código do lado do cliente. Em vez disso, gere o token no lado do servidor e envie-o para o cliente.

Parâmetros de solicitação

Nome do campo	Tipo	Obrigatório	Descritivo
apiKey	string	Sim	API Key
expires	int	Sim	Tempo de validade do token gerado, unidade em segundos
acl	string	Sim	Lista de controle de acesso (Access Control List), controla as permissões de recursos acessíveis pelo token
timestamp	long	Sim	Timestamp, unidade em milissegundos
signature	string	Sim	Assinatura

acl: Composto por um ou mais ACs (controles de acesso), cada AC contém quatro partes: service, effect, resource, permission.

service: Tipo de serviço, atualmente suporta ecs:crs (reconhecimento baseado em nuvem), ecs:spatialmap (mapa espacial esparso), ecs:cls (localização em nuvem Mega Block), ecs:vps1 (landmark)
resource: app id do serviço específico, por exemplo, CRS AppId da biblioteca de reconhecimento em nuvem
effect: Especifica se o acesso correspondente a esta configuração de resource pode ser executado, valores: Allow, Deny
permission: Permissões, valores: READ, WRITE

Exemplo de estrutura:

[
  {
    "service": "ecs:crs",
    "resource": ["f7ff497727ab2d55ea01d9984ef8068c"],
    "effect": "Allow",
    "permission": ["READ"]
  }
]

Método de assinatura

Ordene todos os parâmetros da solicitação pelo nome da chave
Para cada parâmetro, concatene o nome da chave e o valor em uma string
Concatene todas as strings resultantes e adicione o segredo da API no final
Calcule o hash SHA256 da string em hexadecimal - este será a assinatura

Exemplo de assinatura

<?php
// Sua chave de API e segredo de API
$apiKey = '6a47f7f8ff6......68744b4bcf';
$apiSecret = '87745d866345256b......fbae27c502a';
// O ID do aplicativo do seu serviço
$appId = 'f7ff497727ab2d55ea01d9984ef8068c';
// Tempo de validade em segundos
$expires = 3600;

// Construir parâmetros a serem assinados
$data = [
    'apiKey' => $apiKey,
    'expires' => $expires,
    'acl' => '[{"service":"ecs:crs","resource":["'. $appId .'"],"effect":"Allow","permission":["READ"]}]',
    'timestamp' => time() * 1000,
];

// Ordenar
ksort($data);

// Concatenar strings
$builder = [];
foreach ($data as $key => $value) {
    array_push($builder, $key . $value);
}

// Concatenar o segredo da API
array_push($builder, $apiSecret);

// Gerar assinatura
$signature = hash('sha256', implode('', $builder));
echo $signature;

const crypto = require('crypto');

// Sua chave de API e segredo de API
const apiKey = '6a47f7f8ff6......68744b4bcf'
const apiSecret = '87745d866345256b......fbae27c502a'
// ID do aplicativo de serviço
const appId = 'f7ff497727ab2d55ea01d9984ef8068c';
// Tempo de validade em segundos
const expires = 3600

// Construindo parâmetros para assinatura
const data = {
    apiKey: apiKey,
    expires: expires,
    acl: `[{"service":"ecs:crs","resource":["${appId}"],"effect":"Allow","permission":["READ"]}]`,
    timestamp: Date.now(),
}

// Ordenando e concatenando strings
let builder = [];
Object.keys(data).sort().forEach(key => builder.push(`${key}${data[key]}`));

// Concatenando o API Secret
builder.push(apiSecret);

// Gerando a assinatura
const signature = crypto.createHash('sha256').update(builder.join('')).digest('hex');
console.info(signature);

import time
import hashlib

# Sua api key e api secret
apiKey = '6a47f7f8ff6......68744b4bcf'
apiSecret = '87745d866345256b......fbae27c502a'
# Seu app id de serviço
appId = 'f7ff497727ab2d55ea01d9984ef8068c'
# Período de validade em segundos
expires = 3600

# Construir parâmetros para assinatura
data = dict(sorted({
    'apiKey': apiKey,
    'expires': expires,
    'acl': '[{"service":"ecs:crs","resource":["'+ appId +'"],"effect":"Allow","permission":["READ"]}]',
    'timestamp': int(time.time() * 1000),
}.items()))

# Concatenar string
builder = [f'{key}{value}' for key, value in data.items()]

# Adicionar api secret
builder.append(apiSecret)

# Gerar assinatura
signature = hashlib.sha256(''.join(builder).encode('utf8')).hexdigest()
print(signature)

package com.easyar;

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.SortedMap;
import java.util.TreeMap;

public class App {

    public static void main(String[] args) throws NoSuchAlgorithmException {
        // Seu API Key e API Secret
        String apiKey = "6a47f7f8ff6......68744b4bcf";
        String apiSecret = "87745d866345256b......fbae27c502a";
        // ID do aplicativo do serviço
        String appId = "f7ff497727ab2d55ea01d9984ef8068c";
        // Tempo de validade, em segundos
        int expires = 3600;

        // Construir parâmetros a serem assinados
        SortedMap<String, Object> data = new TreeMap<>();
        data.put("apiKey", apiKey);
        data.put("expires", expires);
        data.put("timestamp", System.currentTimeMillis());
        data.put("acl", "[{\"service\":\"ecs:crs\",\"resource\":[\"" + appId + "\"],\"effect\":\"Allow\",\"permission\":[\"READ\"]}]");

        // Concatenar strings
        StringBuilder builder = new StringBuilder();
        data.forEach((key, value) -> builder.append(String.format("%s%s", key, value)));

        // Concatenar API Secret
        builder.append(apiSecret);

        // Gerar assinatura
        String signature = sha256(builder.toString());
        System.out.println(signature);
    }

    private static String sha256(String str) throws NoSuchAlgorithmException {
        StringBuilder builder = new StringBuilder();

        MessageDigest digest = MessageDigest.getInstance("sha-256");
        digest.update(str.getBytes(StandardCharsets.UTF_8));
        byte[] bytes = digest.digest();
        for (byte b : bytes) {
            String hex = Integer.toHexString(b & 0XFF);
            if (hex.length() == 1) {
                builder.append("0");
            }
            builder.append(hex);
        }

        return builder.toString();
    }
}

using System.Text;
using System.Security.Cryptography;

namespace EasyAR {
    static class Program {
        static void Main(string[] args) {
            // Sua API Key e API Secret
            string apiKey = "6a47f7f8ff6......68744b4bcf";
            string apiSecret = "87745d866345256b......fbae27c502a";
            // ID do aplicativo do serviço
            string appId = "f7ff497727ab2d55ea01d9984ef8068c";
            // Validade em segundos
            int expires = 3600;

            // Constrói parâmetros para assinatura
            SortedDictionary<string, object> data = new() {
                { "apiKey", apiKey },
                { "expires", expires },
                { "timestamp", DateTimeOffset.Now.ToUnixTimeMilliseconds() },
                { "acl", "[{\"service\":\"ecs:crs\",\"resource\":[\"" + appId + "\"],\"effect\":\"Allow\",\"permission\":[\"READ\"]}]" }
            };

            // Concatena strings
            StringBuilder builder = new StringBuilder();
            data.ToList().ForEach(pair => builder.Append($"{pair.Key}{pair.Value}"));

            // Adiciona API Secret
            builder.Append(apiSecret);

            // Gera assinatura
            string signature = Sha256(builder.ToString());
            Console.WriteLine(signature);
        }

        static string Sha256(string str) {
            byte[] data = SHA256.HashData(Encoding.UTF8.GetBytes(str));
            StringBuilder builder = new StringBuilder();
            for (int i = 0; i < data.Length; i++) {
                builder.Append(data[i].ToString("x2"));
            }
            return builder.ToString();
        }
    }
}

package main

import (
    "crypto/sha256"
    "fmt"
    "sort"
    "strings"
    "time"
)

func main() {
    // Seu API Key e API Secret
    apiKey := "6a47f7f8ff6......68744b4bcf"
    apiSecret := "87745d866345256b......fbae27c502a"
    // Seu App ID de serviço
    appId := "f7ff497727ab2d55ea01d9984ef8068c"
    // Tempo válido, em segundos
    expires := 3600

    // Construir parâmetros a serem assinados
    data := map[string]any{
        "apiKey":    apiKey,
        "expires":   expires,
        "acl":       `[{"service":"ecs:crs","resource":["` + appId + `"],"effect":"Allow","permission":["READ"]}]`,
        "timestamp": time.Now().Unix() * 1000,
    }

    // Ordenar
    keys := []string{}
    for key := range data {
        keys = append(keys, key)
    }
    sort.Strings(keys)

    // Concatenar strings
    builder := strings.Builder{}
    for _, key := range keys {
        builder.WriteString(fmt.Sprintf("%s%v", key, data[key]))
    }

    // Concatenar API Secret
    builder.WriteString(apiSecret)

    // Gerar assinatura
    signature := fmt.Sprintf("%x", sha256.Sum256([]byte(builder.String())))
    fmt.Println(signature)
}

Dica

Ao gerar a assinatura, converta a ACL em uma string JSON.

Obter token

Adicione a assinatura gerada à lista de parâmetros e envie uma solicitação para o endpoint /token/v2 para obter o token.

Endereço de solicitação: https://uac.easyar.com/token/v2 ou https://uac-na1.easyar.com/token/v2 (América do Norte 1)
Método de solicitação: POST
Cabeçalho de solicitação: Content-Type: application/json
Parâmetros de solicitação: {"apiKey":"6a47f7f8ff6......68744b4bcf","expires":3600,"acl":"[{\"service\":\"ecs:crs\",\"resource\":[\"f7ff497727ab2d55ea01d9984ef8068c\"],\"effect\":\"Allow\",\"permission\":[\"READ\"]}]","timestamp":1765954279002,"signature":"32f18a37fc3c18......55c4943af9"}

Exemplo:

curl -X POST https://uac.easyar.com/token/v2 \
-H 'Content-Type: application/json' \
-d '{"apiKey":"6a47f7f8ff6......68744b4bcf","expires":3600,"acl":"[{\"service\":\"ecs:crs\",\"resource\":[\"f7ff497727ab2d55ea01d9984ef8068c\"],\"effect\":\"Allow\",\"permission\":[\"READ\"]}]","timestamp":1765954279002,"signature":"32f18a37fc3c18......55c4943af9"}'

Se statusCode for 0 no resultado de retorno, indica sucesso.

Formato de retorno normal:

{
  "statusCode": 0,
  "timestamp": 1765954874399,
  "msg": "Success",
  "result": {
    "apiKey": "6a47f7f8ff6......68744b4bcf",
    "expires": 3600,
    "token": "nuPDCj......xstQX",
    "expiration": "2025-12-17T08:01:14.399+0000"
  }
}

token: Token de autenticação para solicitações comerciais.
expiration: Tempo de expiração do token, após expirado é necessário solicitar novo token.

Formato de retorno de erro:

{
  "statusCode": 4001017,
  "timestamp": 1765954666624,
  "msg": "AppId is not authorized by this API Key",
  "result": null
}

Usar token

Em solicitações https de negócios, adicione o token ao cabeçalho da solicitação no formato: {"Authorization": "nuPDCj......xstQX"}.

Ao enviar solicitações de API de negócios, é necessário adicionar o parâmetro appId (a origem para obtenção pode ser verificada no Developer Center nos serviços relacionados).

Descrição dos códigos de erro

Durante a geração do token e seu uso, podem ocorrer diversos erros ou situações excepcionais. Para ajudar os desenvolvedores a identificar problemas rapidamente e tomar medidas corretivas eficazes, abaixo estão detalhados os códigos de erro comuns e seus significados:

Código de erro	Mensagem de erro	Descrição do erro	Solução
4001011	API Key invalid	Chave de API inválida	Verifique se esta chave de API existe em "Chave de API de serviços em nuvem"
4001012	Timestamp invalid	Carimbo de data/hora inválido	O carimbo de data/hora é em milissegundos e o desvio em relação ao horário padrão não deve exceder 5 minutos
4001015	Signature invalid	Assinatura inválida	Verifique o algoritmo de assinatura e se o segredo da API corresponde à chave de API
4001017	AppId is not authorized by this API Key	Esta chave de API não autorizou este AppId	Verifique se o serviço ao qual o AppId pertence está associado a esta chave de API
4001018	Base64 decode error	O Authorization definido no cabeçalho da solicitação não está em formato base64 válido	Não processe o token obtido, use-o diretamente
4001019	Decryption error	O Authorization definido no cabeçalho da solicitação não foi gerado pela EasyAR	Não processe o token obtido, use-o diretamente
4001022	API Key's resource is empty	A chave de API não possui serviços em nuvem associados	Verifique se a chave de API tem serviços em nuvem associados e se esses serviços estão ativos
4001024	Token is expired	Token expirado	Gere um novo
4001025	Token generate fail	Falha ao gerar token	Contate o suporte técnico: support@easyar.com

Table of Contents

Obter e usar chave de API

Criar chave de API

Dica

Aviso

Obter token

Obter token do Developer Center

Nota

Gerar token usando chave de API e segredo da API

Aviso

Parâmetros de solicitação

Método de assinatura

Exemplo de assinatura

Dica

Obter token

Usar token

Descrição dos códigos de erro