Abrufen und verwenden von API Key

In der EasyAR Entwicklungszentrale gibt es keine Beschränkung für die Erstellung von API Keys. Es wird empfohlen, verschiedenen Anwendungen separate API Keys zuzuweisen, um Berechtigungen präziser zu steuern.

Erstellen eines API Key

Melden Sie sich im EasyAR Entwicklungszentrum an. Wenn Sie zum ersten Mal einen API Key verwenden, erstellen Sie bitte zunächst einen API Key. Die Schritte sind wie folgt:

Klicken Sie unter „Autorisierung“ auf „Cloud-Dienste API KEY“
Klicken Sie auf der „API KEY“-Seite auf den Button „API KEY erstellen“

APIKey

Tragen Sie einen „Anwendungsnamen“ ein
Aktivieren Sie die benötigten Cloud-Dienste entsprechend Ihren Anwendungsanforderungen; eine vollständige Autorisierung wird nicht empfohlen.
Klicken Sie auf „Bestätigen“

Tipp

Bei der Verwendung von SpatialMap aktivieren Sie SpatialMap.

Bei der Verwendung von Cloud-Erkennung aktivieren Sie Cloud-Erkennung.

Bei der Verwendung von Mega Landmark aktivieren Sie Mega Landmark; diese Funktion muss vor der Nutzung beim Vertrieb beantragt werden.

Bei der Verwendung des AR Betriebszentrums aktivieren Sie AR Betriebszentrum; diese Funktion muss vor der Nutzung beim Vertrieb beantragt werden.

Bei der Verwendung von Mega Block Cloud-Positionierung aktivieren Sie Mega Block.

APIKey

Es werden nun API Key und API Secret generiert, wie unten gezeigt. Achten Sie darauf, diese nicht preiszugeben.

APIKey

Warnung

Verwenden Sie API Key und API Secret nicht direkt in Client-Anwendungen (z.B. Web, WeChat Mini-Programme usw.).

Abrufen eines Tokens

Es gibt zwei Möglichkeiten, ein Token zu erhalten: 1. Direkt aus dem Entwicklungszentrum; 2. Durch Programmierung. Wenn Sie Zugriffsrechte auf Ressourcen kontrollieren müssen, wird die zweite Methode empfohlen. Nachfolgend werden beide Methoden beschrieben. Wählen Sie je nach Bedarf aus.

Token aus dem Entwicklungszentrum abrufen

Wählen Sie den gewünschten API Key aus und klicken Sie rechts auf „Verwalten“

APIKeyToken

Wählen Sie eine Gültigkeitsdauer für das Token aus
Klicken Sie auf „Token generieren“
Klicken Sie auf „Kopieren“

APIKeyToken

Anmerkung

Sicherheit ist der Hauptgrund für die Festlegung der Token-Gültigkeit. Wenn ein Token zu lange gültig ist, kann es bei Verlust oder Diebstahl lange missbraucht werden, was zu Datenlecks oder unbefugten Aktionen führt. Eine zeitliche Begrenzung reduziert das Risiko, indem der Schaden zeitlich eingegrenzt wird.

Generieren eines Tokens mit API Key und API Secret

Der Token-Generierungsprozess erfordert eine Signierung der Kernparameter zur Gewährleistung der Übertragungssicherheit. Die signierten Daten werden dann an den STS-Dienst (Security Token Service) zur Authentifizierung gesendet. Nach erfolgreicher Validierung stellt der STS-Dienst ein temporäres Zugriffstoken aus, das nur innerhalb eines bestimmten Zeitfensters gültig ist. Nach Ablauf muss der Authentifizierungsprozess neu gestartet werden.

Warnung

Generieren Sie das Token nicht im Client-Code, sondern auf dem Server und übergeben Sie es dann an den Client.

Anforderungsparameter

Feldname	Typ	Erforderlich?	Beschreibung
apiKey	string	Ja	API Key
expires	int	Ja	Gültigkeitsdauer des generierten Tokens in Sekunden
acl	string	Ja	Zugriffssteuerungsliste (Access Control List), steuert Ressourcenzugriffsrechte des Tokens
timestamp	long	Ja	Zeitstempel in Millisekunden
signature	string	Ja	Signatur

acl: Besteht aus einem oder mehreren ACs (Zugriffskontrollen). Jeder AC umfasst vier Teile: service, effect, resource, permission.

service: Diensttyp, derzeit unterstützt: ecs:crs (Cloud Recognition), ecs:spatialmap (Sparse Spatial Map), ecs:cls (Mega Block Cloud Positioning), ecs:vps1 (Landmark)
resource: App-ID des spezifischen Dienstes, z.B. CRS AppId der Cloud Recognition-Bibliothek
effect: Legt fest, ob der Zugriff bei Übereinstimmung mit dieser resource-Konfiguration ausgeführt werden kann. Werte: Allow, Deny
permission: Berechtigungswerte: READ, WRITE

