稀疏空間地圖列表和預覽

EasyAR Spatial Map 中通常儲存著大量空間地圖數據。本章將詳細介紹 Spatial Map 空間地圖詳情獲取、分頁列表獲取的方法。

通過 EasyAR Web 管理稀疏地圖

在可視化界面中，系統默認採用分頁列表形式展示稀疏地圖，並按照最後修改時間進行逆序排列（最新改動的排在最前）。

稀疏地圖列表

操作路徑：登入 EasyAR Web [開發中心] -> [SpatialMap] -> 選擇圖庫 -> 點擊 [管理]。

在此界面中，您可以進行以下操作：

列表瀏覽：查看分頁展示的 Spatial Map 空間地圖集合。
詳情入口：點擊圖中按鈕1 [管理] 可進入地圖詳情頁。
精準檢索：在輸入框2 中，支援以下幾種檢索方式：
- 按名稱檢索：若您的系統按規則（如應用內 ID）命名圖片，可通過名稱快速定位。
- 按 MapId 檢索
- 按 Label, GPS 檢索：僅檢索 Search API支援

Spatial Map 詳情信息

點擊進入詳情頁後，您可以查看到 Spatial Map 地圖的完整屬性，包括：

Preview：預覽圖。
名稱：Spatial Map 名稱。
MapId：系統生成的唯一 ID。
status 狀態：啟用或者停用。
Label 標籤：自定義標籤方便查找，支援 Search API 接口檢索
GPS：空間所在 gps，自定義坐標系，支援 Search API 接口檢索
自定義 Meta：該 Spatial Map 地圖關聯的元數據（如模型 URL 等）

detail

使用 API 查看 Spatial Map 地圖列表

對於需要集成到自有後台的開發者，建議使用 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

步驟 1. 複製範例程式碼到 listmap.js，修改其中的 Token、appId 以及雲端 URL

步驟 2. 執行

npm install axios
node listmap.js

若需變更分頁策略，傳入分頁參數

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 回應 ===');
            console.log('狀態碼:', response.status);
            console.log('請求 URL:', response.config.url);
            console.log('請求標頭:', JSON.stringify(response.config.headers, null, 2));
            console.log('請求參數:', JSON.stringify(queryParams, null, 2));
            console.log('回應資料:', JSON.stringify(response.data, null, 2));
            console.log('時間戳記:', new Date().toISOString());
            
            return response.data;
        } catch (error) {
            console.error('=== API 錯誤 ===');
            if (error.response) {
                console.log('狀態碼:', error.response.status);
                console.log('錯誤資料:', error.response.data);
            } else {
                console.log('錯誤訊息:', 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=== 成功 ===');
    } catch (error) {
        console.log('\n=== 失敗 ===');
    }
}

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

module.exports = MapService;

步驟1. 複製示例程式碼至 listmap.php，修改其中的 Token、appId 以及 Cloud URL

步驟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;
    }
}

// 設定您的 API Key Token 與 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，修改全局變量，然後運行

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. 建立排序參數
        var dict = new SortedDictionary<string, string> {
            { "apiKey", API_KEY },
            { "appId", APP_ID },
            { "timestamp", timestamp },
            { "pageNum", "1" },
            { "pageSize", "10" }
        };

        // 2. 連接並附加 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. 執行 GET 請求
        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($"結果: {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：準備圖片文件

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

按照 Assets 目錄名
- 複製下面範例程式碼 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);
        }
    }
}

在 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 / 錯誤訊息

下一主題：