희소 공간 맵 목록 및 미리보기

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;

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

// 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 / 오류 정보

다음 항목: