Obtenir et utiliser une clé API

La création de clés API dans le centre de développement EasyAR n'est pas limitée. Il est recommandé d'attribuer des clés API distinctes à différentes applications pour un contrôle plus précis des autorisations.

Créer une clé API

Connectez-vous au centre de développement EasyAR. Si vous utilisez une clé API pour la première fois, veuillez d'abord en créer une en suivant ces étapes :

Sous "Autorisation", cliquez sur "Clé API des services cloud"
Sur la page "Clé API", cliquez sur le bouton "Créer une clé API"

APIKey

Remplissez le "Nom de l'application"
Cochez les services cloud requis en fonction des besoins de votre application. Il n'est pas recommandé de tout autoriser.
Cliquez sur "OK"

Astuce

Pour utiliser SpatialMap, cochez SpatialMap.

Pour utiliser la reconnaissance cloud, cochez Reconnaissance cloud.

Pour utiliser Mega Landmark, cochez Mega Landmark. L'utilisation de cette fonction nécessite une demande commerciale préalable.

Pour utiliser le centre d'opérations AR, cochez Centre d'opérations AR. L'utilisation de cette fonction nécessite une demande commerciale préalable.

Pour utiliser le positionnement cloud Mega Block, cochez Mega Block.

APIKey

Une clé API et un secret API seront générés sur la page, comme illustré ci-dessous. Veillez à ne pas les divulguer.

APIKey

Avertissement

N'utilisez pas directement la clé API et le secret API dans des applications clientes (comme Web, mini-programmes WeChat, etc.).

Obtenir un jeton

Il existe deux façons d'obtenir un jeton : 1. Directement depuis le centre de développement ; 2. En écrivant du code. Si vous avez besoin de contrôler les autorisations d'accès aux ressources, il est recommandé d'utiliser la deuxième méthode. Voici les deux méthodes, choisissez celle qui correspond à vos besoins.

Obtenir un jeton depuis le centre de développement

Sélectionnez la clé API que vous souhaitez utiliser et cliquez sur "Gérer" à droite

APIKeyToken

Sélectionnez une durée de validité pour le jeton
Cliquez sur "Générer un jeton"
Cliquez sur "Copier"

APIKeyToken

Note

‌La sécurité est la raison principale de la définition de la durée de validité du jeton.‌ Si la durée de validité du jeton est trop longue, en cas de fuite ou de vol, un attaquant pourrait l'utiliser longtemps, entraînant une fuite de données ou des opérations non autorisées. La durée de validité limite la fenêtre d'efficacité du jeton, réduisant ainsi les dommages potentiels même en cas de fuite.

Générer un jeton à l'aide de la clé API et du secret API

La génération du jeton nécessite une signature des paramètres principaux pour garantir la sécurité de la transmission. Ces données signées sont ensuite envoyées au service STS (Security Token Service) pour authentification. Après validation par le service STS, un jeton d'accès temporaire est émis. Ce jeton n'est valable que pendant une fenêtre de temps spécifiée. Une nouvelle authentification est nécessaire après expiration.

Avertissement

Ne générez pas de jeton dans le code client. Générez plutôt le jeton côté serveur avant de le transmettre au client.

Paramètres de la requête

Nom du champ	Type	Obligatoire	Description
apiKey	string	Oui	Clé API
expires	int	Oui	Durée de validité du Token généré, en secondes
acl	string	Oui	Liste de contrôle d'accès (Access Control List), contrôle les autorisations de ressource accessibles par le token
timestamp	long	Oui	Horodatage, en millisecondes
signature	string	Oui	Signature

acl : Composée d'un ou plusieurs AC (contrôle d'accès). Chaque AC comprend quatre parties : service, effect, resource, permission.

service : Type de service, actuellement supporte ecs:crs (reconnaissance cloud), ecs:spatialmap (carte spatiale éparse), ecs:cls (positionnement cloud Mega Block), ecs:vps1 (landmark).
resource : ID d'application du service spécifique, par exemple CRS AppId de la bibliothèque de reconnaissance cloud.
effect : Spécifie si l'accès correspondant à cet élément resource peut être exécuté. Valeurs : Allow, Deny.
permission : Autorisations. Valeurs : READ, WRITE.

Exemple de structure :

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

Méthode de signature

Triez tous les paramètres de la requête par ordre alphabétique des clés.
Pour chaque paramètre, concaténez le nom de la clé et sa valeur en une chaîne.
Concaténez toutes les chaînes obtenues, puis ajoutez le secret API à la fin.
Le hash SHA256 (en hexadécimal) de la chaîne finale constitue la signature.

