API Key の取得と使用

EasyAR Developer Center で作成できる API Key の数に制限はありません。権限をより細かく管理できるよう、アプリケーションごとに独立した API Key を割り当てることを推奨します。

API Key を作成する

EasyAR Developer Center にログインします。API Key を初めて使用する場合は、まず次の手順で API Key を作成してください。

"Authorization" の下で "Cloud Service API KEY" をクリック
"API KEY" ページで "Create API KEY" ボタンをクリック

APIKey

"Application Name" を入力
アプリケーションの要件に応じて必要な cloud service を選択します。すべてを許可することは推奨しません。
"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

警告

Web や WeChat Mini Program などの client アプリケーションで API Key と API Secret を直接使用しないでください。

Token を取得する

Token を取得する方法は 2 つあります。1. Developer Center から直接取得する。2. コードを書いて取得する。resource のアクセス権限を制御する必要がある場合は、2 番目の方法を推奨します。以下でそれぞれ説明します。

Developer Center から Token を取得する

使用する API Key を選択し、右側の "Manage" をクリックします

APIKeyToken

Token の有効期間を選択
"Generate Token" をクリック
"Copy" をクリック

APIKeyToken

注記

セキュリティは Token 有効期間を設定する主な理由です。Token の有効期間が長すぎると、漏洩または盗難時に攻撃者が長期間利用でき、データ漏洩や不正操作につながります。有効期間により Token の有効ウィンドウが制限され、漏洩しても被害は短時間に限定されます。

API Key と API Secret で Token を生成する

Token の生成では、送信の安全性を確保するために主要パラメータへの署名が必要です。その後、署名済みデータを STS (Security Token Service) に送信して認証します。STS の検証が通ると、一時 access Token が発行されます。この Token は指定時間内のみ有効で、期限切れ後は認証を再実行する必要があります。

警告

client code で Token を生成せず、server side で生成してから client に渡してください。

Request パラメータ

フィールド名	型	必須	説明
apiKey	string	はい	API Key
expires	int	はい	生成された Token の有効期間、単位は秒
acl	string	はい	Access Control List。token がアクセスできる resource 権限を制御します
timestamp	long	はい	Timestamp、単位はミリ秒
signature	string	はい	Signature

acl: 1 つまたは複数の AC (access control) で構成されます。各 AC には service、effect、resource、permission の 4 つの部分が含まれます。

service: サービスタイプ。現在 ecs:crs (Cloud Recognition)、ecs:spatialmap (Sparse Spatial Map)、ecs:cls (Mega Block Cloud Localization)、ecs:vps1 (landmark) をサポートします
resource: 具体的なサービスの app id。例: Cloud Recognition library の CRS AppId
effect: この resource 設定項目に一致するアクセスを実行できるかを指定します。値は Allow、Deny
permission: 権限値 READ、WRITE

構造例:

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

Signature 方法

request のすべてのパラメータを key name でソートします
各パラメータについて、key name と value を連結して string にします
得られたすべての string を連結し、最後に API Secret を追加します
string の sha256 hash を計算し、その 16 進値を 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 をパラメータリストに追加し、/token/v2 interface に request を送信して 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: 業務 request 認証用の Token。
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 パラメータを追加する必要があります (取得元は Developer Center の関連 service を確認してください)。

Error code の説明

Token の生成および使用中に、さまざまな error や exception が発生する可能性があります。 developer が問題を素早く特定し有効な対応を取れるよう、一般的な error code と意味を以下に示します。

Error code	Error message	Error 説明	解決方法
4001011	API Key invalid	API Key が無効です	"Cloud Service API KEY" にこの API Key が存在するか確認します
4001012	Timestamp invalid	Timestamp が無効です	timestamp の単位はミリ秒で、標準時との差は 5 分を超えないようにします
4001015	Signature invalid	Signature が無効です	signature algorithm が正しいか、API Secret と API KEY が一致するか確認します
4001017	AppId is not authorized by this API Key	API Key はこの AppId を承認していません	AppId が属する service がこの API Key に関連付けられているか確認します
4001018	Base64 decode error	request header の Authorization が有効な base64 形式ではありません	取得した Token は処理せず直接使用します
4001019	Decryption error	request header の Authorization は EasyAR が生成したものではありません	取得した Token は処理せず直接使用します
4001022	API Key's resource is empty	API Key に関連付けられた cloud service がありません	API Key が cloud service に関連付けられているか、関連 service が期限切れでないか確認します
4001024	Token is expired	Token が期限切れです	再生成します
4001025	Token generate fail	Token 生成に失敗しました	技術サポートに連絡: support@easyar.com

Table of Contents

API Key の取得と使用

API Key を作成する

ヒント

警告

Token を取得する

Developer Center から Token を取得する

注記

API Key と API Secret で Token を生成する

警告

Request パラメータ

Signature 方法

Signature サンプル

ヒント

Token を取得する

Token を使用する

Error code の説明