疎空間マップリストとプレビュー

EasyAR Spatial Map には通常、大量の空間マップデータが保存されています。本章では、Spatial Map の詳細取得とページングリスト取得の方法を説明します。

EasyAR Web で疎マップを管理する

ビジュアルインターフェイスでは、システムはデフォルトで疎マップをページングリスト形式で表示し、最終更新時刻の逆順（最新の変更が先頭）で並べます。

疎マップリスト

操作パス: EasyAR Web [Developer Center] にログイン -> [SpatialMap] -> gallery を選択 -> [Manage] をクリック。

この画面では、次の操作を実行できます。

リスト閲覧: ページング表示された Spatial Map 空間マップコレクションを確認します。
詳細入口: 画像内のボタン 1 の [Manage] をクリックすると、マップ詳細ページに入ります。
正確な検索: 入力ボックス 2 では、次の検索方法をサポートします。
- 名前で検索: システムがアプリ内 ID などの規則に従って画像に名前を付けている場合、名前で素早く特定できます。
- MapId で検索
- Label, GPS で検索: Search API のみサポートします

Spatial Map 詳細情報

詳細ページに入ると、Spatial Map の完全な属性を確認できます。内容は次のとおりです。

Preview: プレビュー画像。
名称: Spatial Map 名称。
MapId: システムが生成した一意の ID。
status 状態: 有効または無効。
Label ラベル: 検索しやすいカスタムラベルで、Search API クエリをサポートします。
GPS: 空間の gps、カスタム座標系で、Search API クエリをサポートします。
Custom Meta: この Spatial Map に関連付けられたメタデータ（モデル URL など）。

detail

API を使用して Spatial Map マップリストを表示する

独自 backend への統合が必要な開発者には、REST API による管理を推奨します。

参照ドキュメント: Spatial Map マップリスト API

準備チェックリスト

リクエストを開始する前に、次のリソースを取得していることを確認してください。詳細は API 呼び出し準備チェックリストを参照してください。

SpatialMap AppId
API Key / Secret または Token
Cloud URL
- 中国および東南アジアのユーザーは選択: https://armap-api.easyar.com
- その他のユーザーは選択: https://armap-api-na1.easyar.com

プレースホルダーを実際のパラメーターに置き換え、curl スクリプトを実行してください

Your-URL → 実際の Cloud URL
Your-Token → 実際の API Key Authorization Token
Your-SpatialMap-AppId → 実際の SpatialMap appId

curl -X GET "https://armap-api-<cn1|na1>.easyar.com/maps?appId=<Your-SpatialMap-AppId>" \
  -H "Content-Type: application/json" \
  -H "Authorization: <Your-Token>"

Java サンプルコードをダウンロードします

Java Samples Download

Maven 方式でプロジェクトをインポートします

Step 1. サンプルコード ListMaps.java を開きます

Step 2. グローバル変数を変更し、準備チェックリストの認証パラメータに置き換えます

SpatialMap AppId
API Key / API Secret
Cloud URL

ListMaps.java

import okhttp3.OkHttpClient;
import okhttp3.Response;
import org.json.JSONObject;
import java.io.IOException;
import java.util.Set;

public class ListMaps {

    private static final String CLOUD_URL       = "https://armap-api.easyar.com";
    private static final String APPID           = "--here is your SpatialMap AppId--";
    private static final String API_KEY         = "--here is your API Key--";
    private static final String API_SECRET      = "--here is your API Secret--";

    public String  toParam(JSONObject jso) {
        Set<String> keys = jso.keySet();
        StringBuffer sb   = new StringBuffer();
        for (String key : keys){
            sb.append(key);
            sb.append("=");
            sb.append(jso.getString(key));
            sb.append("&");
        }
        return sb.substring(0,sb.length()-1);
    }

    public String list(Auth auth) throws IOException {
        OkHttpClient client = new OkHttpClient.Builder().build();
        JSONObject params = new JSONObject();
        Auth.signParam(params, auth.getAppId(), auth.getApiKey(), auth.getApiSecret());
        okhttp3.Request request = new okhttp3.Request.Builder()
                .url(auth.getCloudURL() + "/maps?"+ toParam(params))
                .get()
                .build();
        Response response = client.newCall(request).execute();
        return response.body().string();
    }
    public static void main(String[] args) throws IOException{
        Auth accessInfo  =  new Auth(APPID, API_KEY, API_SECRET, CLOUD_URL);
        System.out.println(new ListMaps().list(accessInfo));
    }

}

