Ottenere e usare API Key

Nel Developer Center di EasyAR non esiste limite al numero di API Key creabili. Si consiglia di assegnare API Key indipendenti ad applicazioni diverse, così da controllare i permission in modo più preciso.

Creare API Key

Accedere a EasyAR Developer Center. Se si usa API Key per la prima volta, creare prima una API Key seguendo questi passaggi:

In "Authorization", fare clic su "Cloud Service API KEY"
Nella pagina "API KEY", fare clic sul pulsante "Create API KEY"

APIKey

Compilare "Application Name"
Selezionare i cloud services necessari in base alle esigenze dell'applicazione. Non è consigliato autorizzarli tutti.
Fare clic su "OK"

Consiglio

Se si usa SpatialMap, selezionare SpatialMap.

Se si usa Cloud Recognition, selezionare Cloud Recognition.

Se si usa Mega Landmark, selezionare Mega Landmark; prima di usare questa funzione è necessario richiederla al reparto commerciale.

Se si usa AR Operation Center, selezionare AR Operation Center; prima di usare questa funzione è necessario richiederla al reparto commerciale.

Se si usa Mega Block cloud localization, selezionare Mega Block.

APIKey

A questo punto la pagina genererà API Key e API Secret come mostrato sotto. Fare attenzione a non divulgarli.

APIKey

Avvertenza

Non usare API Key e API Secret direttamente in applicazioni client, come Web o WeChat Mini Program.

Ottenere Token

Esistono due modi per ottenere Token: 1. ottenerlo direttamente dal Developer Center; 2. ottenerlo scrivendo codice. Se è necessario controllare i permission di accesso alle resources, è consigliato il secondo metodo. Di seguito vengono descritti entrambi.

Ottenere Token dal Developer Center

Selezionare una API Key da usare e fare clic su "Manage" a destra

APIKeyToken

Selezionare il periodo di validità del Token
Fare clic su "Generate Token"
Fare clic su "Copy"

APIKeyToken

Nota

La sicurezza è il motivo principale per impostare la validità del Token. Se la validità è troppo lunga, una volta trapelato o rubato, un aggressore può usarlo a lungo, causando perdita di dati o operazioni non autorizzate. La validità limita la finestra effettiva del Token; anche se trapela, il danno resta limitato a breve tempo.

Generare Token con API Key e API Secret

Il processo di generazione di Token richiede la firma dei parametri principali per garantire la sicurezza della trasmissione. Successivamente, i dati firmati vengono inviati al servizio STS (Security Token Service) per l'autenticazione. Dopo la verifica, STS emette un access Token temporaneo valido solo nella finestra temporale specificata; alla scadenza occorre avviare nuovamente l'autenticazione.

Avvertenza

Non generare Token nel client code; generarlo sul server side e poi passarlo al client.

Parametri request

Nome campo	Tipo	Obbligatorio	Descrizione
apiKey	string	Si	API Key
expires	int	Si	Tempo di validita del Token generato, in secondi
acl	string	Si	Access Control List, controlla i permessi resource accessibili dal token
timestamp	long	Si	Timestamp, in millisecondi
signature	string	Si	Signature

acl: e composto da uno o piu AC (access control). Ogni AC contiene quattro parti: service, effect, resource e permission.

service: tipo di servizio; attualmente supporta ecs:crs (Cloud Recognition), ecs:spatialmap (Sparse Spatial Map), ecs:cls (Mega Block Cloud Localization), ecs:vps1 (landmark)
resource: app id del servizio specifico, ad esempio CRS AppId della Cloud Recognition library
effect: specifica se l'accesso che corrisponde a questa configurazione resource puo essere eseguito; valori Allow, Deny
permission: valori di permesso READ, WRITE

Esempio di struttura:

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

Metodo signature

Ordinare tutti i parametri della request per nome key
Per ogni parametro, concatenare nome key e value in una stringa
Concatenare tutte le stringhe ottenute e aggiungere API Secret alla fine
Calcolare lo sha256 hash della stringa; il valore esadecimale è la signature

Esempio di signature

<?php
// la tua API Key e il tuo API Secret
$apiKey = '6a47f7f8ff6......68744b4bcf';
$apiSecret = '87745d866345256b......fbae27c502a';
// App ID del tuo servizio
$appId = 'f7ff497727ab2d55ea01d9984ef8068c';
// periodo di validita, in secondi
$expires = 3600;

// costruisce i parametri da firmare
$data = [
    'apiKey' => $apiKey,
    'expires' => $expires,
    'acl' => '[{"service":"ecs:crs","resource":["'. $appId .'"],"effect":"Allow","permission":["READ"]}]',
    'timestamp' => time() * 1000,
];

// ordina
ksort($data);

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

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

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

const crypto = require('crypto');

// la tua API Key e il tuo API Secret
const apiKey = '6a47f7f8ff6......68744b4bcf'
const apiSecret = '87745d866345256b......fbae27c502a'
// App ID del tuo servizio
const appId = 'f7ff497727ab2d55ea01d9984ef8068c';
// periodo di validita, in secondi
const expires = 3600

// costruisce i parametri da firmare
const data = {
    apiKey: apiKey,
    expires: expires,
    acl: `[{"service":"ecs:crs","resource":["${appId}"],"effect":"Allow","permission":["READ"]}]`,
    timestamp: Date.now(),
}

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

// concatena l 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

