Ottenere e utilizzare API Key

Creare API Key nel centro di sviluppo EasyAR non ha limiti di quantità. Si consiglia di assegnare API Key indipendenti per applicazioni diverse, per un controllo più granulare delle autorizzazioni.

Creare API Key

Accedi al centro di sviluppo EasyAR view/login.html. Se utilizzi API Key per la prima volta, creane una seguendo questi passaggi:

In "Autorizzazioni", clicca su "API KEY servizi cloud"
Nella pagina "API KEY", clicca sul pulsante "Crea API KEY"

APIKey

Compila "Nome applicazione"
Seleziona i servizi cloud necessari in base alle esigenze della tua applicazione. Non è consigliabile autorizzare tutti.
Clicca "Conferma"

Consiglio

Per utilizzare SpatialMap, seleziona SpatialMap.

Per utilizzare riconoscimento cloud, seleziona riconoscimento cloud.

Per Mega Landmark, seleziona Mega Landmark. Prima di utilizzare questa funzione, contatta il reparto commerciale.

Per il centro operativo AR, seleziona centro operativo AR. Prima di utilizzare questa funzione, contatta il reparto commerciale.

Per localizzazione cloud Mega Block, seleziona Mega Block.

APIKey

Verranno generati API Key e API Secret, come mostrato di seguito. Attenzione a non divulgarli.

APIKey

Avvertenza

Non utilizzare direttamente API Key e API Secret in applicazioni client (come Web, mini-program WeChat, ecc.).

Ottenere token

Esistono due modi per ottenere un token: 1. Ottenere direttamente dal centro di sviluppo; 2. Generare tramite codice. Se hai esigenze di controllo delle autorizzazioni per le risorse, si consiglia il secondo metodo. Di seguito vengono descritti entrambi, scegli in base alle tue necessità.

Ottenere token dal centro di sviluppo

Seleziona l'API Key che desideri utilizzare, clicca su "Gestisci" a destra

APIKeyToken

Seleziona una durata valida per il token
Clicca "Genera token"
Clicca "Copia"

APIKeyToken

Nota

‌La sicurezza è la ragione principale per impostare la durata del token.‌ Se il token rimane valido troppo a lungo, in caso di furto o compromissione, un attaccante potrebbe utilizzarlo a lungo, causando perdita di dati o operazioni non autorizzate. Una durata limitata riduce la finestra di rischio.

Generare token utilizzando API Key e API Secret

La generazione del token richiede la firma dei parametri principali per garantire la sicurezza della trasmissione. I dati firmati vengono poi inviati al servizio STS (Security Token Service) per l'autenticazione. Dopo la verifica, STS rilascia un token di accesso temporaneo, valido solo entro un intervallo di tempo specificato. Scaduto tale intervallo, è necessario ripetere il processo.

Avvertenza

Non generare token nel codice client, ma generalo lato server e poi trasmettilo al client.

Parametri della richiesta

Nome campo	Tipo	Obbligatorio	Descrizione
apiKey	string	Sì	API Key
expires	int	Sì	Tempo di validità del token generato, in secondi
acl	string	Sì	Access Control List (Access Control List), controlla le autorizzazioni di accesso alle risorse del token
timestamp	long	Sì	Timestamp, in millisecondi
signature	string	Sì	Firma

acl: composto da uno o più AC (controllo di accesso), ogni AC contiene quattro parti: service, effect, resource, permission.

service: tipo di servizio, attualmente supporta ecs:crs (riconoscimento cloud), ecs:spatialmap (mappa spaziale sparsa), ecs:cls (Mega Block cloud localization), ecs:vps1 (landmark)
resource: app id del servizio specifico, ad esempio CRS AppId della libreria di riconoscimento cloud
effect: specifica se l'accesso corrispondente a questa voce di configurazione resource può essere eseguito, valori Allow, Deny
permission: valori di permesso READ, WRITE

Struttura di esempio:

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

Metodo di firma

Ordina tutti i parametri della richiesta per nome
Per ogni parametro, concatena nome e valore in una stringa
Unisci tutte le stringhe risultanti e aggiungi API Secret alla fine
Calcola lo sha256 della stringa in esadecimale: questa è la firma

Esempio di firma

<?php
// La tua chiave API e API Secret
$apiKey = '6a47f7f8ff6......68744b4bcf';
$apiSecret = '87745d866345256b......fbae27c502a';
// Il tuo App ID del servizio
$appId = 'f7ff497727ab2d55ea01d9984ef8068c';
// Tempo valido, in secondi
$expires = 3600;

// Costruisci 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 API Secret
array_push($builder, $apiSecret);

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

const crypto = require('crypto');

// La tua chiave API e il segreto API
const apiKey = '6a47f7f8ff6......68744b4bcf'
const apiSecret = '87745d866345256b......fbae27c502a'
// Il tuo ID app del servizio
const appId = 'f7ff497727ab2d55ea01d9984ef8068c';
// Tempo di validità, in secondi
const expires = 3600