Step 3. Main を実行します

Step 1. サンプルコードを listmap.js にコピーし、その中の Token、appId、Cloud URL を変更します

Step 2. 実行

npm install axios
node listmap.js

pagination strategy を変更する必要がある場合は、pagination parameters を渡します

pageSize: ページサイズ
pageNum: ページ番号

const axios = require('axios');

class MapService {
    constructor(baseURL, token, appId) {
        this.baseURL = baseURL;
        this.token = token;
        this.appId = appId;
        this.client = axios.create({
            baseURL: baseURL,
            headers: {
                'Authorization': token,  
                'Content-Type': 'application/json'
            }
        });
    }

    async listMaps(params = {}) {
        try {
            const queryParams = {
                ...params,
                appId: this.appId 
            };

            const response = await this.client.get('/maps', { params: queryParams });
            
            console.log('=== API Response ===');
            console.log('Status Code:', response.status);
            console.log('Request URL:', response.config.url);
            console.log('Request Headers:', JSON.stringify(response.config.headers, null, 2));
            console.log('Request Params:', JSON.stringify(queryParams, null, 2));
            console.log('Response Data:', JSON.stringify(response.data, null, 2));
            console.log('Timestamp:', new Date().toISOString());
            
            return response.data;
        } catch (error) {
            console.error('=== API Error ===');
            if (error.response) {
                console.log('Status Code:', error.response.status);
                console.log('Error Data:', error.response.data);
            } else {
                console.log('Error Message:', error.message);
            }
            throw error;
        }
    }
}

async function main() {
    const config = {
        baseURL: 'https://armap-api-<cn1|na1>.easyar.com',
        token: 'your_token_here', 
        appId: 'your_app_id_here' 
    };

    const mapService = new MapService(config.baseURL, config.token, config.appId);
    
    const queryParams = {
        pageNum: 1,
        pageSize: 10
    };

    try {
        const result = await mapService.listMaps(queryParams);
        console.log('\n=== Success ===');
    } catch (error) {
        console.log('\n=== Failed ===');
    }
}

if (require.main === module) {
    main();
}

module.exports = MapService;

Step 1. サンプルコードを listmap.php にコピーし、その中の Token、appId、Cloud URL を変更します

Step 2. 実行

php listmap.php

ページング戦略を変更する必要がある場合は、ページングパラメータを渡します

'pageSize': ページサイズ
'pageNum': ページ番号

<?php
class MapService {
    private $baseURL;
    private $token;
    private $appId;
    
    public function __construct($baseURL, $token, $appId) {
        $this->baseURL = $baseURL;
        $this->token = $token;
        $this->appId = $appId;
    }
    
    public function listMaps($params = []) {
        $queryParams = array_merge([
            'appId' => $this->appId
        ], $params);
        
        $queryString = http_build_query($queryParams);
        $url = $this->baseURL . '/maps?' . $queryString;
        
        $ch = curl_init();
        
        curl_setopt_array($ch, [
            CURLOPT_URL => $url,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER => [
                'Authorization: ' . $this->token, 
                'Content-Type: application/json'
            ],
            CURLOPT_SSL_VERIFYPEER => false,
            CURLOPT_TIMEOUT => 30
        ]);
        
        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        $error = curl_error($ch);
        
        echo "=== API Request ===" . PHP_EOL;
        echo "URL: " . $url . PHP_EOL;
        echo "Headers: Authorization: " . $this->token . PHP_EOL;
        echo "Query Params: " . json_encode($queryParams, JSON_PRETTY_PRINT) . PHP_EOL;
        
        curl_close($ch);
        
        echo "=== API Response ===" . PHP_EOL;
        echo "Status Code: " . $httpCode . PHP_EOL;
        echo "Timestamp: " . date('c') . PHP_EOL;
        
        if ($error) {
            echo "cURL Error: " . $error . PHP_EOL;
            return null;
        }
        
        $responseData = json_decode($response, true);
        echo "Response Data: " . json_encode($responseData, JSON_PRETTY_PRINT) . PHP_EOL;
        
        return $responseData;
    }
}

// Configure your API Key Token and Your Spatial Map AppId
$config = [
    'baseURL' => 'https://armap-api-<cn1|na1>.easyar.com',
    'token' => 'your_token_here',   
    'appId' => 'your_app_id_here'   
];

$mapService = new MapService($config['baseURL'], $config['token'], $config['appId']);

