Obtener y usar API Key

En EasyAR Developer Center no hay límite para crear API Key. Se recomienda asignar una API Key independiente a cada aplicación para controlar los permisos con más precisión.

Crear API Key

Inicie sesión en EasyAR Developer Center. Si es la primera vez que usa API Key, cree primero una API Key con estos pasos:

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

APIKey

Rellene "Application Name"
Seleccione los cloud services necesarios según los requisitos de su aplicación. No se recomienda autorizar todos.
Haga clic en "OK"

Consejo

Si usa SpatialMap, seleccione SpatialMap.

Si usa Cloud Recognition, seleccione Cloud Recognition.

Si usa Mega Landmark, seleccione Mega Landmark; esta función requiere solicitarla a ventas antes de usarla.

Si usa AR Operation Center, seleccione AR Operation Center; esta función requiere solicitarla a ventas antes de usarla.

Si usa Mega Block cloud localization, seleccione Mega Block.

APIKey

En este momento se generarán API Key y API Secret en la página, como se muestra abajo. No los filtre.

APIKey

Advertencia

No use API Key ni API Secret directamente en aplicaciones client, como Web o WeChat Mini Program.

Obtener Token

Hay dos formas de obtener Token: 1. obtenerlo directamente desde Developer Center; 2. obtenerlo escribiendo código. Si necesita controlar permisos de acceso a recursos, se recomienda la segunda forma. A continuación se describen ambas; elija según sus necesidades.

Obtener Token desde Developer Center

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

APIKeyToken

Seleccione un periodo de validez para el Token
Haga clic en "Generate Token"
Haga clic en "Copy"

APIKeyToken

Nota

La seguridad es la razón principal para configurar la validez del Token. Si el Token tiene una validez demasiado larga, una vez filtrado o robado, un atacante puede usarlo durante mucho tiempo, causando filtración de datos u operaciones no autorizadas. La validez limita la ventana efectiva del Token; incluso si se filtra, el daño queda limitado a poco tiempo.

Generar Token con API Key y API Secret

El proceso de generación de Token requiere firmar los parámetros principales para garantizar la seguridad de la transmisión. Después, los datos firmados se envían al servicio STS (Security Token Service) para autenticación. Tras la verificación de STS, se emite un Token de acceso temporal que solo es válido dentro de la ventana de tiempo especificada; al expirar, se debe iniciar de nuevo el proceso de autenticación.

Advertencia

No genere Token en el código client; genere Token en el server side y páselo al client para su uso.

Parámetros de request

Nombre del campo	Tipo	Obligatorio	Descripción
apiKey	string	Sí	API Key
expires	int	Sí	Tiempo de validez del Token generado, en segundos
acl	string	Sí	Access Control List, controla los permisos de resource a los que puede acceder el token
timestamp	long	Sí	Timestamp, en milisegundos
signature	string	Sí	Signature

acl: se compone de uno o varios AC (access control). Cada AC contiene cuatro partes: service, effect, resource y permission.

service: tipo de servicio; actualmente admite ecs:crs (Cloud Recognition), ecs:spatialmap (Sparse Spatial Map), ecs:cls (Mega Block Cloud Localization), ecs:vps1 (landmark)
resource: app id del servicio específico, por ejemplo CRS AppId de la Cloud Recognition library
effect: especifica si el acceso que coincide con esta configuración de resource puede ejecutarse; valores Allow, Deny
permission: valores de permiso READ, WRITE

Ejemplo de estructura:

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

Método de signature

Ordene todos los parámetros de request por nombre de key
Para cada parámetro, concatene el nombre de key y el value en una string
Concatene todas las strings resultantes y añada API Secret al final
Calcule el hash sha256 de la string; el valor hexadecimal es la signature

Ejemplo de signature

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

// construye los parametros que se firmaran
$data = [
    'apiKey' => $apiKey,
    'expires' => $expires,
    'acl' => '[{"service":"ecs:crs","resource":["'. $appId .'"],"effect":"Allow","permission":["READ"]}]',
    'timestamp' => time() * 1000,
];

// ordena
ksort($data);

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

// concatena el API Secret
array_push($builder, $apiSecret);

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

const crypto = require('crypto');

// su API Key y API Secret
const apiKey = '6a47f7f8ff6......68744b4bcf'
const apiSecret = '87745d866345256b......fbae27c502a'
// el App ID de su servicio
const appId = 'f7ff497727ab2d55ea01d9984ef8068c';
// tiempo de validez, en segundos
const expires = 3600

// construye los parametros que se firmaran
const data = {
    apiKey: apiKey,
    expires: expires,
    acl: `[{"service":"ecs:crs","resource":["${appId}"],"effect":"Allow","permission":["READ"]}]`,
    timestamp: Date.now(),
}

// ordena y concatena la cadena
let builder = [];
Object.keys(data).sort().forEach(key => builder.push(`${key}${data[key]}`));

// concatena el API Secret
builder.push(apiSecret);

// genera la 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'
# el App ID de su servicio
appId = 'f7ff497727ab2d55ea01d9984ef8068c'
# tiempo de validez, en segundos
expires = 3600

