Mendapatkan dan menggunakan api key

Di Pusat Pengembangan EasyAR, membuat API Key tidak dibatasi jumlahnya. Disarankan untuk mengalokasikan API Key terpisah untuk aplikasi yang berbeda, agar pengelolaan izin dapat dilakukan lebih terperinci.

Membuat api key

Masuk ke Pusat Pengembangan EasyAR Pusat Pengembangan. Jika ini pertama kalinya Anda menggunakan API Key, buat terlebih dahulu dengan langkah-langkah berikut:

Di bawah "Otorisasi", klik "Kunci API Layanan Cloud"
Di halaman "API KEY", klik tombol "Buat API KEY"

APIKey

Isi "Nama Aplikasi"
Centang layanan cloud yang diperlukan sesuai kebutuhan aplikasi Anda. Tidak disarankan memberikan semua otorisasi.
Klik "Konfirmasi"

Kiat

Saat menggunakan SpatialMap, centang SpatialMap.

Saat menggunakan Pengenalan Cloud, centang Pengenalan Cloud.

Saat menggunakan Mega Landmark, centang Mega Landmark. Sebelum menggunakan fitur ini, perlu mengajukan permohonan ke bagian bisnis.

Saat menggunakan Pusat Operasi AR, centang Pusat Operasi AR. Sebelum menggunakan fitur ini, perlu mengajukan permohonan ke bagian bisnis.

Saat menggunakan Pelokasian Cloud Mega Block, centang Mega Block.

APIKey

Saat ini, API Key dan API Secret akan dibuat di halaman, seperti yang ditunjukkan di bawah. Harap jangan bocorkan.

APIKey

Peringatan

Jangan gunakan API Key dan API Secret langsung di aplikasi klien (seperti Web, aplikasi mini WeChat, dll.).

Mendapatkan token

Ada dua cara untuk mendapatkan Token: 1. Langsung dari Pusat Pengembangan; 2. Menulis kode untuk mendapatkannya. Jika Anda memiliki kebutuhan kontrol izin akses sumber daya, disarankan menggunakan cara ke-2. Berikut ini akan menjelaskan kedua cara tersebut. Anda dapat memilih sesuai kebutuhan Anda.

Mendapatkan token dari pusat pengembangan

Pilih API Key yang ingin Anda gunakan, klik "Kelola" di sebelah kanan

APIKeyToken

Pilih masa berlaku Token
Klik "Hasilkan Token"
Klik "Salin"

APIKeyToken

Catatan

Keamanan adalah alasan utama untuk menetapkan masa berlaku Token. Jika masa berlaku Token terlalu lama, begitu bocor atau dicuri, penyerang dapat menggunakannya dalam jangka panjang, menyebabkan kebocoran data atau operasi yang tidak sah. Masa berlaku membatasi jendela efektif Token, sehingga meskipun bocor, bahayanya hanya terbatas dalam waktu singkat.

Menggunakan api key dan api secret untuk menghasilkan token

Proses pembuatan Token memerlukan penandatanganan parameter inti untuk memastikan keamanan transmisi. Selanjutnya, data yang ditandatangani ini dikirim ke layanan STS (Security Token Service) untuk autentikasi. Setelah verifikasi berhasil oleh layanan STS, Token akses sementara akan diterbitkan. Token ini hanya berlaku dalam jendela waktu yang ditentukan. Setelah waktu habis, proses autentikasi perlu dimulai ulang.

Peringatan

Jangan hasilkan Token dalam kode klien, tetapi hasilkan Token di sisi server lalu kirimkan ke klien untuk digunakan.

Parameter permintaan

Nama bidang	Tipe	Wajib diisi	Deskripsi
apiKey	string	Ya	API Key
expires	int	Ya	Waktu berlaku token yang dihasilkan, dalam satuan detik
acl	string	Ya	Daftar kontrol akses (Access Control List), mengontrol izin sumber daya yang dapat diakses oleh token
timestamp	long	Ya	Stempel waktu, dalam satuan milidetik
signature	string	Ya	Tanda tangan

acl: Terdiri dari satu atau lebih AC (kontrol akses). Setiap AC mencakup empat bagian: service, effect, resource, permission.

service: Jenis layanan, saat ini mendukung ecs:crs (pengenalan awan), ecs:spatialmap (peta spasial renggang), ecs:cls (pelokasian awan Mega Block), ecs:vps1 (landmark)
resource: ID aplikasi layanan spesifik, misalnya CRS AppId dari pustaka pengenalan awan
effect: Menentukan apakah akses yang cocok dengan item konfigurasi resource ini dapat dieksekusi, nilainya Allow atau Deny
permission: Izin, nilainya READ atau WRITE

Contoh strukturnya:

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

Metode tanda tangan

Urutkan semua parameter permintaan berdasarkan nama kunci
Untuk setiap parameter, gabungkan nama kunci dan nilainya menjadi sebuah string
Gabungkan semua string yang diperoleh, lalu tambahkan API Secret di bagian akhir
Hitung sha256 heksadesimal dari hash string tersebut sebagai tanda tangan