$queryParams = [
    'pageNum' => 1,
    'pageSize' => 5
];

$result = $mapService->listMaps($queryParams);

if ($result) {
    echo PHP_EOL . "=== Success ===" . PHP_EOL;
} else {
    echo PHP_EOL . "=== Failed ===" . PHP_EOL;
}
?>

関連するコードファイル list_map.py を作成し、グローバル変数を変更してから実行します

pip install requests
python list_map.py

import time
import hashlib
import requests

# --- Global Configuration ---
API_KEY = "YOUR_API_KEY"
API_SECRET = "YOUR_API_SECRET"
APP_ID = "YOUR_APP_ID"
HOST = "https://armap-api-<cn1|na1>.easyar.com"

def main():
    timestamp = str(int(time.time() * 1000))
    
    # 1. Prepare parameters
    params = {
        'apiKey': API_KEY,
        'appId': APP_ID,
        'timestamp': timestamp,
        'pageNum': '1',
        'pageSize': '10'
    }

    # 2. Signature Calculation
    sorted_keys = sorted(params.keys())
    sign_str = "".join([f"{k}{params[k]}" for k in sorted_keys]) + API_SECRET
    signature = hashlib.sha256(sign_str.encode('utf-8')).hexdigest()

    # 3. Build Request
    url = f"{HOST}/maps"
    params['signature'] = signature

    print(f"Fetching Spatial Maps from {url}...")
    response = requests.get(url, params=params)
    print(f"Response: {response.text}")

if __name__ == "__main__":
    main()

関連するコードファイル main.go を新規作成し、global variables を変更してから、次を実行します

go run main.go

main.go:

package main

import (
  "crypto/sha256"
  "fmt"
  "io"
  "net/http"
  "sort"
  "strconv"
  "time"
)

var (
  ApiKey    = "YOUR_API_KEY"
  ApiSecret = "YOUR_API_SECRET"
  AppId     = "YOUR_APP_ID"
  Host      = "https://armap-api-<cn1|na1>.easyar.com"
)

func main() {
  ts := strconv.FormatInt(time.Now().UnixNano()/1e6, 10)
  params := map[string]string{
    "apiKey":    ApiKey,
    "appId":     AppId,
    "timestamp": ts,
    "pageNum":   "1",
    "pageSize":  "10",
  }

  // 1. Sort keys
  keys := make([]string, 0, len(params))
  for k := range params { keys = append(keys, k) }
  sort.Strings(keys)

  // 2. Build string and sign
  builder := ""
  for _, k := range keys { builder += k + params[k] }
  builder += ApiSecret

  signature := fmt.Sprintf("%x", sha256.Sum256([]byte(builder)))

  // 3. Request
  url := fmt.Sprintf("%s/maps?apiKey=%s&appId=%s&timestamp=%s&pageNum=%s&pageSize=%s&signature=%s", 
    Host, ApiKey, AppId, ts, params["pageNum"], params["pageSize"], signature)
  
  resp, _ := http.Get(url)
  defer resp.Body.Close()
  body, _ := io.ReadAll(resp.Body)
  fmt.Printf("Response: %s\n", string(body))
}

Cargo.toml に reqwest、tokio、sha2、hex の依存関係を追加します。

cargo run を実行します。

use sha2::{Sha256, Digest};
use std::collections::BTreeMap;
use std::time::{SystemTime, UNIX_EPOCH};

const API_KEY: &str = "YOUR_API_KEY";
const API_SECRET: &str = "YOUR_API_SECRET";
const APP_ID: &str = "YOUR_APP_ID";
const HOST: &str = "https://armap-api-<cn1|na1>.easyar.com";

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let ts = SystemTime::now().duration_since(UNIX_EPOCH)?.as_millis().to_string();

    // 1. Signature components in BTreeMap (sorted by key)
    let mut params = BTreeMap::new();
    params.insert("apiKey", API_KEY);
    params.insert("appId", APP_ID);
    params.insert("timestamp", &ts);
    params.insert("pageNum", "1");
    params.insert("pageSize", "10");

    // 2. Concatenate and add Secret
    let mut sign_str = String::new();
    for (k, v) in &params {
        sign_str.push_str(k);
        sign_str.push_str(v);
    }
    sign_str.push_str(API_SECRET);
    
    let mut hasher = Sha256::new();
    hasher.update(sign_str.as_bytes());
    let signature = hex::encode(hasher.finalize());

    // 3. Request
    let url = format!("{}/maps?apiKey={}&appId={}&timestamp={}&pageNum=1&pageSize=10&signature={}", 
                      HOST, API_KEY, APP_ID, ts, signature);
    
    let res = reqwest::get(url).await?;
    println!("Response: {}", res.text().await?);
    Ok(())
}

