API Key erhalten und verwenden

Im EasyAR Developer Center gibt es keine Mengenbegrenzung für API Keys. Es wird empfohlen, verschiedenen Anwendungen unabhängige API Keys zuzuweisen, damit permissions genauer verwaltet werden können.

API Key erstellen

Melden Sie sich im EasyAR Developer Center an. Wenn Sie API Key zum ersten Mal verwenden, erstellen Sie zunächst einen API Key:

Klicken Sie unter "Authorization" auf "Cloud Service API KEY"
Klicken Sie auf der Seite "API KEY" auf "Create API KEY"

APIKey

Füllen Sie "Application Name" aus
Wählen Sie die benötigten cloud services entsprechend den Anforderungen Ihrer Anwendung aus. Es wird nicht empfohlen, alle Berechtigungen zu erteilen.
Klicken Sie auf "OK"

Tipp

Wenn Sie SpatialMap verwenden, wählen Sie SpatialMap.

Wenn Sie Cloud Recognition verwenden, wählen Sie Cloud Recognition.

Wenn Sie Mega Landmark verwenden, wählen Sie Mega Landmark. Vor Nutzung dieser Funktion ist eine Beantragung beim Vertrieb erforderlich.

Wenn Sie AR Operation Center verwenden, wählen Sie AR Operation Center. Vor Nutzung dieser Funktion ist eine Beantragung beim Vertrieb erforderlich.

Wenn Sie Mega Block cloud localization verwenden, wählen Sie Mega Block.

APIKey

Nun werden API Key und API Secret auf der Seite erzeugt, wie unten gezeigt. Achten Sie darauf, sie nicht offenzulegen.

APIKey

Warnung

Verwenden Sie API Key und API Secret nicht direkt in client-Anwendungen wie Web oder WeChat Mini Program.

Token erhalten

Es gibt zwei Möglichkeiten, einen Token zu erhalten: 1. direkt aus dem Developer Center; 2. per Code. Wenn Sie den Zugriff auf resources kontrollieren müssen, wird die zweite Methode empfohlen. Beide Methoden werden im Folgenden beschrieben.

Token aus dem Developer Center erhalten

Wählen Sie einen API Key aus und klicken Sie rechts auf "Manage"

APIKeyToken

Wählen Sie eine Gültigkeitsdauer für den Token
Klicken Sie auf "Generate Token"
Klicken Sie auf "Copy"

APIKeyToken

Anmerkung

Sicherheit ist der wichtigste Grund für die Festlegung der Token-Gültigkeitsdauer. Ist sie zu lang, kann ein Angreifer einen geleakten oder gestohlenen Token lange nutzen und dadurch Datenlecks oder nicht autorisierte Vorgänge verursachen. Die Gültigkeitsdauer begrenzt das Zeitfenster des Tokens; selbst bei einem Leak bleibt der Schaden zeitlich begrenzt.

Token mit API Key und API Secret erzeugen

Beim Erzeugen eines Tokens müssen Kernparameter signiert werden, um die Übertragungssicherheit zu gewährleisten. Danach werden die signierten Daten an den STS (Security Token Service) zur Identitätsprüfung gesendet. Nach erfolgreicher Prüfung stellt STS einen temporären access Token aus, der nur im angegebenen Zeitfenster gültig ist; nach Ablauf muss die Authentifizierung erneut gestartet werden.

Warnung

Erzeugen Sie Token nicht im client code, sondern serverseitig und übergeben Sie sie dann an den client.

Request-Parameter

Feldname	Typ	Erforderlich	Beschreibung
apiKey	string	Ja	API Key
expires	int	Ja	Gültigkeitsdauer des erzeugten Token, in Sekunden
acl	string	Ja	Access Control List, steuert die resource-Berechtigungen, auf die token zugreifen kann
timestamp	long	Ja	Timestamp, in Millisekunden
signature	string	Ja	Signature

acl: besteht aus einem oder mehreren AC (access control). Jeder AC enthält vier Teile: service, effect, resource und permission.

service: Servicetyp; derzeit unterstützt werden ecs:crs (Cloud Recognition), ecs:spatialmap (Sparse Spatial Map), ecs:cls (Mega Block Cloud Localization), ecs:vps1 (landmark)
resource: app id des konkreten Services, z. B. CRS AppId der Cloud Recognition library
effect: legt fest, ob der Zugriff, der zu dieser resource-Konfiguration passt, ausgeführt werden darf; Werte Allow, Deny
permission: Berechtigungswerte READ, WRITE