Exemple de signature

<?php
// Votre clé API et secret API
$apiKey = '6a47f7f8ff6......68744b4bcf';
$apiSecret = '87745d866345256b......fbae27c502a';
// Votre ID d'application de service
$appId = 'f7ff497727ab2d55ea01d9984ef8068c';
// Durée de validité, en secondes
$expires = 3600;

// Construire les paramètres à signer
$data = [
    'apiKey' => $apiKey,
    'expires' => $expires,
    'acl' => '[{"service":"ecs:crs","resource":["'. $appId .'"],"effect":"Allow","permission":["READ"]}]',
    'timestamp' => time() * 1000,
];

// Trier
ksort($data);

// Concaténer les chaînes
$builder = [];
foreach ($data as $key => $value) {
    array_push($builder, $key . $value);
}

// Concaténer le secret API
array_push($builder, $apiSecret);

// Générer la signature
$signature = hash('sha256', implode('', $builder));
echo $signature;

const crypto = require('crypto');

// Votre clé API et secret API
const apiKey = '6a47f7f8ff6......68744b4bcf'
const apiSecret = '87745d866345256b......fbae27c502a'
// Votre ID d'application de service
const appId = 'f7ff497727ab2d55ea01d9984ef8068c';
// Durée de validité, en secondes
const expires = 3600

// Construire les paramètres à signer
const data = {
    apiKey: apiKey,
    expires: expires,
    acl: `[{"service":"ecs:crs","resource":["${appId}"],"effect":"Allow","permission":["READ"]}]`,
    timestamp: Date.now(),
}

// Trier et concaténer la chaîne
let builder = [];
Object.keys(data).sort().forEach(key => builder.push(`${key}${data[key]}`));

// Concaténer le secret API
builder.push(apiSecret);

// Générer la signature
const signature = crypto.createHash('sha256').update(builder.join('')).digest('hex');
console.info(signature);

import time
import hashlib

# Votre clé API et secret API
apiKey = '6a47f7f8ff6......68744b4bcf'
apiSecret = '87745d866345256b......fbae27c502a'
# Votre ID d'application de service
appId = 'f7ff497727ab2d55ea01d9984ef8068c'
# Durée de validité, en secondes
expires = 3600

# Construire les paramètres à signer
data = dict(sorted({
    'apiKey': apiKey,
    'expires': expires,
    'acl': '[{"service":"ecs:crs","resource":["'+ appId +'"],"effect":"Allow","permission":["READ"]}]',
    'timestamp': int(time.time() * 1000),
}.items()))

# Concaténer la chaîne
builder = [f'{key}{value}' for key, value in data.items()]

# Ajouter le secret API
builder.append(apiSecret)

