Halaman ini menangani pola umum dengan Open Cloud APIs, khususnya sekitar membuat permintaan dan menangani respons.
Jalan
Untuk membuat permintaan ke API Open Cloud, Anda harus terlebih dahulu membentuk URL. URL ini adalah kombinasi dari URL dasar ( https://apis.roblox.com/cloud/v2), jalan Open Cloud API (untuk contoh, /universes/universe-id/places/place-id/user
Banyak jalan, termasuk contoh di atas, memiliki parameter jalan , ditandai oleh kurungan berdikur di referensi API. Para parameter jalan adalah hanya variabel yang Anda masukkan sebelum meminta dan hampir selalu ID: ID pengguna, ID kelompok, tempat ID, dll. ID sering bernilai numerik, tetapi tidak selalu; misalnya, data store dan memory store ID mendukung aturkarakter yang
Beberapa sumber daya memiliki banyak pola jalan, terlihat di bawah Paths Sumber Daya header dalam referensi API. Misalnya, URL untuk Menghindari Batas Pengguna Lista dapat menjadi salah satu dari mengikuti:
- https://apis.roblox.com/cloud/cloud/v2/universes/{universe-id}/user-restrictions
- https://apis.roblox.com/cloud/cloud/v2/universes/{universe-id}/places/{place-id}/user-restrictions
Anda mungkin dapat menebak perbedaan antara kedua: beberapa batasan pengguna berlaku untuk seluruh alam semesta (pengalaman), sementara yang lain berlaku untuk lokasi tertentu di dalam alam semesta. Selain dari sedikit tambahan untuk parameter jalan dan jalan tambahan, panggilan sama.
Banyak API mengembalikan jalan sebagai bagian dari respons mereka, yang dapat Anda gunakan untuk membuat permintaan lebih lanjut. Jika API memerlukan lebih dari beberapa detik untuk menyelesaikan permintaan, itu biasanya mengembalikan operasi bukan sumber daya atau respons itu sendiri.
Panjang dan Jenis Konten
Banyak panggilan API, khususnya yang menciptakan atau memperbarui sumber daya, memerlukan tubuh permintaan JSON. Jika permintaan Anda memiliki tubuh, pastikan untuk mencakup Content-Length dan Content-Type header. Kebanyakan klien HTTP menambahkan header ini secara otomatis.
Paginasi
Jika Anda spesifikasi maxPageSize dalam permintaan Anda, beberapa metode mengembalikan hasil berkilau-kilau:
GET /cloud/v2/users/{userId}/inventory-items?maxPageSize=25
{
"inventoryItems": [
...
],
"nextPageToken": "aaaBBB"
}
Jika jawaban meng包含值 untuk nextPageToken , gunakan nilai itu dalam parameter pageToken panggilan berikutnya untuk mengambil halaman berikutnya. Ketika nextPageToken kosong, Anda telah mencapai akhir dari hasil Anda:
GET /cloud/v2/users/{userId}/inventory-items?maxPageSize=25&pageToken=aaaBBB
{
"inventoryItems": [
...
],
"nextPageToken": ""
}
Selain dari pageToken , Anda harus menggunakan query yang sama agar pagination berfungsi dengan benar. Mengubah parameter filter apa pun menghasilkan kesalahan 400.
Operasi Jarak Panjang
Beberapa metode mengembalikan objek Operation yang mewakili permintaan berjalan panjang yang kemudian mengembalikan respons asinkronis. Objek mengandung berbagai lapangan berikut:
- jalan setapak - Jalan setapak endpoint untuk memanggil untuk selesainya permintaan. Tempel jalan ke URL asli base server资源方法.
- dilakukan -NilaiBoolean yang mewakili apakah atau tidak operasi telah selesai.
- respons - Objek respons. Feld ini kosong sampai dengan done field yang memiliki nilai true.
- metadata - Metode data khusus untuk permintaan yang dibuat.
Objek Operasi Contoh
{
"path": "v1/assets/12345/operation/xyz",
"done": true,
"response": {
"value1": "myValue",
"value2": 1234
},
"metadata": {
"metadata1": "string",
"metadata2": 5678
}
}
Gunakan jalan Operation objek untuk mengumpulkan saat sumber daya siap. Strategi yang baik adalah menggunakan backoff eksponensial. Misalnya, Anda mungkin mengumpulkan segera, lalu setelah satu detik, dua detik, empat detik, dll.
def PollForResults(operationPath):
currentRetries = 0
maxRetries = 10
retryPollingDelay = 1
retryPollingMultiplier = 2
while (currentRetries < maxRetries):
# Tidak ada kelambatan pada tes pertama
if (currentRetries == 0):
results = GetOperation(operationPath)
# Coba lagi logika untuk tes berikutnya
else:
time.sleep(retryPollingDelay)
results = GetOperation(operationPath)
# Penurunan eksponensial
retryPollingDelay *= retryPollingMultiplier
# Periksa hasil dan kembalikan jika mereka ada
if (results.status_code != 200 or results.json()[doneJSONKey]):
return results
# Jika tidak, tingkatkan jumlah coba kembali
else:
currentRetries += 1
Untuk contoh kode yang lebih lengkap yang menggunakan interval coba kembali tetap bukan backoff eksponensial, lihat Polling for Results .
Menafsirkan
Beberapa metode memungkinkan Anda untuk menyaring respons dengan menyertakan parameter filter dalam permintaan. Bagian berikut menjelaskan sintaks dan panduan untuk endpoint yang ditentukan.
Daftar Keanggotaan Grup
Karakter wildcard - dapat digunakan sebagai ID grup alih-alih untuk mencantum keanggotaan di semua grup: groups/-/memberships .
Filtering mengikuti Bahasa Ekspresi Umum (CEL). Hanya dua operator yang didukung:
- ==
- in [...]
Jika Anda menyebutkan ID grup di jalan sumber daya, Anda dapat menyaring keanggotaan berdasarkan pengguna atau peran dalam format berikut:
- Filter pengguna : filter="user == 'users/9876543210'"
- Filter peran : filter="role == 'groups/123/roles/7920705'"
Jika Anda menyebutkan karakter liar untuk ID grup, Anda harus menyaring keanggotaan oleh pengguna (hingga 50) dalam format berikut:
- Filter pengguna : filter="user in ['users/1', 'users/156', 'users/9876543210', ...]"
Daftar Inventori Barang
Anda dapat menyaring berdasarkan status koleksibel, ketikitem inventaris, dan ID item inventaris. Jika Anda tidak menyediakan filter, seluruh inventaris pengguna dikembalikan.
Format filter adalah daftar semikolon-terpisah:
filter={field}={value};{field}={value},{value},...;{field}=...
- {field} dapat menjadi salah satu dari jenis lapangan prasetel atau ID lapangan di tabel berikut.
- {value} dapat menjadi string, boolean, atau enum. Tergantung pada ketiklapangan, ini dapat menjadi satu nilai (field booleh) atau beberapa nilai (list field).
Anda tidak dapat menggabungkan field type dan ID di filter yang sama.
Jenis Fields
| Saring | Tipe | Deskripsi | | :---------------- | :
Ladang ID
| Saring | Ketik | Deskripsi | | | | | | | | | | | | | | | | | | | | | |
Contoh
Mengembalikan semua item koleksibel yang dimiliki pengguna:
filter=onlyCollectibles=true;inventoryItemAssetTypes=*
Mengembalikan semua item dari jenis yang ditentukan:
filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY
Mengembalikan semua item dari jenis yang terdaftar atau game passes. Mengecualikan badge dari hasil (perilaku yang sama seperti jika badges tidak termasuk dalam filter):
filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY;gamePasses=true;badges=false
Mengembalikan aset yang cocok dengan ID yang ditentukan:
filter=assetIds=1,2,3,4
Mengembalikan aset, lencana, game passes, dan server pribadi yang cocok dengan ID yang ditentukan:
filter=assetIds=1,2,3,4;badgeIds=1,2,3,4;gamePassIds=1,2,3,4;privateServerIds=1,2,3,4