Strukturbeispiel:

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

Signaturmethode

Sortieren Sie alle Parameter des Requests nach Schlüsselname
Verketten Sie für jeden Parameter Schlüsselname und Wert zu einer Zeichenkette
Verketten Sie alle resultierenden Zeichenketten und hängen Sie das API Secret an
Der Hexadezimalwert des SHA-256-Hash der Zeichenkette ist die Signatur

Signaturbeispiel

<?php
// Ihr API-Schlüssel und API-Geheimnis
$apiKey = '6a47f7f8ff6......68744b4bcf';
$apiSecret = '87745d866345256b......fbae27c502a';
// Ihre Dienst-App-ID
$appId = 'f7ff497727ab2d55ea01d9984ef8068c';
// Gültigkeitsdauer in Sekunden
$expires = 3600;

// Zu signierende Parameter erstellen
$data = [
    'apiKey' => $apiKey,
    'expires' => $expires,
    'acl' => '[{"service":"ecs:crs","resource":["'. $appId .'"],"effect":"Allow","permission":["READ"]}]',
    'timestamp' => time() * 1000,
];

// Sortieren
ksort($data);

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

// API-Geheimnis anhängen
array_push($builder, $apiSecret);

// Signatur generieren
$signature = hash('sha256', implode('', $builder));
echo $signature;

const crypto = require('crypto');

// Ihr API-Schlüssel und API-Geheimnis
const apiKey = '6a47f7f8ff6......68744b4bcf'
const apiSecret = '87745d866345256b......fbae27c502a'
// Ihre Dienst-App-ID
const appId = 'f7ff497727ab2d55ea01d9984ef8068c';
// Gültigkeitsdauer in Sekunden
const expires = 3600

// Parameter für die zu signierenden Daten erstellen
const data = {
    apiKey: apiKey,
    expires: expires,
    acl: `[{"service":"ecs:crs","resource":["${appId}"],"effect":"Allow","permission":["READ"]}]`,
    timestamp: Date.now(),
}

// Zeichenfolgen sortieren und verketten
let builder = [];
Object.keys(data).sort().forEach(key => builder.push(`${key}${data[key]}`));

// API-Geheimnis anhängen
builder.push(apiSecret);

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

import time
import hashlib

# Ihre api key und api secret
apiKey = '6a47f7f8ff6......68744b4bcf'
apiSecret = '87745d866345256b......fbae27c502a'
# Ihre service app id
appId = 'f7ff497727ab2d55ea01d9984ef8068c'
# Gültigkeitsdauer, in sekunden
expires = 3600

# Parameter für signaturerstellung
data = dict(sorted({
    'apiKey': apiKey,
    'expires': expires,
    'acl': '[{"service":"ecs:crs","resource":["'+ appId +'"],"effect":"Allow","permission":["READ"]}]',
    'timestamp': int(time.time() * 1000),
}.items()))

# Zeichenkette verketten
builder = [f'{key}{value}' for key, value in data.items()]

# Api secret anhängen
builder.append(apiSecret)

