Obtener y usar API Key

En EasyAR Development Center, crear API Key no tiene límite de cantidad. Se recomienda asignar API Key independientes para diferentes aplicaciones, para un control de permisos más preciso.

Crear API Key

Inicie sesión en EasyAR Development Center. Si es la primera vez que usa API Key, primero cree un API Key siguiendo estos pasos:

En "Autorización", haga clic en "Cloud Service API KEY"
En la página "API KEY", haga clic en el botón "Create API KEY"

APIKey

Complete el "Application Name"
Marque los servicios en la nube requeridos según las necesidades de su aplicación. No se recomienda autorizar todos.
Haga clic en "Confirm"

Consejo

Para usar SpatialMap, marque SpatialMap.

Para usar Cloud Recognition, marque Cloud Recognition.

Para usar Mega Landmark, marque Mega Landmark. Antes de usar esta función, debe solicitarla al departamento comercial.

Para usar AR Operation Center, marque AR Operation Center. Antes de usar esta función, debe solicitarla al departamento comercial.

Para usar Mega Block Cloud Localization, marque Mega Block.

APIKey

En este momento, se generarán API Key y API Secret en la página, como se muestra a continuación. Tenga cuidado de no divulgarlos.

APIKey

Advertencia

No use API Key y API Secret directamente en aplicaciones cliente (como Web, WeChat Mini Programs, etc.).

Obtener token

Hay dos formas de obtener un token: 1. Obtenerlo directamente desde Development Center; 2. Generarlo mediante código. Si necesita controlar los permisos de acceso a recursos, se recomienda usar el segundo método. A continuación se explican ambas opciones, puede elegir según sus necesidades.

Obtener token desde Development Center

Seleccione el API Key que desea usar y haga clic en "Manage" a la derecha

APIKeyToken

Seleccione un período de validez para el token
Haga clic en "Generate Token"
Haga clic en "Copy" para copiarlo

APIKeyToken

Nota

La seguridad es la razón principal para establecer la validez del token. Si el token tiene una validez demasiado larga, en caso de filtración o robo, un atacante podría usarlo durante mucho tiempo, causando fugas de datos u operaciones no autorizadas. La validez limita la ventana efectiva del token, por lo que incluso si se filtra, el daño se limita a un corto período.

Generar token usando API Key y API Secret

El proceso de generación de token requiere firmar parámetros clave para garantizar la seguridad de la transmisión. Luego, estos datos firmados se envían al servicio STS (Security Token Service) para autenticación. Después de la verificación, el servicio STS emite un token de acceso temporal que solo es válido durante un período específico. Una vez vencido, se debe reiniciar el proceso de autenticación.

Advertencia

No genere el token en código cliente. Genere el token en el servidor y luego páselo al cliente.

Parámetros de solicitud

Nombre del campo	Tipo	¿Es obligatorio?	Descripción
apiKey	string	Sí	API Key
expires	int	Sí	Tiempo de validez del token generado, en segundos
acl	string	Sí	Lista de control de acceso (Access Control List), controla los permisos de recursos accesibles por el token
timestamp	long	Sí	Marca de tiempo, en milisegundos
signature	string	Sí	Firma

acl: Compuesto por uno o más AC (control de acceso). Cada AC contiene cuatro partes: service, effect, resource y permission.

service: Tipo de servicio. Actualmente compatible con ecs:crs (reconocimiento en la nube), ecs:spatialmap (mapa espacial disperso), ecs:cls (Mega Block cloud positioning), ecs:vps1 (landmark)
resource: App ID específica del servicio, por ejemplo, CRS AppId de la biblioteca de reconocimiento en la nube
effect: Especifica si se puede ejecutar el acceso que coincide con esta entrada de configuración de resource. Valores: Allow, Deny
permission: Permisos. Valores: READ, WRITE

Ejemplo de estructura:

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

Método de firma

Ordenar todos los parámetros de la solicitud por nombre de clave
Para cada parámetro, concatenar su nombre de clave y valor en una cadena
Concatenar todas las cadenas obtenidas y agregar API Secret al final
Calcular el hash sha256 de la cadena en hexadecimal, que será la firma

Ejemplo de firma

<?php
// Su API Key y API Secret
$apiKey = '6a47f7f8ff6......68744b4bcf';
$apiSecret = '87745d866345256b......fbae27c502a';
// Su App ID de servicio
$appId = 'f7ff497727ab2d55ea01d9984ef8068c';
// Tiempo de validez, en segundos
$expires = 3600;

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

// Ordenar
ksort($data);

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

// Concatenar API Secret
array_push($builder, $apiSecret);

// Generar firma
$signature = hash('sha256', implode('', $builder));
echo $signature;

const crypto = require('crypto');

// Su clave API y API Secret
const apiKey = '6a47f7f8ff6......68744b4bcf'
const apiSecret = '87745d866345256b......fbae27c502a'
// Su ID de aplicación del servicio
const appId = 'f7ff497727ab2d55ea01d9984ef8068c';
// Tiempo de validez, en segundos
const expires = 3600

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

// Ordenar y concatenar cadenas
let builder = [];
Object.keys(data).sort().forEach(key => builder.push(`${key}${data[key]}`));

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