Contoh tanda tangan

<?php
// Kunci api dan rahasia api anda
$apiKey = '6a47f7f8ff6......68744b4bcf';
$apiSecret = '87745d866345256b......fbae27c502a';
// Id aplikasi layanan anda
$appId = 'f7ff497727ab2d55ea01d9984ef8068c';
// Waktu berlaku, dalam detik
$expires = 3600;

// Membangun parameter yang akan ditandatangani
$data = [
    'apiKey' => $apiKey,
    'expires' => $expires,
    'acl' => '[{"service":"ecs:crs","resource":["'. $appId .'"],"effect":"Allow","permission":["READ"]}]',
    'timestamp' => time() * 1000,
];

// Pengurutan
ksort($data);

// Penggabungan string
$builder = [];
foreach ($data as $key => $value) {
    array_push($builder, $key . $value);
}

// Menambahkan apiSecret
array_push($builder, $apiSecret);

// Menghasilkan tanda tangan digital
$signature = hash('sha256', implode('', $builder));
echo $signature;

const crypto = require('crypto');

// Kunci API dan rahasia API anda
const apiKey = '6a47f7f8ff6......68744b4bcf'
const apiSecret = '87745d866345256b......fbae27c502a'
// ID aplikasi layanan anda
const appId = 'f7ff497727ab2d55ea01d9984ef8068c';
// Masa berlaku, dalam detik
const expires = 3600

// Membangun parameter yang akan ditandatangani
const data = {
    apiKey: apiKey,
    expires: expires,
    acl: `[{"service":"ecs:crs","resource":["${appId}"],"effect":"Allow","permission":["READ"]}]`,
    timestamp: Date.now(),
}

// Mengurutkan dan menggabungkan string
let builder = [];
Object.keys(data).sort().forEach(key => builder.push(`${key}${data[key]}`));

// Menggabungkan rahasia API
builder.push(apiSecret);

// Menghasilkan tanda tangan
const signature = crypto.createHash('sha256').update(builder.join('')).digest('hex');
console.info(signature);

import time
import hashlib

# Api key dan api secret anda
apiKey = '6a47f7f8ff6......68744b4bcf'
apiSecret = '87745d866345256b......fbae27c502a'
# App id layanan anda
appId = 'f7ff497727ab2d55ea01d9984ef8068c'
# Waktu berlaku, dalam satuan detik
expires = 3600

# Membangun parameter yang akan ditandatangani
data = dict(sorted({
    'apiKey': apiKey,
    'expires': expires,
    'acl': '[{"service":"ecs:crs","resource":["'+ appId +'"],"effect":"Allow","permission":["READ"]}]',
    'timestamp': int(time.time() * 1000),
}.items()))

# Menggabungkan string
builder = [f'{key}{value}' for key, value in data.items()]

# Menambahkan api secret
builder.append(apiSecret)

# Menghasilkan tanda tangan
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 dan API Secret Anda
        String apiKey = "6a47f7f8ff6......68744b4bcf";
        String apiSecret = "87745d866345256b......fbae27c502a";
        // ID Aplikasi layanan
        String appId = "f7ff497727ab2d55ea01d9984ef8068c";
        // Waktu kedaluwarsa, dalam detik
        int expires = 3600;

        // Bangun parameter yang akan ditandatangani
        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\"]}]");

        // Gabungkan string
        StringBuilder builder = new StringBuilder();
        data.forEach((key, value) -> builder.append(String.format("%s%s", key, value)));

        // Tambahkan API Secret
        builder.append(apiSecret);

        // Hasilkan tanda tangan
        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 dan API Secret Anda
            string apiKey = "6a47f7f8ff6......68744b4bcf";
            string apiSecret = "87745d866345256b......fbae27c502a";
            // App ID layanan
            string appId = "f7ff497727ab2d55ea01d9984ef8068c";
            // Waktu berlaku, dalam detik
            int expires = 3600;

            // Membangun parameter yang akan ditandatangani
            SortedDictionary<string, object> data = new() {
                { "apiKey", apiKey },
                { "expires", expires },
                { "timestamp", DateTimeOffset.Now.ToUnixTimeMilliseconds() },
                { "acl", "[{\"service\":\"ecs:crs\",\"resource\":[\"" + appId + "\"],\"effect\":\"Allow\",\"permission\":[\"READ\"]}]" }
            };

            // Menggabungkan string
            StringBuilder builder = new StringBuilder();
            data.ToList().ForEach(pair => builder.Append($"{pair.Key}{pair.Value}"));

            // Menggabungkan API Secret
            builder.Append(apiSecret);

            // Menghasilkan tanda tangan
            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 dan API Secret Anda
    apiKey := "6a47f7f8ff6......68744b4bcf"
    apiSecret := "87745d866345256b......fbae27c502a"
    // App ID layanan Anda
    appId := "f7ff497727ab2d55ea01d9984ef8068c"
    // Waktu berlaku, dalam detik
    expires := 3600

    // Membangun parameter yang akan ditandatangani
    data := map[string]any{
        "apiKey":    apiKey,
        "expires":   expires,
        "acl":       `[{"service":"ecs:crs","resource":["` + appId + `"],"effect":"Allow","permission":["READ"]}]`,
        "timestamp": time.Now().Unix() * 1000,
    }

    // Mengurutkan
    keys := []string{}
    for key := range data {
        keys = append(keys, key)
    }
    sort.Strings(keys)

    // Menggabungkan string
    builder := strings.Builder{}
    for _, key := range keys {
        builder.WriteString(fmt.Sprintf("%s%v", key, data[key]))
    }

    // Menggabungkan API Secret
    builder.WriteString(apiSecret)

    // Menghasilkan tanda tangan
    signature := fmt.Sprintf("%x", sha256.Sum256([]byte(builder.String())))
    fmt.Println(signature)
}

