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

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

Создать api key

Войдите в центр разработки EasyAR view/login.html. Если вы используете API Key впервые, сначала создайте его, выполнив следующие шаги:

В разделе «Авторизация» нажмите «API KEY облачных сервисов»
На странице «API KEY» нажмите кнопку «Создать API KEY»

APIKey

Заполните «Название приложения»
В зависимости от потребностей вашего приложения, отметьте необходимые облачные сервисы. Не рекомендуется предоставлять все права.
Нажмите «Подтвердить»

Совет

Для использования SpatialMap отметьте SpatialMap.

Для использования распознавания в облаке отметьте распознавание в облаке.

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

Для использования центра управления AR отметьте центр управления AR. Перед использованием этой функции необходимо обратиться в коммерческий отдел.

Для использования облачного позиционирования Mega Block отметьте Mega Block.

APIKey

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

APIKey

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

Не используйте API Key и API Secret напрямую в клиентских приложениях (например, Web, мини-программы WeChat и т.д.).

Получить токен

Есть два способа получить токен: 1. Непосредственно из центра разработки; 2. Написав код. Если вам требуется контроль прав доступа к ресурсам, рекомендуется использовать второй способ. Ниже описаны оба способа, вы можете выбрать подходящий в зависимости от ваших потребностей.

Получить токен из центра разработки

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

APIKeyToken

Выберите срок действия токена
Нажмите «Сгенерировать токен»
Нажмите «Копировать»

APIKeyToken

Примечание

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

Сгенерировать токен с помощью API Key и API Secret

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

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

Не генерируйте токен в клиентском коде. Генерируйте токен на сервере и передавайте его клиенту для использования.

Параметры запроса

Имя поля	Тип	Обязательно	Описание
apiKey	string	Да	API Key
expires	int	Да	Срок действия токена, в секундах
acl	string	Да	Список контроля доступа (Access Control List), определяет права доступа токена к ресурсам
timestamp	long	Да	Отметка времени, в миллисекундах
signature	string	Да	Подпись

acl: Состоит из одного или нескольких элементов AC (контроль доступа). Каждый AC содержит четыре части: service, effect, resource, permission.

service: Тип сервиса. Поддерживаемые значения: ecs:crs (облачное распознавание), ecs:spatialmap (разреженная пространственная карта), ecs:cls (Mega Block облачная локализация), ecs:vps1 (landmark-vps).
resource: App id конкретного сервиса, например CRS AppId библиотеки облачного распознавания.
effect: Определяет, разрешено ли выполнение доступа, соответствующего данной конфигурации resource. Значения: Allow, Deny.
permission: Права доступа. Значения: READ, WRITE.

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

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

Метод подписи

Отсортируйте все параметры запроса по имени ключа
Для каждого параметра объедините имя ключа и значение в строку
Объедините все полученные строки и добавьте в конец API Secret
Вычислите шестнадцатеричное значение хеша sha256 строки — это и будет подпись

Пример подписи

<?php
// Ваш API Key и API Secret
$apiKey = '6a47f7f8ff6......68744b4bcf';
$apiSecret = '87745d866345256b......fbae27c502a';
// ID вашего сервисного приложения (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'
// ID вашего сервисного приложения (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-ключ и секрет API
            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
            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)
}

Совет

При добавлении подписи преобразуйте ACL в строку JSON.

Получить токен

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

Адрес запроса: https://uac.easyar.com/token/v2 или https://uac-na1.easyar.com/token/v2 (регион Северная Америка 1)
Метод запроса: POST
Заголовки запроса: Content-Type: application/json
Параметры запроса: {"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: Токен для аутентификации бизнес-запросов.
expiration: Время истечения срока действия токена. По истечении срока действия необходимо запросить новый токен.

Формат ответа с ошибкой:

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

Использовать токен

В HTTPS-запросах вашего приложения добавьте токен в заголовок запроса в формате: {"Authorization": "nuPDCj......xstQX"}.

При отправке запросов к API сервиса добавьте параметр appId (источник получения см. в центре разработки в разделе соответствующего сервиса).

Описание кодов ошибок

В процессе генерации и использования токена могут возникать различные ошибки или исключительные ситуации. Чтобы помочь разработчикам быстро определить проблему и принять эффективные меры, ниже подробно описаны распространенные коды ошибок и их значения:

Код ошибки	Сообщение об ошибке	Описание ошибки	Решение
4001011	API Key invalid	API Key недействителен	Проверьте наличие этого API Key в разделе «API KEY облачных сервисов»
4001012	Timestamp invalid	Неверная временная метка	Временная метка указывается в миллисекундах, и ее расхождение со стандартным временем не должно превышать 5 минут
4001015	Signature invalid	Неверная подпись	Проверьте правильность алгоритма подписи, а также соответствие API Secret данному API KEY
4001017	AppId is not authorized by this API Key	Этот API Key не авторизован для данного AppId	Проверьте, связана ли служба, к которой принадлежит AppId, с этим API Key
4001018	Base64 decode error	Установленный в заголовке запроса Authorization не является допустимой строкой base64	Полученный токен используйте как есть, без обработки
4001019	Decryption error	Установленный в заголовке запроса Authorization не был сгенерирован EasyAR	Полученный токен используйте как есть, без обработки
4001022	API Key's resource is empty	API Key не имеет связанных облачных сервисов	Проверьте, связан ли API Key с облачными сервисами, и не истек ли срок действия связанных сервисов
4001024	Token is expired	Срок действия токена истек	Сгенерируйте новый токен
4001025	Token generate fail	Ошибка генерации токена	Свяжитесь со службой поддержки: support@easyar.com

Table of Contents

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

Создать api key

Совет

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

Получить токен

Получить токен из центра разработки

Примечание

Сгенерировать токен с помощью API Key и API Secret

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

Параметры запроса

Метод подписи

Пример подписи

Совет

Получить токен

Использовать токен

Описание кодов ошибок