# Générer la signature
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 {
        // Votre clé API et secret API
        String apiKey = "6a47f7f8ff6......68744b4bcf";
        String apiSecret = "87745d866345256b......fbae27c502a";
        // ID d'application du service
        String appId = "f7ff497727ab2d55ea01d9984ef8068c";
        // Durée de validité, en secondes
        int expires = 3600;

        // Construire les paramètres à signer
        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\"]}]");

        // Concaténer les chaînes de caractères
        StringBuilder builder = new StringBuilder();
        data.forEach((key, value) -> builder.append(String.format("%s%s", key, value)));

        // Concaténer le secret API
        builder.append(apiSecret);

        // Générer la signature
        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) {
            // Votre clé API et secret API
            string apiKey = "6a47f7f8ff6......68744b4bcf";
            string apiSecret = "87745d866345256b......fbae27c502a";
            // ID d'application du service
            string appId = "f7ff497727ab2d55ea01d9984ef8068c";
            // Durée de validité, en secondes
            int expires = 3600;

            // Construction des paramètres à signer
            SortedDictionary<string, object> data = new() {
                { "apiKey", apiKey },
                { "expires", expires },
                { "timestamp", DateTimeOffset.Now.ToUnixTimeMilliseconds() },
                { "acl", "[{\"service\":\"ecs:crs\",\"resource\":[\"" + appId + "\"],\"effect\":\"Allow\",\"permission\":[\"READ\"]}]" }
            };

            // Concaténation de la chaîne
            StringBuilder builder = new StringBuilder();
            data.ToList().ForEach(pair => builder.Append($"{pair.Key}{pair.Value}"));

            // Ajout du secret API
            builder.Append(apiSecret);

            // Génération de la signature
            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() {
    // Votre clé API et secret API
    apiKey := "6a47f7f8ff6......68744b4bcf"
    apiSecret := "87745d866345256b......fbae27c502a"
    // Votre ID d'application de service
    appId := "f7ff497727ab2d55ea01d9984ef8068c"
    // Durée de validité, en secondes
    expires := 3600

    // Construire les paramètres à signer
    data := map[string]any{
        "apiKey":    apiKey,
        "expires":   expires,
        "acl":       `[{"service":"ecs:crs","resource":["` + appId + `"],"effect":"Allow","permission":["READ"]}]`,
        "timestamp": time.Now().Unix() * 1000,
    }

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

    // Concaténer les chaînes
    builder := strings.Builder{}
    for _, key := range keys {
        builder.WriteString(fmt.Sprintf("%s%v", key, data[key]))
    }

    // Concaténer le secret API
    builder.WriteString(apiSecret)

    // Générer la signature
    signature := fmt.Sprintf("%x", sha256.Sum256([]byte(builder.String())))
    fmt.Println(signature)
}

Astuce

Lors de l'ajout à la signature, convertissez l'ACL en chaîne JSON.

Obtenir le jeton

Ajoutez la signature générée à la liste des paramètres et envoyez la requête à l'endpoint /token/v2 pour obtenir le jeton.

Adresse de la requête : https://uac.easyar.com/token/v2 ou https://uac-na1.easyar.com/token/v2 (zone nord-américaine 1)
Méthode de requête : POST
En-tête de requête : Content-Type: application/json
Paramètres de requête : {"apiKey":"6a47f7f8ff6......68744b4bcf","expires":3600,"acl":"[{\"service\":\"ecs:crs\",\"resource\":[\"f7ff497727ab2d55ea01d9984ef8068c\"],\"effect\":\"Allow\",\"permission\":[\"READ\"]}]","timestamp":1765954279002,"signature":"32f18a37fc3c18......55c4943af9"}

Exemple :

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

Dans le résultat de retour, si statusCode est 0, cela indique un succès.

Format de retour 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 d'authentification pour les requêtes métier.
expiration : Date d'expiration du token. Un nouveau token doit être demandé après expiration.

Format de retour d'erreur :

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

Utiliser le jeton

Dans les requêtes https métier, ajoutez le jeton dans l'en-tête de la requête au format : {"Authorization": "nuPDCj......xstQX"}.

Lors de l'envoi de requêtes API métier, le paramètre appId est requis (consultez le service concerné dans le centre de développement pour son origine).

Explication des codes d'erreur

Lors de la génération ou de l'utilisation d'un jeton, diverses erreurs ou situations exceptionnelles peuvent survenir. Pour aider les développeurs à identifier rapidement les problèmes et à prendre des mesures correctives, voici une explication détaillée des codes d'erreur courants et de leur signification :

Code d'erreur	Message d'erreur	Explication	Solution
4001011	Clé API invalide	La clé API est invalide	Vérifiez si cette clé API existe sous "Clé API des services cloud"
4001012	Horodatage invalide	L'horodatage est invalide	L'unité de l'horodatage est la milliseconde. L'écart avec l'heure standard ne doit pas dépasser 5 minutes.
4001015	Signature invalide	La signature est invalide	Vérifiez l'algorithme de signature et assurez-vous que le secret API correspond à la clé API.
4001017	AppId n'est pas autorisé par cette clé API	La clé API n'a pas autorisé cet AppId	Vérifiez si le service contenant l'AppId est associé à cette clé API.
4001018	Erreur de décodage Base64	L'Authorization défini dans l'en-tête de la requête n'est pas au format base64 valide	Utilisez le jeton obtenu sans modification.
4001019	Erreur de déchiffrement	L'Authorization défini dans l'en-tête de la requête n'a pas été généré par EasyAR	Utilisez le jeton obtenu sans modification.
4001022	La ressource de la clé API est vide	La clé API n'est associée à aucun service cloud	Vérifiez si la clé API est associée à un service cloud et si celui-ci est toujours valide.
4001024	Le jeton a expiré	Le jeton a expiré	Régénérez-le.
4001025	Échec de la génération du jeton	La génération du jeton a échoué	Contactez le support technique : support@easyar.com

Table of Contents

Obtenir et utiliser une clé API

Créer une clé API

Astuce

Avertissement

Obtenir un jeton

Obtenir un jeton depuis le centre de développement

Note

Générer un jeton à l'aide de la clé API et du secret API

Avertissement

Paramètres de la requête

Méthode de signature

Exemple de signature

Astuce

Obtenir le jeton

Utiliser le jeton

Explication des codes d'erreur