# Signatur generieren
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 {
        // Ihr API Key und API Secret
        String apiKey = "6a47f7f8ff6......68744b4bcf";
        String apiSecret = "87745d866345256b......fbae27c502a";
        // App-ID des Dienstes
        String appId = "f7ff497727ab2d55ea01d9984ef8068c";
        // Gültigkeitsdauer in Sekunden
        int expires = 3600;

        // Parameter für die zu signierenden Daten erstellen
        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\"]}]");

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

        // API Secret anhängen
        builder.append(apiSecret);

        // Signatur generieren
        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) {
            // Ihre API Key und API Secret
            string apiKey = "6a47f7f8ff6......68744b4bcf";
            string apiSecret = "87745d866345256b......fbae27c502a";
            // Die App-ID des Dienstes
            string appId = "f7ff497727ab2d55ea01d9984ef8068c";
            // Gültigkeitsdauer in Sekunden
            int expires = 3600;

            // Parameter für die Signatur erstellen
            SortedDictionary<string, object> data = new() {
                { "apiKey", apiKey },
                { "expires", expires },
                { "timestamp", DateTimeOffset.Now.ToUnixTimeMilliseconds() },
                { "acl", "[{\"service\":\"ecs:crs\",\"resource\":[\"" + appId + "\"],\"effect\":\"Allow\",\"permission\":[\"READ\"]}]" }
            };

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

            // API Secret anhängen
            builder.Append(apiSecret);

            // Signatur generieren
            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() {
    // Ihr API Key und API Secret
    apiKey := "6a47f7f8ff6......68744b4bcf"
    apiSecret := "87745d866345256b......fbae27c502a"
    // Ihre Dienst-App-ID
    appId := "f7ff497727ab2d55ea01d9984ef8068c"
    // Gültigkeitsdauer in Sekunden
    expires := 3600

    // Parameter für die Signaturerstellung
    data := map[string]any{
        "apiKey":    apiKey,
        "expires":   expires,
        "acl":       `[{"service":"ecs:crs","resource":["` + appId + `"],"effect":"Allow","permission":["READ"]}]`,
        "timestamp": time.Now().Unix() * 1000,
    }

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

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

    // API Secret anfügen
    builder.WriteString(apiSecret)

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

Tipp

Beim Einbinden in die Signatur muss ACL in einen JSON-String konvertiert werden.

Token abrufen

Fügen Sie die generierte Signatur zur Parameterliste hinzu und senden Sie die Anfrage an den Endpunkt /token/v2, um das Token zu erhalten.

Anfrageadresse: https://uac.easyar.com/token/v2 oder https://uac-na1.easyar.com/token/v2 (Nordamerika-1-Zone)
Anfragemethode: POST
Anfragekopf: Content-Type: application/json
Anfrageparameter: {"apiKey":"6a47f7f8ff6......68744b4bcf","expires":3600,"acl":"[{\"service\":\"ecs:crs\",\"resource\":[\"f7ff497727ab2d55ea01d9984ef8068c\"],\"effect\":\"Allow\",\"permission\":[\"READ\"]}]","timestamp":1765954279002,"signature":"32f18a37fc3c18......55c4943af9"}

Beispiel:

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

Wenn statusCode im Rückgabeergebnis 0 ist, bedeutet das Erfolg.

Normales Rückgabeformat:

{
  "statusCode": 0,
  "timestamp": 1765954874399,
  "msg": "Success",
  "result": {
    "apiKey": "6a47f7f8ff6......68744b4bcf",
    "expires": 3600,
    "token": "nuPDCj......xstQX",
    "expiration": "2025-12-17T08:01:14.399+0000"
  }
}

token: Das Token zur Authentifizierung von Geschäftsanfragen.
expiration: Die Ablaufzeit des Tokens. Nach Ablauf muss ein neues Token angefordert werden.

Fehlerrückgabeformat:

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

Verwenden des Tokens

Fügen Sie das Token im Header von HTTPS-Anfragen hinzu. Format: {"Authorization": "nuPDCj......xstQX"}.

Beim Senden von API-Anfragen muss der Parameter appId hinzugefügt werden (Informationen zur Beschaffung finden Sie im Entwicklungszentrum unter dem entsprechenden Dienst).

Fehlercode-Erläuterung

Während der Token-Generierung und -Verwendung können verschiedene Fehler auftreten. Zur schnellen Problembehebung finden Sie nachfolgend eine detaillierte Erklärung gängiger Fehlercodes:

Fehlercode	Fehlermeldung	Fehlerbeschreibung	Lösung
4001011	API Key invalid	API Key ungültig	Prüfen Sie unter „Cloud-Dienste API KEY“, ob dieser API Key existiert
4001012	Timestamp invalid	Zeitstempel ungültig	Zeitstempel in Millisekunden; Abweichung zur Standardzeit sollte 5 Minuten nicht überschreiten
4001015	Signature invalid	Signatur ungültig	Prüfen Sie den Signaturalgorithmus und ob API Secret zum API Key passt
4001017	AppId is not authorized by this API Key	API Key hat diese AppId nicht autorisiert	Prüfen Sie, ob der Dienst der AppId diesem API Key zugeordnet ist
4001018	Base64 decode error	Authorization im Header ist kein gültiges Base64-Format	Verwenden Sie das erhaltene Token direkt ohne Bearbeitung
4001019	Decryption error	Authorization im Header wurde nicht von EasyAR generiert	Verwenden Sie das erhaltene Token direkt ohne Bearbeitung
4001022	API Key's resource is empty	API Key hat keine zugeordneten Cloud-Dienste	Prüfen Sie, ob dem API Key Cloud-Dienste zugeordnet sind und ob diese abgelaufen sind
4001024	Token is expired	Token ist abgelaufen	Neu generieren
4001025	Token generate fail	Token-Generierung fehlgeschlagen	Kontaktieren Sie den technischen Support: support@easyar.com

Table of Contents

Abrufen und verwenden von API Key

Erstellen eines API Key

Tipp

Warnung

Abrufen eines Tokens

Token aus dem Entwicklungszentrum abrufen

Anmerkung

Generieren eines Tokens mit API Key und API Secret

Warnung

Anforderungsparameter

Signaturmethode

Signaturbeispiel

Tipp

Token abrufen

Verwenden des Tokens

Fehlercode-Erläuterung