Membuat token otentikasi JWT untuk digunakan dengan API terbuka

13 mnt

Format permintaan API terbuka

API terbuka ZEPETO dipanggil melalui HTTP.

Jika ada body dalam permintaan, parameter harus dikirim dalam format JSON. Contoh jenis konten yang valid ditunjukkan di bawah ini, dan mungkin ada sedikit perbedaan tergantung pada pustaka bahasa pemrograman masing-masing.

Content-Type: application/json; charset=utf-8

Dapatkan Kunci Akses, Kunci Rahasia dari ZEPETO Studio

Sebelum membuat token otentikasi JWT, Anda perlu mendapatkan kunci akses dan kunci rahasia dari konsol ZEPETO Studio.

📘 Silakan merujuk ke panduan berikut. Mengelola API Terbuka

Membuat token otentikasi JWT

API terbuka ZEPETO menghasilkan token format JWT(https://jwt.io) berdasarkan kunci akses dan kunci rahasia yang dikeluarkan untuk setiap permintaan dan mengirimkannya dalam header Otorisasi.

HS256 disarankan sebagai metode tanda tangan, dan rahasia yang digunakan untuk penandatanganan adalah kunci rahasia yang dikeluarkan.

Payload token JWT memiliki format berikut:

{
    "access_key": "kunci akses yang diterbitkan (diperlukan)",
    "nonce": "Nilai UUID yang diacak (diperlukan)",
    "uri_hash": "Nilai yang di-hash dari URI, termasuk parameter kueri, kecuali jalur dasar (diperlukan)",
    "body_hash": "nilai yang di-hash dari body permintaan"
}

uri_hash adalah nilai yang di-hash dari uri termasuk parameter kueri kecuali jalur dasar.
body_hash adalah nilai yang dikonversi menjadi string json dan di-hash untuk dimasukkan ke dalam payload hanya ketika body permintaan ada; itu diabaikan jika tidak ada body permintaan.
- Dalam hal ini, tidak boleh ada spasi antara kunci dan nilai string json.
uri_hash dan body_hash harus di-hash ke nilai yang sama seperti parameter kueri dan body permintaan yang dikirim ke permintaan. (Urutan nilai juga harus identik.)

Batas jumlah panggilan API: Hingga 300 panggilan tersedia dalam 1 menit.

Contoh ketika tidak ada body permintaan

Silakan masukkan kunci akses, kunci rahasia, worldld, uri, dan parameter kueri sesuai dengan API yang ingin Anda gunakan.

Kode contoh di bawah ini telah ditulis berdasarkan API Data Pemain dari kategori DataStorage.

Java

String accessKey = "accessKey";
String secretKey = "secretKey";
 
String worldId = "com.test.world";
String uri = "/datastorage/v1/worlds/" + worldId + "/player-data";
 
MessageDigest uriHash = MessageDigest.getInstance("SHA-256");
uriHash.update(uri.getBytes(StandardCharsets.UTF_8));
byte[] uriHashBytes = uriHash.digest();
 
ObjectMapper objectMapper = new ObjectMapper();
 
Map<String, Object> payload = new HashMap<>();
payload.put("access_key", accessKey);
payload.put("nonce", UUID.randomUUID().toString());
payload.put("uri_hash", new String(Base64.encodeBase64(uriHashBytes), StandardCharsets.UTF_8));
 
String jwtToken = Jwts.builder()
                    .setPayload(objectMapper.writeValueAsString(payload))
                    .signWith(SignatureAlgorithm.HS256, secretKey.getBytes(StandardCharsets.UTF_8))
                    .compact();
 
String authorization = "Bearer " + jwtToken;

Python

import jwt
import uuid
import hashlib
import base64
 
accessKey = 'accessKey'
secretKey = 'secretKey'
 
worldId = 'com.test.world'
uri = '/datastorage/v1/worlds/' + worldId + '/player-data?playerId=testplayerid&keys=test'
hash = hashlib.sha256()
hash.update(uri.encode())
 
payload = {
    'access_key': accessKey,
    'nonce': str(uuid.uuid4()),
    'uri_hash': base64.b64encode(hash.digest()).decode('utf8')
}
 
jwt_token = jwt.encode(payload, secretKey)
authorization = 'Bearer {}'.format(jwt_token)

NodeJS

import * as jwt from 'jsonwebtoken';
import * as uuid from 'uuid';
import * as crypto from 'crypto-js';
import { Buffer } from 'safe-buffer';

const accessKey = 'accessKey';
const secretKey = 'secretKey';
const worldId = 'com.test.world';
const uri = '/datastorage/v1/worlds/' + worldId + '/player-data?playerId=testplayerid&keys=test';
const hash = crypto.SHA256(uri);

const payload = {
  access_key: accessKey,
  nonce: uuid.v4(),
  uri_hash: Buffer.from(hash.toString(), 'hex').toString('base64')
};
const jwtToken = jwt.sign(payload, secretKey);
const authorization = `Bearer ${jwtToken}`;

Contoh ketika ada Request Body

Silakan masukkan access key, secret key, worldId, uri, dan parameter body sesuai dengan API yang ingin Anda gunakan.

Kode contoh di bawah ini telah ditulis berdasarkan API Set Player Data dari kategori DataStorage.

Java

String accessKey = "accessKey";
String secretKey = "secretKey";
 
String worldId = "com.test.world";
String uri = "/datastorage/v1/worlds/" + worldId + "/player-data";
 
MessageDigest uriHash = MessageDigest.getInstance("SHA-256");
uriHash.update(uri.getBytes(StandardCharsets.UTF_8));
byte[] uriHashBytes = uriHash.digest();
 
ObjectMapper objectMapper = new ObjectMapper();
 
PlayerData dataMap = new PlayerData("test", "test value");
 
List<PlayerData> dataList = new ArrayList<>();
dataList.add(dataMap);
 
PlayerDataSetParam param = new PlayerDataSetParam(dataList, "testplayerid");
 
 
MessageDigest paramHash = MessageDigest.getInstance("SHA-256");
paramHash.update(objectMapper.writeValueAsString(param).getBytes(StandardCharsets.UTF_8));
byte[] paramHashBytes = paramHash.digest();
 
Map<String, Object> payload = new HashMap<>();
payload.put("access_key", accessKey);
payload.put("nonce", UUID.randomUUID().toString());
payload.put("uri_hash", new String(Base64.encodeBase64(uriHashBytes), StandardCharsets.UTF_8));
payload.put("body_hash", new String(Base64.encodeBase64(paramHashBytes), StandardCharsets.UTF_8));
 
String jwtToken = Jwts.builder()
                    .setPayload(objectMapper.writeValueAsString(payload))
                    .signWith(SignatureAlgorithm.HS256, secretKey.getBytes(StandardCharsets.UTF_8))
                    .compact();
 
String authorization = "Bearer " + jwtToken;

Python

import jwt
import uuid
import hashlib
import base64
import simplejson as json
 
accessKey = 'accessKey' secretKey = 'secretKey'
 
worldId = 'com.test.world'
uri = '/datastorage/v1/worlds/' + worldId + '/player-data'
hash = hashlib.sha256()
hash.update(uri.encode())
 
param = {
    'playerId': 'testplayerid',
    'data':[
        {
            'key': 'test',
            'value': 'test value'
        }
    ]
}
 
param_hash = hashlib.sha256()
param_hash.update(json.dumps(param, ensure_ascii=False, encoding='surrogatepass').encode())
 
payload = {
    'access_key': accessKey,
    'nonce': str(uuid.uuid4()),
    'uri_hash': base64.b64encode(hash.digest()).decode('utf8'),
    'body_hash': base64.b64encode(param_hash.digest()).decode('utf8')
}
 
jwt_token = jwt.encode(payload, secretKey)
authorization = 'Bearer {}'.format(jwt_token)

NodeJS

import * as jwt from 'jsonwebtoken';
import * as uuid from 'uuid';
import * as crypto from 'crypto-js';
import { Buffer } from 'safe-buffer';

const accessKey = 'accessKey';
const secretKey = 'secretKey';
const worldId = 'com.test.world';
const uri = '/datastorage/v1/worlds/' + worldId + '/player-data';
const hash = crypto.SHA256(uri);

const param = {
  playerId: 'testplayerid',
  data: [
    {
      value: 'test value',
      key: 'test'
    }
  ]
};
const paramHash = crypto.SHA256(JSON.stringify(param,null,0));

const payload = {
  access_key: accessKey,
  nonce: uuid.v4(),
  uri_hash: Buffer.from(hash.toString(), 'hex').toString('base64'),
  body_hash: Buffer.from(paramHash.toString(), 'hex').toString('base64')
};
const jwtToken = jwt.sign(payload, secretKey);
const authorization = `Bearer ${jwtToken}`;

❗️ Perhatian

OpenAPI adalah fitur yang disediakan untuk digunakan di web atau aplikasi terpisah.
Saat ini, skrip server ZEPETO tidak dapat melakukan panggilan ZEPETO Open API.
Jika Anda ingin melakukan panggilan Open API di ZEPETO multiplayer, kami menyarankan metode berikut:
- Siapkan server terpisah untuk melakukan logika bisnis yang diperlukan dengan berkomunikasi dengan Open API.
- Gunakan paket httpService di server ZEPETO untuk berkomunikasi langsung dengan server yang telah Anda siapkan.
- Terapkan metode otentikasi yang relatif sederhana antara server, seperti menggunakan header HTTP Authorize, untuk memungkinkan panggilan dalam fitur yang didukung oleh server ZEPETO.

Membuat token otentikasi JWT untuk digunakan dengan API terbuka

Format permintaan API terbuka

Dapatkan Kunci Akses, Kunci Rahasia dari ZEPETO Studio

Membuat token otentikasi JWT

Contoh ketika tidak ada body permintaan

Java

Python

NodeJS

Contoh ketika ada Request Body

Java

Python

NodeJS

﻿