.NET コンソールプロジェクトを作成します。

dotnet new console
dotnet run

using System;
using System.Collections.Generic;
using System.Linq;
using System.Security.Cryptography;
using System.Text;
using System.Net.Http;

class Program {
    static string API_KEY = "YOUR_API_KEY";
    static string API_SECRET = "YOUR_API_SECRET";
    static string APP_ID = "YOUR_APP_ID";
    static string HOST = "https://armap-api-<cn1|na1>.easyar.com";

    static async System.Threading.Tasks.Task Main() {
        string timestamp = DateTimeOffset.Now.ToUnixTimeMilliseconds().ToString();

        // 1. Build sorted parameters
        var dict = new SortedDictionary<string, string> {
            { "apiKey", API_KEY },
            { "appId", APP_ID },
            { "timestamp", timestamp },
            { "pageNum", "1" },
            { "pageSize", "10" }
        };

        // 2. Concatenate and append Secret
        StringBuilder sb = new StringBuilder();
        foreach (var kv in dict) sb.Append(kv.Key).Append(kv.Value);
        sb.Append(API_SECRET);
        
        string signature = Sha256(sb.ToString());

        // 3. Execute GET request
        using var client = new HttpClient();
        string query = string.Join("&", dict.Select(x => $"{x.Key}={x.Value}")) + $"&signature={signature}";
        string url = $"{HOST}/maps?{query}";
        
        var response = await client.GetAsync(url);
        Console.WriteLine($"Result: {await response.Content.ReadAsStringAsync()}");
    }

    static string Sha256(string str) {
        byte[] bytes = SHA256.HashData(Encoding.UTF8.GetBytes(str));
        return BitConverter.ToString(bytes).Replace("-", "").ToLower();
    }
}

実行環境
- Unity 2020 LTS 以降
- Scripting Backend: Mono または IL2CPP のどちらでも可
- API Compatibility Level: .NET Standard 2.1（推奨）

Step 1: 画像ファイルを準備する

Unity プロジェクト内にディレクトリを作成します。

Assets/
└── Scripts/
     └── ListMap.cs

using System.Collections;
using UnityEngine;
using UnityEngine.Networking;

public class ListMap : MonoBehaviour
{
    [Header("Config")]
    public string apiBaseUrl = "https://armap-api-<cn1|na1>.easyar.com";
    public string authorizationToken = "YOUR API KEY AUTH TOKEN"; 
    public string spatialMapAppId = "SpatialMap-AppId"; 
    public int pageSize = 5; 
    public int pageNum  = 1; 
     
    private void Start()
    {
        StartCoroutine(ListMaps());
    }

    private IEnumerator ListMaps()
    {
     
        string url =
            $"{apiBaseUrl}/maps?appId={spatialMapAppId}&pageSize={pageSize}&pageNum={pageNum}";

        UnityWebRequest request = UnityWebRequest.Get(url);
        request.downloadHandler = new DownloadHandlerBuffer();

        request.SetRequestHeader("Content-Type", "application/json");
        request.SetRequestHeader("Authorization", authorizationToken);

        yield return request.SendWebRequest();

        if (request.result == UnityWebRequest.Result.Success)
        {
            Debug.Log("List maps success:");
            Debug.Log(request.downloadHandler.text);
        }
        else
        {
            Debug.LogError("List maps failed:");
            Debug.LogError(request.error);
            Debug.LogError(request.downloadHandler.text);
        }
    }
}

Assets ディレクトリ名に従って
- 次のサンプルコード ListMap.cs をコピーします
Unity Editor で:
- 空の GameObject を作成します
- ListMap という名前にします
- ListMap スクリプトをこのオブジェクトにドラッグします

Step 3: パラメータを設定する（Inspector）

Inspector パネルで次を変更します。
- Api Url
- Authorization Token
- Spatial Map App Id
- page size
- page num
実行にはこれらの項目だけを変更すればよく、準備チェックリストで用意したパラメータを入力します

Step 4: 実行する

Play をクリックします
Console で結果を確認します。
- 成功: JSON（result を含む）を返します
- 失敗: HTTP / エラー情報

次のトピック: