Получение и использование API Key

В EasyAR Developer Center нет ограничения на количество создаваемых API Key. Рекомендуется выделять отдельный API Key для разных приложений, чтобы точнее управлять permissions.

Создание API Key

Войдите в EasyAR Developer Center. Если вы впервые используете API Key, сначала создайте API Key:

В разделе "Authorization" нажмите "Cloud Service API KEY"
На странице "API KEY" нажмите кнопку "Create API KEY"

APIKey

Заполните "Application Name"
Выберите необходимые cloud services в соответствии с потребностями приложения. Не рекомендуется выдавать все permissions.
Нажмите "OK"

Совет

При использовании SpatialMap выберите SpatialMap.

При использовании Cloud Recognition выберите Cloud Recognition.

При использовании Mega Landmark выберите Mega Landmark; перед использованием этой функции нужно обратиться в отдел продаж.

При использовании AR Operation Center выберите AR Operation Center; перед использованием этой функции нужно обратиться в отдел продаж.

При использовании Mega Block cloud localization выберите Mega Block.

APIKey

После этого на странице будут созданы API Key и API Secret, как показано ниже. Не раскрывайте их.

APIKey

Предупреждение

Не используйте API Key и API Secret напрямую в client-приложениях, таких как Web или WeChat Mini Program.

Получение Token

Token можно получить двумя способами: 1. напрямую в Developer Center; 2. программно. Если требуется контролировать permissions доступа к resources, рекомендуется второй способ. Ниже описаны оба варианта; выберите подходящий.

Получение Token из Developer Center

Выберите API Key, который хотите использовать, и нажмите "Manage" справа

APIKeyToken

Выберите срок действия Token
Нажмите "Generate Token"
Нажмите "Copy"

APIKeyToken

Примечание

Безопасность является основной причиной установки срока действия Token. Если срок действия Token слишком длинный, при утечке или краже злоумышленник сможет использовать его долгое время, что приведет к утечке данных или несанкционированным операциям. Ограничение срока действия сужает окно валидности Token; даже при утечке вред ограничен коротким временем.

Генерация Token с API Key и API Secret

Процесс генерации Token требует подписи основных параметров, чтобы обеспечить безопасность передачи. Затем подписанные данные отправляются в службу STS (Security Token Service) для аутентификации. После успешной проверки STS выдает временный access Token, действительный только в указанном временном окне; после истечения срока нужно повторить процесс аутентификации.

Предупреждение

Не генерируйте Token в client code; генерируйте Token на server side и передавайте его client для использования.

Request parameters

Имя поля	Тип	Обязательно	Описание
apiKey	string	Да	API Key
expires	int	Да	Время действия созданного Token, в секундах
acl	string	Да	Access Control List, управляет правами resource, доступными для token
timestamp	long	Да	Timestamp, в миллисекундах
signature	string	Да	Signature

acl: состоит из одного или нескольких AC (access control). Каждый AC содержит четыре части: service, effect, resource и permission.

service: тип сервиса; сейчас поддерживаются ecs:crs (Cloud Recognition), ecs:spatialmap (Sparse Spatial Map), ecs:cls (Mega Block Cloud Localization), ecs:vps1 (landmark)
resource: app id конкретного сервиса, например CRS AppId библиотеки Cloud Recognition
effect: определяет, может ли выполняться доступ, соответствующий этой конфигурации resource; значения Allow, Deny
permission: значения прав READ, WRITE

Пример структуры:

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

Метод signature

Отсортируйте все параметры request по имени key
Для каждого параметра объедините имя key и value в строку
Объедините все полученные строки и добавьте API Secret в конец
Вычислите sha256 hash строки; шестнадцатеричное значение является signature

Пример signature

<?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)
}

Совет

При добавлении signature ACL нужно преобразовать в JSON string.

Получение Token

Добавьте созданную signature в список параметров и отправьте request к interface /token/v2, чтобы получить Token.

Адрес request: https://uac.easyar.com/token/v2 или https://uac-na1.easyar.com/token/v2 (North America 1)
Метод request: POST
Заголовок request: Content-Type: application/json
Параметры request:{"apiKey":"6a47f7f8ff6......68744b4bcf","expires":3600,"acl":"[{\"service\":\"ecs:crs\",\"resource\":[\"f7ff497727ab2d55ea01d9984ef8068c\"],\"effect\":\"Allow\",\"permission\":[\"READ\"]}]","timestamp":1765954279002,"signature":"32f18a37fc3c18......55c4943af9"}

Пример:

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

Если statusCode в возвращенном результате равен 0, это означает успех.

Формат нормального ответа:

{
  "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 для аутентификации бизнес-request.
expiration: время истечения token; после истечения срока необходимо заново запросить token.

Формат ошибки:

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

Использование Token

В business https request добавьте Token в request header в формате: {"Authorization": "nuPDCj......xstQX"}.

При отправке business API request нужно добавить параметр appId (его источник см. в соответствующем service в Developer Center).

Описание error codes

Во время генерации и использования Token могут возникать различные errors или exceptions. Чтобы помочь developers быстро найти проблему и принять эффективные меры, ниже подробно описаны распространенные error codes и их значения:

Error code	Error message	Описание ошибки	Решение
4001011	API Key invalid	API Key недействителен	Проверьте, есть ли этот API Key в "Cloud Service API KEY"
4001012	Timestamp invalid	Timestamp недействителен	Единица timestamp - миллисекунды; отклонение от стандартного времени не должно превышать 5 минут
4001015	Signature invalid	Signature недействительна	Проверьте алгоритм signature и соответствие API Secret и API KEY
4001017	AppId is not authorized by this API Key	API Key не авторизовал этот AppId	Проверьте, связан ли service, которому принадлежит AppId, с этим API Key
4001018	Base64 decode error	Authorization в request header не является валидным base64	Используйте полученный Token напрямую без какой-либо обработки
4001019	Decryption error	Authorization в request header не был создан EasyAR	Используйте полученный Token напрямую без какой-либо обработки
4001022	API Key's resource is empty	У API Key нет связанных cloud services	Проверьте, связан ли API Key с cloud service и не истек ли связанный cloud service
4001024	Token is expired	Token истек	Сгенерируйте заново
4001025	Token generate fail	Генерация Token не удалась	Свяжитесь с технической поддержкой: support@easyar.com

Table of Contents

Получение и использование API Key

Создание API Key

Совет

Предупреждение

Получение Token

Получение Token из Developer Center

Примечание

Генерация Token с API Key и API Secret

Предупреждение

Request parameters

Метод signature

Пример signature

Совет

Получение Token

Использование Token

Описание error codes