# construye los parametros que se firmaran
data = dict(sorted({
    'apiKey': apiKey,
    'expires': expires,
    'acl': '[{"service":"ecs:crs","resource":["'+ appId +'"],"effect":"Allow","permission":["READ"]}]',
    'timestamp': int(time.time() * 1000),
}.items()))

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

# concatena el API Secret
builder.append(apiSecret)

# genera 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 {
        // su API Key y API Secret
        String apiKey = "6a47f7f8ff6......68744b4bcf";
        String apiSecret = "87745d866345256b......fbae27c502a";
        // App ID del servicio
        String appId = "f7ff497727ab2d55ea01d9984ef8068c";
        // tiempo de validez, en segundos
        int expires = 3600;

        // construye los parametros que se firmaran
        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\"]}]");

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

        // concatena el API Secret
        builder.append(apiSecret);

        // genera 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 API Key y API Secret
            string apiKey = "6a47f7f8ff6......68744b4bcf";
            string apiSecret = "87745d866345256b......fbae27c502a";
            // App ID del servicio
            string appId = "f7ff497727ab2d55ea01d9984ef8068c";
            // tiempo de validez, en segundos
            int expires = 3600;

            // construye los parametros que se firmaran
            SortedDictionary<string, object> data = new() {
                { "apiKey", apiKey },
                { "expires", expires },
                { "timestamp", DateTimeOffset.Now.ToUnixTimeMilliseconds() },
                { "acl", "[{\"service\":\"ecs:crs\",\"resource\":[\"" + appId + "\"],\"effect\":\"Allow\",\"permission\":[\"READ\"]}]" }
            };

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

            // concatena el API Secret
            builder.Append(apiSecret);

            // genera la 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() {
    // su API Key y API Secret
    apiKey := "6a47f7f8ff6......68744b4bcf"
    apiSecret := "87745d866345256b......fbae27c502a"
    // el App ID de su servicio
    appId := "f7ff497727ab2d55ea01d9984ef8068c"
    // tiempo de validez, en segundos
    expires := 3600

    // construye los parametros que se firmaran
    data := map[string]any{
        "apiKey":    apiKey,
        "expires":   expires,
        "acl":       `[{"service":"ecs:crs","resource":["` + appId + `"],"effect":"Allow","permission":["READ"]}]`,
        "timestamp": time.Now().Unix() * 1000,
    }

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

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

    // concatena el API Secret
    builder.WriteString(apiSecret)

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

Consejo

Al añadir la signature, ACL debe convertirse en string JSON.

Obtener Token

Agregue la signature generada a la lista de parámetros y envíe un request a la interfaz /token/v2 para obtener Token.

Dirección de request: https://uac.easyar.com/token/v2 o https://uac-na1.easyar.com/token/v2 (North America 1)
Método de request: POST
Header de request: Content-Type: application/json
Parámetros de request:{"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"}'

Si statusCode en el resultado devuelto 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 para autenticación de business request.
expiration: hora de expiración del token; después de expirar, debe solicitarse de nuevo.

Formato de retorno de error:

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

Usar Token

En los request https de negocio, añada Token al request header con el formato: {"Authorization": "nuPDCj......xstQX"}.

Al enviar request de API de negocio, debe añadir el parámetro appId (consulte el servicio correspondiente en Developer Center para obtenerlo).

Descripción de error codes

Durante la generación y el uso de Token pueden producirse distintos errores o excepciones. Para ayudar a los desarrolladores a localizar problemas rápidamente y tomar medidas efectivas, a continuación se detallan los error codes comunes y su significado:

Error code	Error message	Descripción del error	Solución
4001011	API Key invalid	API Key no válida	Compruebe si esta API Key existe en "Cloud Service API KEY"
4001012	Timestamp invalid	Timestamp no válido	La unidad del timestamp es milisegundos y la diferencia con la hora estándar no debe superar 5 minutos
4001015	Signature invalid	Signature no válida	Compruebe si el algoritmo de signature es correcto y si API Secret coincide con API KEY
4001017	AppId is not authorized by this API Key	API Key no ha autorizado este AppId	Compruebe si el servicio al que pertenece AppId está asociado a esta API Key
4001018	Base64 decode error	Authorization configurado en el request header no es base64 válido	Use directamente el Token obtenido sin procesarlo
4001019	Decryption error	Authorization configurado en el request header no fue generado por EasyAR	Use directamente el Token obtenido sin procesarlo
4001022	API Key's resource is empty	API Key no tiene cloud service asociado	Compruebe si API Key está asociada a cloud service y si el cloud service asociado ha expirado
4001024	Token is expired	Token ha expirado	Genérelo de nuevo
4001025	Token generate fail	La generación de Token falló	Contacte con soporte técnico: support@easyar.com

Table of Contents

Obtener y usar API Key

Crear API Key

Consejo

Advertencia

Obtener Token

Obtener Token desde Developer Center

Nota

Generar Token con API Key y API Secret

Advertencia

Parámetros de request

Método de signature

Ejemplo de signature

Consejo

Obtener Token

Usar Token

Descripción de error codes