取得と使用 api key

EasyAR 開発センターで API Key を作成する際、数に制限はありません。異なるアプリケーションに独立した API Key を割り当てることをお勧めします。これにより、権限をより細かく制御できます。

API key の作成

EasyAR 開発センターにログインします。API Key を初めて使用する場合は、まず API Key を作成してください。手順は以下の通りです:

「承認」の下にある「クラウドサービス API KEY」をクリック
「API KEY」ページで「API KEY を作成」ボタンをクリック

APIKey

「アプリ名」を入力
アプリの要件に基づいて必要なクラウドサービスにチェックを入れます。すべてを承認することはお勧めしません。
「OK」をクリック

ヒント

SpatialMap を使用する場合、SpatialMap にチェックを入れます。

クラウド認識を使用する場合、「クラウド認識」にチェックを入れます。

Mega Landmark を使用する場合、「Mega Landmark」にチェックを入れます。この機能を使用する前には、ビジネスチームに申請する必要があります。

AR オペレーションセンターを使用する場合、「AR オペレーションセンター」にチェックを入れます。この機能を使用する前には、ビジネスチームに申請する必要があります。

Mega Block クラウド位置特定を使用する場合、「Mega Block」にチェックを入れます。

APIKey

この時点で、API Key と API Secret がページに生成されます。以下に示すように、漏洩しないように注意してください。

APIKey

警告

クライアント側（Web、WeChat ミニアプリなど）のアプリケーションで API Key と API Secret を直接使用しないでください。

Token の取得

Token を取得する方法は2つあります：1. 開発センターから直接取得する。2. コードを書いて取得する。リソースへのアクセス権限を制御する必要がある場合は、2番目の方法を使用することをお勧めします。以下では、これらの取得方法をそれぞれ説明します。ニーズに応じて選択してください。

開発センターから token を取得

使用する API Key を選択し、右側の「管理」をクリック

APIKeyToken

Token の有効期限を選択
「Token を生成」をクリック
「コピー」をクリック

APIKeyToken

注記

‌セキュリティは Token の有効期限設定の主な理由です。‌ Token の有効期限が長すぎると、漏洩または盗難に遭った場合、攻撃者が長期間使用し、データ漏洩や未承認の操作を引き起こす可能性があります。有効期限は Token の有効な時間枠を制限し、たとえ漏洩しても被害は短時間に限定されます。

API key と API secret を使用して token を生成

Token の生成プロセスでは、コアパラメータの署名操作が要求され、伝送の安全性が確保されます。その後、署名されたデータは STS（Security Token Service）サービスに送信され、認証が行われます。STS サービスによる認証が成功すると、一時的なアクセス Token が発行されます。この Token は指定された時間枠内でのみ有効で、期限切れ後は再認証プロセスを開始する必要があります。

警告

クライアント側コードで Token を生成せず、サーバー側で生成した Token をクライアントに渡して使用してください。

リクエストパラメータ

フィールド名	タイプ	必須	説明
apiKey	string	はい	API Key
expires	int	はい	生成された Token の有効時間, 単位は秒
acl	string	はい	アクセス制御リスト (Access Control List), token がアクセスできるリソースの権限を制御
timestamp	long	はい	タイムスタンプ, 単位はミリ秒
signature	string	はい	署名

acl： 1つ以上の AC（アクセス制御）で構成され、各 AC は service、effect、resource、permission の4つの部分を含む。

service：サービスタイプ。現在サポート: ecs:crs（クラウド認識）、ecs:spatialmap（疎空間マップ）、ecs:cls（Mega Block クラウド位置特定）、ecs:vps1（landmark）
resource：具体的なサービスの app id。例: クラウド認識ライブラリの CRS AppId
effect：この resource 設定項目に一致するアクセスが実行可能かどうかを指定。Allow または Deny
permission：権限。READ または WRITE

構造例:

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

署名方法

リクエストのすべてのパラメータをキー名でソート
各パラメータについて、キー名と値を連結して文字列を作成
得られたすべての文字列を連結し、最後に API Secret を追加
文字列の sha256 ハッシュを16進数で計算したものが署名

署名サンプル

<?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キーと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 の取得

上記で生成した署名をパラメータリストに追加し、/token/v2 エンドポイントにリクエストを送信して Token を取得します。

リクエスト先：https://uac.easyar.com/token/v2 または https://uac-na1.easyar.com/token/v2 （North-america-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
}

Token の使用

業務 https リクエストで、Token をリクエストヘッダーに追加します。形式：{"Authorization": "nuPDCj......xstQX"}。

業務 API リクエストを送信する際は、appId パラメータを追加する必要があります（出所については開発センターで関連サービスを参照）。

エラーコード説明

Token 生成および Token 使用プロセスでは、様々なエラーや異常が発生する可能性があります。開発者が問題を迅速に特定し、効果的な解決策を講じるのに役立つよう、一般的なエラーコードとその意味を以下に詳しく説明します:

エラーコード	エラーメッセージ	エラー説明	解決策
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 形式ではない	取得した Token は、一切処理せずそのまま使用
4001019	Decryption error	リクエストヘッダーに設定された Authorization が EasyAR 生成のものではない	取得した Token は、一切処理せずそのまま使用
4001022	API Key's resource is empty	API Key に関連付けられたクラウドサービスがない	API Key がクラウドサービスに関連付けられているか、関連付けられたクラウドサービスの有効期限が切れていないか確認
4001024	Token is expired	Token の有効期限が切れている	再生成
4001025	Token generate fail	Token 生成失敗	テクニカルサポートに連絡: support@easyar.com

Table of Contents

取得と使用 api key

API key の作成

ヒント

警告

Token の取得

開発センターから token を取得

注記

API key と API secret を使用して token を生成

警告

リクエストパラメータ

署名方法

署名サンプル

ヒント

Token の取得

Token の使用

エラーコード説明