// Costruisci 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 le stringhe
let builder = [];
Object.keys(data).sort().forEach(key => builder.push(`${key}${data[key]}`));

// Concatena il segreto API
builder.push(apiSecret);

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

import time
import hashlib

# Il tuo API Key e API Secret
apiKey = '6a47f7f8ff6......68744b4bcf'
apiSecret = '87745d866345256b......fbae27c502a'
# Il tuo servizio App ID
appId = 'f7ff497727ab2d55ea01d9984ef8068c'
# Durata di validità, in secondi
expires = 3600

# Costruisci 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()))

# Concatenare le stringhe
builder = [f'{key}{value}' for key, value in data.items()]

# Aggiungi 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 {
        // Il tuo API Key e API Secret
        String apiKey = "6a47f7f8ff6......68744b4bcf";
        String apiSecret = "87745d866345256b......fbae27c502a";
        // ID dell'app del servizio
        String appId = "f7ff497727ab2d55ea01d9984ef8068c";
        // Tempo di validità, in secondi
        int expires = 3600;

        // Costruisci 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 le stringhe
        StringBuilder builder = new StringBuilder();
        data.forEach((key, value) -> builder.append(String.format("%s%s", key, value)));

        // Concatena 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 chiave API e segreto API
            string apiKey = "6a47f7f8ff6......68744b4bcf";
            string apiSecret = "87745d866345256b......fbae27c502a";
            // ID app del servizio
            string appId = "f7ff497727ab2d55ea01d9984ef8068c";
            // Periodo di validità, in secondi
            int expires = 3600;

            // Costruisci 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}"));

            // Aggiungi il segreto API
            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 chiave API e il segreto API
    apiKey := "6a47f7f8ff6......68744b4bcf"
    apiSecret := "87745d866345256b......fbae27c502a"
    // Il tuo ID app del servizio
    appId := "f7ff497727ab2d55ea01d9984ef8068c"
    // Durata valida, in secondi
    expires := 3600

    // Costruisci 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 le stringhe
    builder := strings.Builder{}
    for _, key := range keys {
        builder.WriteString(fmt.Sprintf("%s%v", key, data[key]))
    }

    // Aggiungi il segreto API
    builder.WriteString(apiSecret)

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

Consiglio

Durante la creazione della firma, converti ACL in stringa JSON.

Ottenere token

Aggiungi la firma generata all'elenco dei parametri e invia una richiesta all'endpoint /token/v2 per ottenere il token.

Indirizzo di richiesta: https://uac.easyar.com/token/v2 o https://uac-na1.easyar.com/token/v2 (Nord America zona 1)
Metodo di richiesta: POST
Intestazione: Content-Type: application/json
Parametri di richiesta: {"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 è 0 nella risposta, indica successo.

Formato risposta 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 di autenticazione per richieste di servizio.
expiration: Ora di scadenza del token, dopo la scadenza è necessario richiederne uno nuovo.

Formato risposta di errore:

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

Utilizzare token

Nelle richieste https di business, aggiungi il token nell'header con il formato: {"Authorization": "nuPDCj......xstQX"}.

Quando invii richieste API di business, aggiungi il parametro appId (per l'origine, consulta il servizio pertinente nel centro di sviluppo).

Descrizione codici di errore

Durante la generazione o l'utilizzo del token, potrebbero verificarsi errori o situazioni anomale. Per aiutare gli sviluppatori a identificare rapidamente i problemi e adottare soluzioni efficaci, di seguito sono descritti in dettaglio i codici di errore comuni e il loro significato:

Codice errore	Messaggio errore	Descrizione errore	Soluzione
4001011	API Key invalid	API Key non valida	Verifica la presenza di questa API Key in "API KEY servizi cloud"
4001012	Timestamp invalid	Timestamp non valido	Il timestamp è in millisecondi e non deve discostarsi più di 5 minuti dal tempo standard
4001015	Signature invalid	Firma non valida	Controlla l'algoritmo di firma e verifica che API Secret corrisponda a API KEY
4001017	AppId is not authorized by this API Key	API Key non autorizzata per questo AppId	Controlla se il servizio di AppId è associato a questa API Key
4001018	Base64 decode error	Authorization nell'header non è in formato base64 valido	Utilizza il token ottenuto senza modifiche
4001019	Decryption error	Authorization nell'header non è generato da EasyAR	Utilizza il token ottenuto senza modifiche
4001022	API Key's resource is empty	API Key non ha servizi cloud associati	Controlla se API Key è associata a servizi cloud e se questi sono scaduti
4001024	Token is expired	Token scaduto	Rigenera
4001025	Token generate fail	Generazione token fallita	Contatta il supporto tecnico: support@easyar.com

Table of Contents

Ottenere e utilizzare API Key

Creare API Key

Consiglio

Avvertenza

Ottenere token

Ottenere token dal centro di sviluppo

Nota

Generare token utilizzando API Key e API Secret

Avvertenza

Parametri della richiesta

Metodo di firma

Esempio di firma

Consiglio

Ottenere token

Utilizzare token

Descrizione codici di errore