Pola

Halaman ini mencakup pola umum dengan API Cloud Terbuka, terutama sekitar membuat permintaan dan menangani respons.

Jalur

Untuk membuat permintaan ke API Cloud Terbuka, Anda harus terlebih dahulu membentuk URL.URL ini adalah kombinasi dari URL dasar ( https://apis.roblox.com/cloud/v2 ), jalur Open Cloud API (misalnya, /universes/{universe_id}/places/{place_id}/user-restrictions ), dan setiap parameter pencarian (misalnya, ?maxPageSize=25 ).URL permintaan lengkap mungkin terlihat seperti ini:


https://apis.roblox.com/cloud/v2/users/4687549151/inventory-items?maxPageSize=100

Banyak jalur, termasuk contoh di atas, memiliki parameter jalur , ditentukan oleh kurungan ganda di referensi API.Parameter jalur hanyalah variabel yang Anda masukkan sebelum membuat permintaan dan hampir selalu merupakan ID: ID pengguna, ID kelompok, ID tempat, dll.ID seringkali bersifat numerik, tetapi tidak selalu; misalnya, ID penyimpanan data dan penyimpanan memori mendukung aturkarakter yang lebih luas.

Beberapa sumber daya memiliki banyak pola jalur, terlihat di bawah judul Jalur Sumber Daya di referensi API.Sebagai contoh, URL untuk Daftar Batasan Pengguna 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 menyimpulkan perbedaan antara keduanya: beberapa batasan pengguna berlaku untuk seluruh alam semesta (pengalaman), sementara yang lain berlaku untuk tempat tertentu dalam alam semesta.Selain dari tambahan kecil ke jalur dan parameter jalur ekstra, panggilan identik.

Banyak API kembali jalur sebagai bagian dari respons mereka, yang dapat Anda gunakan untuk membuat permintaan lebih lanjut.Jika API membutuhkan lebih dari beberapa detik untuk memenuhi permintaan, sering kali ia mengembalikan operasi operasi daripada sumber daya atau respons itu sendiri.

Panjang dan ketikkonten

Banyak panggilan API, terutama yang membuat atau memperbarui sumber daya, memerlukan tubuh permintaan JSON.Jika permintaan Anda memiliki tubuh, pastikan untuk menyertakan Content-Length dan Content-Type kepala.Kebanyakan klien HTTP menambahkan header ini secara otomatis.

Paginasi

Jika Anda menyebutkan maxPageSize dalam permintaan Anda, beberapa metode akan mengembalikan hasil berhalaman-halaman—pada dasarnya respons parsial:


GET /cloud/v2/users/{user_id}/inventory-items?maxPageSize=25

{
  "inventoryItems": [
    ...
  ],
  "nextPageToken": "aaaBBB"
}


GET /cloud/v2/universes/{universe_id}/data-stores?maxPageSize=25

{
  "dataStores": [
    ...
  ],
  "nextPageToken": "datastore1"
}

Jika respons termasuk nilai untuk nextPageToken , gunakan nilai itu dalam parameter pageToken dari permintaan berikutnya untuk mengambil halaman berikutnya.Ketika nextPageToken kosong atau diabaikan sepenuhnya, Anda telah mencapai akhir hasil Anda:


GET /cloud/v2/users/{user_id}/inventory-items?maxPageSize=25&pageToken=aaaBBB

{
  "inventoryItems": [
    ...
  ],
  "nextPageToken": ""
}


GET /cloud/v2/universes/{universe_id}/data-stores?maxPageSize=25&pageToken=datastore1

{
  "dataStores": [
    ...
  ]
}

Selain dari pageToken, Anda harus menggunakan query yang sama untuk pengurutan agar berfungsi dengan baik. Mengubah parameter filter apa pun menyebabkan kesalahan 400.

Operasi jalan panjang

Beberapa metode mengembalikan objek Operation yang mewakili permintaan berjalan lama yang kemudian mengembalikan respons asinkron nanti.Objek tersebut berisi bidang berikut:

jalur - Jalur akhir untuk memanggil poll untuk menyelesaikan permintaan. Tambahkan jalur ke URL asli basis sumber metode sumber daya.
selesai - Nilai boolean yang mewakili apakah operasi telah selesai atau tidak.
respons - Objek respons. Field ini kosong sampai bidang done memiliki nilai true.
metadata - metadata khusus untuk permintaan yang dibuat.

Contoh Objek Operasi
{
  "path": "v1/assets/12345/operation/xyz",
  "done": true,
  "response": {
    "value1": "myValue",
    "value2": 1234
  },
  "metadata": {
    "metadata1": "string",
    "metadata2": 5678
  }
}

Gunakan jalur objek Operation untuk memilih ketika sumber daya siap.Strategi yang baik adalah menggunakan penundaan eksponensial.Sebagai contoh, Anda mungkin memilih langsung, 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 penundaan pada periksapertama
        if (currentRetries == 0):
            results = GetOperation(operationPath)
        # Coba ulang logika untuk pemeriksaan berikutnya
        else:
            time.sleep(retryPollingDelay)
            results = GetOperation(operationPath)
            # Pengunduran eksponensial
            retryPollingDelay *= retryPollingMultiplier
        # Periksa hasil dan kembalikan jika ada
        if (results.status_code != 200 or results.json()[doneJSONKey]):
            return results
        # Jika tidak, tingkatkan hitungan pencobaan ulang
        else:
           currentRetries += 1

Untuk sampel kode yang lebih lengkap yang menggunakan interval pencobaan tetap daripada jeda mundur eksponensial, lihat Poll untuk hasil.

Pemfilteran

Beberapa metode memungkinkan Anda untuk menyaring respons dengan menyertakan parameter filter dalam permintaan.Bagian berikut menjelaskan syntax filter dan panduan untuk titik akhir yang ditentukan.

Daftar anggota kelompok

Karakter liar - dapat digunakan sebagai ganti ID kelompok untuk daftar anggota di semua kelompok: groups/-/memberships .

Filterisasi sesuai dengan Bahasa Ekspresi Umum (CEL). Hanya dua operator yang didukung:

==
in [...]

Jika Anda menyediakan ID grup di jalur sumber daya, Anda dapat menyaring keanggotaan oleh pengguna atau peran dalam format berikut:

Filter pengguna : filter="user == 'users/9876543210'"
Filter peran : filter="role == 'groups/123/roles/7920705'"

Jika Anda menentukan 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 item inventaris

Anda dapat memfilter berdasarkan status koleksi, ketikitem inventaris, dan ID item inventaris.Jika Anda tidak memberikan filter, seluruh inventaris pengguna dikembalikan.

Format filter adalah daftar terpisah semikolon:

filter={field}={value};{field}={value},{value},...;{field}=...

{field} dapat menjadi salah satu bidang jenis prasetel atau bidang ID di tabel berikut.
{value} bisa menjadi string, boolean, atau enum.Tergantung pada ketikbidang, ini bisa menjadi nilai tunggal (bidang boolean) atau beberapa nilai (bidang daftar).

Anda tidak dapat menggabungkan bidang jenis dan ID dalam filter yang sama.

Ketik bidang

| Filter | Jenis | Deskripsi | | :------------------------ | :------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | badges | boolean | Sertakan lencana dalam respons.Nomor default adalah false. | | gamePasses | boolean | Sertakan pas permainan dalam respons.Nomor default adalah false. | | inventoryItemAssetTypes | Lihat detail aset untuk daftar lengkap jenis aset.| Daftar terpisah koma dari jenis aset untuk dimasukkan.Standar adalah tidak ada.Spesifikasikan * untuk semua jenis aset.Harus memiliki cakupan inventaris untuk disaring oleh tempat yang dibeli. | | onlyCollectibles | boolean | Sertakan hanya koleksi di balasan.Nomor default adalah false.Bidang ini harus digunakan dengan bidang inventoryItemAssetTypes untuk mengembalikan item dan hanya mengembalikan item terbatas non-UGC.| | privateServers | boolean | Sertakan server pribadi dalam respons.Nomor default adalah false.Harus memiliki inventaris baca scope untuk disaring oleh bidang ini. |

Bidang ID

Contoh

Kembalikan semua item koleksi yang dimiliki pengguna:

filter=onlyCollectibles=true;inventoryItemAssetTypes=*
Kembalikan semua item dari jenis yang ditentukan:

filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY
Kembalikan semua item dari jenis yang terdaftar atau pas permainan apa pun.Menghilangkan lencana dari hasil (perilaku yang sama seolah-olah 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
Kembalikan aset, lencana, pas permainan, dan server pribadi yang sesuai 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

Di halaman ini