Penanganan permintaan API untuk penyimpanan data

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

Otorisasi

Seperti semua API Cloud Terbuka, akhir penyimpanan data memerlukan semua permintaan untuk memasukkan header x-api-key, yang berisi kunci API dengan cukup izin untuk permintaan.Ini memerlukan Anda untuk menerapkan kunci ke pengalaman dan tokodata, dan operasi endpoint diizinkan.Jika kunci tidak valid, 403 Unauthorized dikembalikan.Untuk informasi lebih lanjut tentang kunci API, lihat Manajemen kunci API.

Mempercepat

Semua ujung memiliki dua jenis penyempurnaan tingkat alam semesta: penyempurnaan permintaan per menit dan penyempurnaan melalui putaran .Dengan setiap pengalaman, pengurangan permintaan per menit memungkinkan Anda mengirim jumlah tertentu permintaan per menit, dan pengurangan lalu lintas memungkinkan Anda mengirim jumlah tertentu data per menit, terlepas dari jumlah kunci API.

Tidak seperti API Luau, batasan ini saat ini tidak skala berdasarkan hitungan pengguna. Melampaui batasan ini menyebabkan endpoint untuk kembali 429 Too Many Requests .

Toko data standar membatasi batas penyempurnaan

Toko data yang diperintahkan membatasi batas penggunaan

Validasi masukan

Sebelum mengirim permintaan Anda, pastikan untuk memeriksa parameter ujung pada persyaratan dan batasan formatasi berdasarkan tabel berikut.Akhiran individu dapat memiliki persyaratan tambahan di luar ini.Jika parameter tidak memenuhi batasan berikut, akhiran akan mengembalikan 400 Bad Request .

ID Alam Semesta

ID Alam Semesta adalah identifikator unik dari pengalaman di mana Anda ingin mengakses penyimpanan data Anda.Nilai ID Alam Semesta dari pengalaman adalah nilai dari , tidak sama dengan ID Tempat Mulai dari pengalaman, yang mengidentifikasi tempat mulai dari pengalaman bukan seluruh pengalaman.

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

1. Navigasikan ke Dashboard Pencipta.

2. Cari pengalaman dengan penyimpanan data yang ingin Anda akses.

3. Pasang mouse di atas thumbnail pengalaman, klik tombol ⋯ dan pilih Copy Universe ID .

   

Scope

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

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

Semua metode operasi masuk penyimpanan data memiliki parameter Scope ketika Anda perlu mengakses entri yang disimpan di bawah scope non-默认.Sebagai contoh, Anda mungkin memiliki kunci 1234 di bawah scope default global, dan kunci yang sama di bawah scope special.Anda dapat mengakses yang pertama tanpa menggunakan parameter scope, tetapi untuk mengakses yang terakhir, Anda harus menyediakan parameter scope sebagai di atau API panggilan.

Selain itu, jika Anda ingin mencantumkan semua kunci yang disimpan di penyimpan data yang memiliki satu atau beberapa scope non-default, Anda dapat mengatur parameter AllScopes dalam metode List Entries untuk menjadi true , di mana panggilan tersebut mengembalikan tuple dengan string kunci dan scope.Dalam contoh sebelumnya, List Entries akan mengembalikan keduanya ( 1234 , global ), dan ( 1234 , special ) dalam respons.

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

Daftar Kunci untuk Berbagai Skop
# Membuat
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 lingkup khusus
specialScopeKeys = DatastoresApi.list_entries(datastoreName, scope = "special", allScopes = False)
print(keys.content)
# Daftar kunci untuk semuaScope ditetapkan ke benar
specialScopeKeys = DatastoresApi.list_entries(datastoreName, allScopes = True)
print(specialScopeKeys.content)

Kunci dengan scope yang sesuai dikembalikan dalam respons:

Contoh Respon untuk Berbagai Skop
// Respon untuk skala global
{ "keys": [{ "scope": "global", "key": "User_2" }], "nextPageCursor": "" }

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

// Respon untuk Semua Skop
{"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 basis-64 dienkodekan MD5 checksum dari konten.Ini adalah header permintaan opsional untuk endpoint Set Input yang memeriksa integritas data dan mendeteksi masalah potensial.

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

Membuat Konten-MD5
# Dengan perintah
$ 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 mengalami masalah menghasilkan nilai content-md5 yang valid, Anda mungkin perlu mengodekan tubuh permintaan Anda dalam biner UTF-8 sebelum menghitung checksum.

Kursi

Akhiran yang mengembalikan daftar data mungkin juga mengembalikan string nextPageCursor.Ini menunjukkan bahwa ada lebih banyak data yang tersedia dalam aturhasil yang diminta.Untuk menerimanya, berikan string ini dalam parameter pencarian cursor pada permintaan berikutnya.Jika parameter kursor disediakan tetapi tidak valid, akhir pengembalian mengembalikan 400 Bad Request .

Format string kursor tidak didefinisikan tidak didefinisikan . Anda tidak boleh menafsirkan atau mem parse mereka karena mereka dapat berubah kapan saja.

Filter

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

Parameter filter mendukung satu operator logika, && , dan dua operator perbandingan, <= untuk mengatur nilai maksimum dan >= untuk mengatur nilai minimum.Jika Anda ingin mengatur rentang dengan nilai maksimum dan minimum, tambahkan && di antara kedua urutan.

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

Contoh berikut adalah nilai yang tidak benar filter yang dapat gagalkan permintaan Anda:

• entry <= 10 - tidak ada spasi 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 minimum dan maksimum.

Izinkan bendera yang hilang

Saat mengirim permintaan ke metode Update untuk memperbarui entri data terstruktur yang sudah ada, Anda dapat menambahkan bendera opsional allow_missing untuk memungkinkan pembuatan entri bahkan jika entri tidak ada.

Ketika Anda mengatur flag allow_missing ke True :

• Jika entri tidak ada, respons men返ikan entri baru.

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

• Jika entri ada dan konten tidak cocok dengan nilai entri yang ada, respons mem返ikan entri dengan nilai konten baru yang diperbarui.