Kiat

Saat menambahkan tanda tangan, ACL perlu dikonversi menjadi string JSON.

Mendapatkan token

Tambahkan tanda tangan yang telah dibuat ke dalam daftar parameter, kirim permintaan ke antarmuka /token/v2 untuk mendapatkan Token.

Alamat permintaan: https://uac.easyar.com/token/v2 atau https://uac-na1.easyar.com/token/v2 (Amerika Utara 1)
Metode permintaan: POST
Header permintaan: Content-Type: application/json
Parameter permintaan: {"apiKey":"6a47f7f8ff6......68744b4bcf","expires":3600,"acl":"[{\"service\":\"ecs:crs\",\"resource\":[\"f7ff497727ab2d55ea01d9984ef8068c\"],\"effect\":\"Allow\",\"permission\":[\"READ\"]}]","timestamp":1765954279002,"signature":"32f18a37fc3c18......55c4943af9"}

Contoh:

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"}'

Jika statusCode dalam hasil respons adalah 0, itu berarti sukses.

Format respons normal:

{
  "statusCode": 0,
  "timestamp": 1765954874399,
  "msg": "Success",
  "result": {
    "apiKey": "6a47f7f8ff6......68744b4bcf",
    "expires": 3600,
    "token": "nuPDCj......xstQX",
    "expiration": "2025-12-17T08:01:14.399+0000"
  }
}

token: Token untuk otentikasi permintaan bisnis.
expiration: Waktu kedaluwarsa token, setelah kedaluwarsa perlu meminta token baru.

Format respons kesalahan:

{
  "statusCode": 4001017,
  "timestamp": 1765954666624,
  "msg": "AppId is not authorized by this API Key",
  "result": null
}

Menggunakan token

Dalam permintaan https bisnis, tambahkan Token ke header permintaan dengan format: {"Authorization": "nuPDCj......xstQX"}.

Saat mengirim permintaan API bisnis, perlu menambahkan parameter appId (sumber untuk mendapatkan dapat dilihat di Pusat Pengembangan terkait layanan).

Penjelasan kode kesalahan

Selama proses pembuatan Token dan penggunaan Token, berbagai kesalahan atau situasi tidak normal dapat terjadi. Untuk membantu pengembang dengan cepat menemukan masalah dan mengambil tindakan perbaikan yang efektif, berikut adalah penjelasan rinci tentang kode kesalahan umum dan artinya:

Kode Kesalahan	Informasi Kesalahan	Penjelasan Kesalahan	Solusi
4001011	API Key invalid	API Key tidak valid	Periksa apakah API Key ini ada di bawah "Kunci API Layanan Cloud"
4001012	Timestamp invalid	Stempel waktu tidak valid	Unit stempel waktu adalah milidetik, dan kesalahan dengan waktu standar tidak boleh melebihi 5 menit
4001015	Signature invalid	Tanda tangan tidak valid	Periksa apakah algoritma tanda tangan benar, dan periksa apakah API Secret cocok dengan API KEY
4001017	AppId is not authorized by this API Key	API Key tidak diizinkan untuk AppId ini	Periksa apakah layanan tempat AppId berada terkait dengan API Key ini
4001018	Base64 decode error	Authorization yang diatur di header permintaan bukan format base64 yang valid	Token yang diperoleh, jangan diproses apa pun, gunakan langsung
4001019	Decryption error	Authorization yang diatur di header permintaan bukan hasil buatan EasyAR	Token yang diperoleh, jangan diproses apa pun, gunakan langsung
4001022	API Key's resource is empty	API Key tidak memiliki layanan cloud yang terkait	Periksa apakah API Key terkait dengan layanan cloud dan apakah layanan cloud yang terkait sudah kedaluwarsa
4001024	Token is expired	Token telah kedaluwarsa	Hasilkan ulang
4001025	Token generate fail	Gagal menghasilkan Token	Hubungi dukungan teknis: support@easyar.com

Table of Contents

Mendapatkan dan menggunakan api key

Membuat api key

Kiat

Peringatan

Mendapatkan token

Mendapatkan token dari pusat pengembangan

Catatan

Menggunakan api key dan api secret untuk menghasilkan token

Peringatan

Parameter permintaan

Metode tanda tangan

Contoh tanda tangan

Kiat

Mendapatkan token

Menggunakan token

Penjelasan kode kesalahan