Strukturbeispiel:

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

Signature-Methode

Sortieren Sie alle request-Parameter nach key name
Verketten Sie für jeden Parameter key name und value zu einem string
Verketten Sie alle so entstandenen strings und hängen Sie am Ende API Secret an
Berechnen Sie den sha256 hash des strings; der hexadezimale Wert ist die signature

Signature-Beispiel

<?php
// 您的 API Key 与 API Secret
$apiKey = '6a47f7f8ff6......68744b4bcf';
$apiSecret = '87745d866345256b......fbae27c502a';
// 您的服务 App ID
$appId = 'f7ff497727ab2d55ea01d9984ef8068c';
// 有效时间, 单位为秒
$expires = 3600;

// 构建待签名参数
$data = [
    'apiKey' => $apiKey,
    'expires' => $expires,
    'acl' => '[{"service":"ecs:crs","resource":["'. $appId .'"],"effect":"Allow","permission":["READ"]}]',
    'timestamp' => time() * 1000,
];

// 排序
ksort($data);

// 拼接字符串
$builder = [];
foreach ($data as $key => $value) {
    array_push($builder, $key . $value);
}

// 拼接 API Secret
array_push($builder, $apiSecret);

// 生成签名
$signature = hash('sha256', implode('', $builder));
echo $signature;

const crypto = require('crypto');

// 您的 API Key 与 API Secret
const apiKey = '6a47f7f8ff6......68744b4bcf'
const apiSecret = '87745d866345256b......fbae27c502a'
// 您的服务 App ID
const appId = 'f7ff497727ab2d55ea01d9984ef8068c';
// 有效时间, 单位为秒
const expires = 3600

// 构建待签名参数
const data = {
    apiKey: apiKey,
    expires: expires,
    acl: `[{"service":"ecs:crs","resource":["${appId}"],"effect":"Allow","permission":["READ"]}]`,
    timestamp: Date.now(),
}

// 排序与拼接字符串
let builder = [];
Object.keys(data).sort().forEach(key => builder.push(`${key}${data[key]}`));

// 拼接 API Secret
builder.push(apiSecret);

// 生成签名
const signature = crypto.createHash('sha256').update(builder.join('')).digest('hex');
console.info(signature);

import time
import hashlib

# 您的 API Key 与 API Secret
apiKey = '6a47f7f8ff6......68744b4bcf'
apiSecret = '87745d866345256b......fbae27c502a'
# 您的服务 App ID
appId = 'f7ff497727ab2d55ea01d9984ef8068c'
# 有效时间, 单位为秒
expires = 3600

# 构建待签名参数
data = dict(sorted({
    'apiKey': apiKey,
    'expires': expires,
    'acl': '[{"service":"ecs:crs","resource":["'+ appId +'"],"effect":"Allow","permission":["READ"]}]',
    'timestamp': int(time.time() * 1000),
}.items()))

# 拼接字符串
builder = [f'{key}{value}' for key, value in data.items()]

# 拼接 API Secret
builder.append(apiSecret)