# la tua API Key e il tuo API Secret
apiKey = '6a47f7f8ff6......68744b4bcf'
apiSecret = '87745d866345256b......fbae27c502a'
# App ID del tuo servizio
appId = 'f7ff497727ab2d55ea01d9984ef8068c'
# periodo di validita, in secondi
expires = 3600

# costruisce i parametri da firmare
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 stringa
builder = [f'{key}{value}' for key, value in data.items()]

# concatena l 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 {
        // la tua API Key e il tuo API Secret
        String apiKey = "6a47f7f8ff6......68744b4bcf";
        String apiSecret = "87745d866345256b......fbae27c502a";
        // App ID del servizio
        String appId = "f7ff497727ab2d55ea01d9984ef8068c";
        // periodo di validita, in secondi
        int expires = 3600;

        // costruisce i parametri da firmare
        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 stringa
        StringBuilder builder = new StringBuilder();
        data.forEach((key, value) -> builder.append(String.format("%s%s", key, value)));

        // concatena l 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) {
            // la tua API Key e il tuo API Secret
            string apiKey = "6a47f7f8ff6......68744b4bcf";
            string apiSecret = "87745d866345256b......fbae27c502a";
            // App ID del servizio
            string appId = "f7ff497727ab2d55ea01d9984ef8068c";
            // periodo di validita, in secondi
            int expires = 3600;

            // costruisce i parametri da firmare
            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 stringa
            StringBuilder builder = new StringBuilder();
            data.ToList().ForEach(pair => builder.Append($"{pair.Key}{pair.Value}"));

            // concatena l 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() {
    // la tua API Key e il tuo API Secret
    apiKey := "6a47f7f8ff6......68744b4bcf"
    apiSecret := "87745d866345256b......fbae27c502a"
    // App ID del tuo servizio
    appId := "f7ff497727ab2d55ea01d9984ef8068c"
    // periodo di validita, in secondi
    expires := 3600

    // costruisce i parametri da firmare
    data := map[string]any{
        "apiKey":    apiKey,
        "expires":   expires,
        "acl":       `[{"service":"ecs:crs","resource":["` + appId + `"],"effect":"Allow","permission":["READ"]}]`,
        "timestamp": time.Now().Unix() * 1000,
    }

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

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

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

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

Consiglio

Quando si aggiunge la signature, ACL deve essere convertito in stringa JSON.

Ottenere Token

Aggiungere la signature generata alla lista dei parametri e inviare la request all'interface /token/v2 per ottenere Token.

Indirizzo request: https://uac.easyar.com/token/v2 oppure https://uac-na1.easyar.com/token/v2 (North America 1)
Metodo request: POST
Header request: Content-Type: application/json
Parametri request:{"apiKey":"6a47f7f8ff6......68744b4bcf","expires":3600,"acl":"[{\"service\":\"ecs:crs\",\"resource\":[\"f7ff497727ab2d55ea01d9984ef8068c\"],\"effect\":\"Allow\",\"permission\":[\"READ\"]}]","timestamp":1765954279002,"signature":"32f18a37fc3c18......55c4943af9"}

Esempio:

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 nel risultato restituito e 0, significa successo.

Formato di ritorno normale:

{
  "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 per l'autenticazione della business request.
expiration: tempo di scadenza del token; dopo la scadenza e necessario richiedere nuovamente il token.

Formato di ritorno errore:

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

Usare Token

Nelle request https di business, aggiungere Token al request header nel formato: {"Authorization": "nuPDCj......xstQX"}.

Quando si invia una business API request, è necessario aggiungere il parametro appId (consultare il service corrispondente nel Developer Center per l'origine).

Descrizione degli error code

Durante generazione e uso di Token possono verificarsi vari errori o eccezioni. Per aiutare gli sviluppatori a individuare rapidamente i problemi e adottare soluzioni efficaci, di seguito sono illustrati gli error code comuni e il loro significato:

Error code	Error message	Descrizione errore	Soluzione
4001011	API Key invalid	API Key non valida	Verificare se questa API Key esiste in "Cloud Service API KEY"
4001012	Timestamp invalid	Timestamp non valido	L'unità del timestamp è il millisecondo e la differenza dall'ora standard non deve superare 5 minuti
4001015	Signature invalid	Signature non valida	Verificare se l'algoritmo di signature è corretto e se API Secret corrisponde ad API KEY
4001017	AppId is not authorized by this API Key	API Key non ha autorizzato questo AppId	Verificare se il service a cui appartiene AppId è associato a questa API Key
4001018	Base64 decode error	Authorization impostato nel request header non è un base64 valido	Usare direttamente il Token ottenuto senza alcuna elaborazione
4001019	Decryption error	Authorization impostato nel request header non è generato da EasyAR	Usare direttamente il Token ottenuto senza alcuna elaborazione
4001022	API Key's resource is empty	API Key non ha cloud service associati	Verificare se API Key è associata a cloud service e se il cloud service associato è scaduto
4001024	Token is expired	Token scaduto	Rigenerare
4001025	Token generate fail	Generazione Token fallita	Contattare il supporto tecnico: support@easyar.com

Table of Contents

Ottenere e usare API Key

Creare API Key

Consiglio

Avvertenza

Ottenere Token

Ottenere Token dal Developer Center

Nota

Generare Token con API Key e API Secret

Avvertenza

Parametri request

Metodo signature

Esempio di signature

Consiglio

Ottenere Token

Usare Token

Descrizione degli error code