// Generar firma
const signature = crypto.createHash('sha256').update(builder.join('')).digest('hex');
console.info(signature);

import time
import hashlib

# Su API Key y API Secret
apiKey = '6a47f7f8ff6......68744b4bcf'
apiSecret = '87745d866345256b......fbae27c502a'
# Su servicio App ID
appId = 'f7ff497727ab2d55ea01d9984ef8068c'
# Tiempo de validez, en segundos
expires = 3600

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

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

# Concatenar API Secret
builder.append(apiSecret)

# Generar la firma
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 {
        // Tu clave API y secreto API
        String apiKey = "6a47f7f8ff6......68744b4bcf";
        String apiSecret = "87745d866345256b......fbae27c502a";
        // ID de la aplicación del servicio
        String appId = "f7ff497727ab2d55ea01d9984ef8068c";
        // Tiempo de validez, en segundos
        int expires = 3600;

        // Construir los parámetros a firmar
        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 la cadena
        StringBuilder builder = new StringBuilder();
        data.forEach((key, value) -> builder.append(String.format("%s%s", key, value)));

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

        // Generar la firma
        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) {
            // Su clave API y secreto API
            string apiKey = "6a47f7f8ff6......68744b4bcf";
            string apiSecret = "87745d866345256b......fbae27c502a";
            // ID de la aplicación del servicio
            string appId = "f7ff497727ab2d55ea01d9984ef8068c";
            // Tiempo de validez, en segundos
            int expires = 3600;

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

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

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

            // Generar firma
            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() {
    // Tu api key y api secret
    apiKey := "6a47f7f8ff6......68744b4bcf"
    apiSecret := "87745d866345256b......fbae27c502a"
    // Tu app id de servicio
    appId := "f7ff497727ab2d55ea01d9984ef8068c"
    // Tiempo de validez, en segundos
    expires := 3600

    // Construir parámetros de firma
    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 cadenas
    builder := strings.Builder{}
    for _, key := range keys {
        builder.WriteString(fmt.Sprintf("%s%v", key, data[key]))
    }

    // Concatenar api secret
    builder.WriteString(apiSecret)

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

Consejo

Al agregar la firma, es necesario convertir ACL a cadena JSON.

Obtener token

Agregue la firma generada a la lista de parámetros y envíe una solicitud al endpoint /token/v2 para obtener el token.

Dirección de solicitud: https://uac.easyar.com/token/v2 o https://uac-na1.easyar.com/token/v2 (Región Norteamérica 1)
Método de solicitud: POST
Cabeceras de solicitud: Content-Type: application/json
Parámetros de solicitud: {"apiKey":"6a47f7f8ff6......68744b4bcf","expires":3600,"acl":"[{\"service\":\"ecs:crs\",\"resource\":[\"f7ff497727ab2d55ea01d9984ef8068c\"],\"effect\":\"Allow\",\"permission\":[\"READ\"]}]","timestamp":1765954279002,"signature":"32f18a37fc3c18......55c4943af9"}

Ejemplo:

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

En el resultado de retorno, si statusCode es 0, indica éxito.

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 autenticación de solicitud comercial.
expiration: Tiempo de expiración del token. Una vez caducado, es necesario solicitar un nuevo token.

Formato de retorno de error:

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

Usar token

En solicitudes https de negocio, agregue el token al encabezado de la solicitud con el formato: {"Authorization": "nuPDCj......xstQX"}.

Al enviar solicitudes API de negocio, debe agregar el parámetro appId (consulte el servicio relacionado en Development Center para obtenerlo).

Explicación de códigos de error

Durante la generación y uso del token, pueden ocurrir varios errores o situaciones excepcionales. Para ayudar a los desarrolladores a identificar problemas rápidamente y tomar medidas efectivas, a continuación se detallan los códigos de error comunes y sus significados:

Código de error	Mensaje de error	Explicación	Solución
4001011	API Key invalid	API Key inválido	Verifique si existe este API Key en "Cloud Service API KEY"
4001012	Timestamp invalid	Marca de tiempo inválida	La marca de tiempo está en milisegundos y no debe diferir más de 5 minutos de la hora estándar
4001015	Signature invalid	Firma inválida	Verifique el algoritmo de firma y asegúrese de que API Secret coincida con API KEY
4001017	AppId is not authorized by this API Key	API Key no tiene autorizado este AppId	Verifique si el servicio donde está AppId está asociado a este API Key
4001018	Base64 decode error	Authorization en el encabezado no tiene formato base64 válido	Use el token obtenido directamente sin procesarlo
4001019	Decryption error	Authorization en el encabezado no fue generado por EasyAR	Use el token obtenido directamente sin procesarlo
4001022	API Key's resource is empty	API Key no tiene servicios en la nube asociados	Verifique si API Key tiene servicios asociados y si han expirado
4001024	Token is expired	Token ha expirado	Genere uno nuevo
4001025	Token generate fail	Error al generar token	Contacte a soporte técnico: support@easyar.com

Table of Contents

Obtener y usar API Key

Crear API Key

Consejo

Advertencia

Obtener token

Obtener token desde Development Center

Nota

Generar token usando API Key y API Secret

Advertencia

Parámetros de solicitud

Método de firma

Ejemplo de firma

Consejo

Obtener token

Usar token

Explicación de códigos de error