# 生成签名
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 {
        // 您的 API Key 与 API Secret
        String apiKey = "6a47f7f8ff6......68744b4bcf";
        String apiSecret = "87745d866345256b......fbae27c502a";
        // 服务的 App ID
        String appId = "f7ff497727ab2d55ea01d9984ef8068c";
        // 有效时间, 单位为秒
        int expires = 3600;

        // 构建待签名参数
        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\"]}]");

        // 拼接字符串
        StringBuilder builder = new StringBuilder();
        data.forEach((key, value) -> builder.append(String.format("%s%s", key, value)));

        // 拼接 API Secret
        builder.append(apiSecret);

        // 生成签名
        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) {
            // 您的 API Key 与 API Secret
            string apiKey = "6a47f7f8ff6......68744b4bcf";
            string apiSecret = "87745d866345256b......fbae27c502a";
            // 服务的 App ID
            string appId = "f7ff497727ab2d55ea01d9984ef8068c";
            // 有效时间, 单位为秒
            int expires = 3600;

            // 构建待签名参数
            SortedDictionary<string, object> data = new() {
                { "apiKey", apiKey },
                { "expires", expires },
                { "timestamp", DateTimeOffset.Now.ToUnixTimeMilliseconds() },
                { "acl", "[{\"service\":\"ecs:crs\",\"resource\":[\"" + appId + "\"],\"effect\":\"Allow\",\"permission\":[\"READ\"]}]" }
            };

            // 拼接字符串
            StringBuilder builder = new StringBuilder();
            data.ToList().ForEach(pair => builder.Append($"{pair.Key}{pair.Value}"));

            // 拼接 API Secret
            builder.Append(apiSecret);

            // 生成签名
            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() {
    // 您的 API Key 与 API Secret
    apiKey := "6a47f7f8ff6......68744b4bcf"
    apiSecret := "87745d866345256b......fbae27c502a"
    // 您的服务 App ID
    appId := "f7ff497727ab2d55ea01d9984ef8068c"
    // 有效时间, 单位为秒
    expires := 3600

    // 构建待签名参数
    data := map[string]any{
        "apiKey":    apiKey,
        "expires":   expires,
        "acl":       `[{"service":"ecs:crs","resource":["` + appId + `"],"effect":"Allow","permission":["READ"]}]`,
        "timestamp": time.Now().Unix() * 1000,
    }

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

    // 拼接字符串
    builder := strings.Builder{}
    for _, key := range keys {
        builder.WriteString(fmt.Sprintf("%s%v", key, data[key]))
    }

    // 拼接 API Secret
    builder.WriteString(apiSecret)

    // 生成签名
    signature := fmt.Sprintf("%x", sha256.Sum256([]byte(builder.String())))
    fmt.Println(signature)
}

Tipp

Beim Hinzufügen der signature muss ACL in einen JSON string konvertiert werden.

Token erhalten

Fügen Sie die erzeugte signature zur Parameterliste hinzu und senden Sie den request an das interface /token/v2, um einen Token zu erhalten.

request-Adresse: https://uac.easyar.com/token/v2 oder https://uac-na1.easyar.com/token/v2 (North America 1)
request-Methode: POST
request-Header: Content-Type: application/json
request-Parameter:{"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 dies 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: Token für die Authentifizierung von business request.
expiration: Ablaufzeit des token; nach Ablauf muss token erneut beantragt werden.

Fehler-Rückgabeformat:

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

Token verwenden

Fügen Sie bei business https requests den Token dem request header im Format {"Authorization": "nuPDCj......xstQX"} hinzu.

Beim Senden von business API requests muss der Parameter appId hinzugefügt werden (die Quelle finden Sie im Developer Center beim entsprechenden service).

Beschreibung der error codes

Beim Erzeugen und Verwenden von Token können verschiedene errors oder exceptions auftreten. Damit developers Probleme schnell finden und passende Maßnahmen ergreifen können, werden häufige error codes und ihre Bedeutung unten erläutert:

Error code	Error message	Fehlerbeschreibung	Lösung
4001011	API Key invalid	API Key ist ungültig	Prüfen Sie, ob dieser API Key unter "Cloud Service API KEY" vorhanden ist
4001012	Timestamp invalid	Timestamp ist ungültig	Die Einheit des timestamp ist Millisekunden, und die Abweichung von der Standardzeit darf 5 Minuten nicht überschreiten
4001015	Signature invalid	Signature ist ungültig	Prüfen Sie den signature algorithm und ob API Secret und API KEY zusammenpassen
4001017	AppId is not authorized by this API Key	API Key hat diesen AppId nicht autorisiert	Prüfen Sie, ob der service, zu dem AppId gehört, mit diesem API Key verknüpft ist
4001018	Base64 decode error	Authorization im request header ist kein gültiges base64	Verwenden Sie den erhaltenen Token direkt ohne weitere Verarbeitung
4001019	Decryption error	Authorization im request header wurde nicht von EasyAR erzeugt	Verwenden Sie den erhaltenen Token direkt ohne weitere Verarbeitung
4001022	API Key's resource is empty	API Key hat keinen verknüpften cloud service	Prüfen Sie, ob API Key mit cloud service verknüpft ist und ob der service abgelaufen ist
4001024	Token is expired	Token ist abgelaufen	Neu erzeugen
4001025	Token generate fail	Token-Erzeugung fehlgeschlagen	Technischen Support kontaktieren: support@easyar.com

Table of Contents

API Key erhalten und verwenden

API Key erstellen

Tipp

Warnung

Token erhalten

Token aus dem Developer Center erhalten

Anmerkung

Token mit API Key und API Secret erzeugen

Warnung

Request-Parameter

Signature-Methode

Signature-Beispiel

Tipp

Token erhalten

Token verwenden

Beschreibung der error codes