Mengelola Permintaan API untuk Toko Data

Sebelum mengirim permintaan untuk Open Cloud APIs untuk simpan data standar dan toko data yang dipesan, Anda perlu memahami cara menanganinya dengan benar. Untuk informasi tentang penggunaan API, lihat Panduan Penggunaan.

Autentikasi

Seperti semua Open Cloud API, titik akhir penyimpanan data mengharuskan semua permintaan untuk mencakup x-api-key header, yang berisi kunci API dengan cukup izin untuk permintaan. Ini mengharuskan Anda untuk menerapkan kunci ke pengalaman dan penyimpanan data, dan operasi端口 diizinkan. Jika kunci tidak

Mengecepat

Semua endpoints memiliki dua jenis tingkat level universe level throttling: request-per-minute throttling dan throughput throttling . Dengan setiap pengalaman, request-per-minute throttling memungkinkan Anda untuk mengirim jumlah tertentu permintaan per menit, dan 1> throughput throttling1> memungk

Tidak seperti API Lua, batas-batas ini saat ini tidak skalasi berdasarkan jumlah pengguna. Melebihi batas-batas ini menyebabkan penyelesaian端口 429 Too Many Requests .

Batas-batas Kecepatan Pengganda Data Standar

Memesan Toko Data Mempercepat Batas

Validasi Masukan

Sebelum mengirim permintaan Anda, pastikan untuk mengevaluasi parameter akhir pada persyaratan dan kendala pemformatan berdasarkan tabel berikut. Endpoint individu dapat memiliki persyaratan tambahan di luar batasan ini. Jika parameter tidak memenuhi batasan berikut, endpoint mengembalikan 400 Bad Request .

ID Universe

ID Alam Semesta adalah identifikator unik dari pengalaman di mana Anda ingin mengakses toko data Anda.Nilai dari ID Alam Semesta pengalaman adalah nilai dari DataModel.GameId , bukan dari 1> tempat awal ID1>, yang mengidentifikasi tempat awal pengalaman daripada seluruh pengalaman.

Anda dapat mengambil ID Alam Semesta dari pengalaman dengan langkah berikut:

1. Navigasikan ke Dashboard Pencipta.

2. Temukan pengalaman dengan toko data yang ingin Anda akses.

3. Klik tombol ⋯ pada gambar miniatur pengalaman target untuk menunjukkan daftar opsi, lalu pilih Copy Universe ID .

   

Skala

Anda dapat mengatur penyimpanan data Anda dengan menetapkan string unik sebagai scope yang menentukan subfolder untuk entri. Setelah Anda menetapkan scope, itu secara otomatis menambahkan ke semua kunci dalam semua operasi yang dilakukan di tokodata. Scopes adalah opsional dan secara default sebagai global untuk penyimpanan data standar tetapi diperlukan untuk penyimpanan data yang dipesan.

Skala mengkategorikan data Anda dengan string dan pemisah dengan "/", seperti:

Semua metode operasi penyimpanan data memiliki Scope parameter untuk ketika Anda perlu mengakses entri yang disim

Selain itu, jika Anda ingin menghitung semua kunci yang disimpan di toko data yang memiliki satu atau le

Anda tidak dapat menyebutkan Scope dan AllScopes parameter pada permintaan yang sama, jika tidak, panggilan akan mengembalikan kesalahan.Menggunakan fungsi bantuan dari Open Cloud APIs untuk modul penyimpanan data, kode berikut menunjukkan cara Anda dapat membaca setiap kunci dalam penyimpanan data dengan skala khusus:

Daftar Kunci untuk Berbagai Skala
# Mengatur
import tutorialFunctions
DatastoresApi = tutorialFunctions.DataStores()
datastoreName = "PlayerInventory"

# Daftar kunci untuk skala global
specialScopeKeys = DatastoresApi.list_entries(datastoreName, scope = "global",  allScopes = False)
print(keys.content)
# Daftar kunci untuk scope khusus
specialScopeKeys = DatastoresApi.list_entries(datastoreName, scope = "special", allScopes = False)
print(keys.content)
# Daftar kunci untuk semuaScope di set ke benar
specialScopeKeys = DatastoresApi.list_entries(datastoreName, allScopes = True)
print(specialScopeKeys.content)

Kunci dengan scope yang sesuai dikembalikan dalam respons:

Contoh Tanggapan untuk Berbagai Skala
// Balasan untuk skala global
{ "keys": [{ "scope": "global", "key": "User_2" }], "nextPageCursor": "" }

// Balasan untuk skala khusus
{"keys":[{"scope":"special","key":"User_6"},{"scope":"special","key":"User_7"}],"nextPageCursor":""}

// Balasan untuk SemuaSkop
{"keys":[{"scope":"global","key":"User_3"},{"scope":"global","key":"User_4"},{"scope":"global","key":"User_5"},{"scope":"special","key":"User_6"},{"scope":"special","key":"User_7"}],"nextPageCursor":""}

Konten-MD5

Content-MD5 adalah base-64 encoded MD5 checksum dari konten. Ini adalah header permintaan opsional untuk Set Entry endpoint yang memeriksa integritas data dan mendeteksi masalah potensial.

Anda dapat menggunakan bahasa pilihan Anda untuk menghitung nilai content-md5 header. Contoh berikut menggunakan Python. Fungsi hashlib.md5() dan base64.b64Encode() tersedia dalam library standar Python (2.7, 3+).

Membuat Konten-MD5
# Dengan prompt
$ python -c "import base64, hashlib; print('content-md5: ' + str(base64.b64encode(hashlib.md5(bytes(input('content: '), encoding='utf8')).digest()), encoding='utf8'))"
content: 750
content-md5: sTf90fedVsft8zZf6nUg8g==
# Menggunakan hanya stdin dan stdout
$ echo "750" | python -c "import base64, hashlib; print(str(base64.b64encode(hashlib.md5(bytes(input(), encoding='utf8')).digest()), encoding='utf8'))"
sTf90fedVsft8zZf6nUg8g==

Jika Anda menghadapi masalah meng生成 valid content-md5 nilai, Anda mungkin perlu meng-Encoding request body Anda dalam UTF-8 binary sebelum menghitung checksum.

Kursi

Endpoints yang mengembalikan daftar data juga dapat mengembalikan string nextPageCursor. Ini menunjukkan bahwa ada lebih banyak data tersedia dalam aturhasil yang diminta. Untuk menerimanya, berikan string ini dalam parameter permintaancursor pada panggilan berikutnya. Jika parameter cursor tidak diberikan tetapi tidak valid, endpoints mengembalikan 40

Format string cursor adalah tidak didefinisikan . Anda seharusnya tidak meng interpretasi atau menganalisis mereka karena mereka mungkin berubah kapan saja.

Filter

Ketika mengirim permintaan ke metode List > metode untuk penyimpanan data yang dipesan, Anda dapat menambahkan parameter filter opsional untuk mengembalikan entri dengan nilai dalam rentang tertentu.

Para filter parameter mendukung satu operator logika, && , dan dua operator perbandingan, <= untuk menetapkan nilai maksimum dan 1> >=1> untuk menetapkan nilai minimum. Jika Anda ingin menetapkan rentang dengan kedua nilai maksimum dan minimum, tambahkan 4> &&4> di antara

Misalnya, untuk mengembalikan entri dengan nilai yang kurang dari atau sama dengan 10, Anda perlu menulis entry <= 10 sebagai nilai filter. Untuk mengembalikan entri dengan nilai di antara 10 dan 50, masukkan entry <= 50 && entry >= 10 .

Berikut adalah contoh yang salah filter nilai yang dapat gagal permintaan Anda:

• entry <= 10 - tidak ada ruang putih di antara setiap bagian dari urutan.
• 10 <= entry - entry dan nilai perbandingan berada di sisi yang salah.
• entry <= 10 && entry <= 50 - && hanya dapat digunakan untuk menentukan rentang dengan kedua operator perbandingan untuk nilai min dan maks.

Izinkan Bayangan yang Hilang

Ketika mengirim permintaan ke metode Update untuk menyimpan entri data yang dipesan sebelumnya, Anda dapat menambahkan tag allow_missing yang opsional untuk memungkinkan pembuatan entri bahkan jika entri tidak ada.

Ketika Anda menetapkan bendera allow_missing ke True :

• Jika entri tidak ada, jawaban mengembalikan entri baru.

• Jika entri ada tetapi kontennya cocok dengan nilai yang sudah ada dari entri, entri yang sudah ada tetap tidak berubah.

• Jika entri ada dan konten tidak cocok dengan nilai value entri yang sudah ada, respons menyelesaikan entri dengan nilai value konten yang diperbarui.