Pola

Halaman ini mencakup pola umum dengan API Open Cloud, khususnya terkait pembuatan permintaan dan penanganan respons.

Jalur

Untuk membuat permintaan ke API Open Cloud, Anda harus terlebih dahulu membentuk URL. URL ini adalah kombinasi dari URL dasar (misalnya, https://apis.roblox.com), jalur API Open Cloud (misalnya, /cloud/v2/universes/{universe_id}/places/{place_id}/user-restrictions), dan parameter query apa pun (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, yang ditentukan dengan tanda kurung kurawal dalam referensi API. Parameter jalur hanyalah variabel yang Anda masukkan sebelum membuat permintaan dan hampir selalu merupakan ID: ID pengguna, ID grup, ID tempat, dll. ID sering kali numerik, tetapi tidak selalu; misalnya, ID store data dan ID store memori mendukung himpunan karakter yang lebih luas.

Panjang dan tipe konten

Banyak panggilan API, terutama yang membuat atau mengupdate, memerlukan tubuh permintaan JSON. Jika permintaan Anda memiliki tubuh, pastikan untuk menyertakan header Content-Length dan Content-Type. Sebagian besar klien HTTP menambahkan header ini secara otomatis.

Paginasi

Jika Anda menentukan maxPageSize dalam permintaan Anda, beberapa metode mengembalikan hasil yang dipaginasi—sebenarnya 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 menyertakan nilai untuk nextPageToken, gunakan nilai tersebut dalam parameter pageToken dari permintaan berikutnya untuk mengambil halaman berikutnya. Ketika nextPageToken kosong atau dihilangkan sama sekali, Anda telah mencapai akhir dari 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 pageToken, Anda harus menggunakan kueri yang sama untuk paginasi agar berfungsi dengan benar. Mengubah parameter filter apa pun mengakibatkan kesalahan 400.

Open Cloud v2

Beberapa jalur

Beberapa sumber daya memiliki beberapa pola jalur, terlihat di bawah header Jalur Sumber Daya dalam referensi API. Misalnya, URL untuk Daftar Pembatasan Pengguna bisa salah satu dari yang berikut:

• 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 pembatasan pengguna berlaku untuk seluruh alam semesta (permainan), sedangkan yang lain berlaku untuk tempat tertentu dalam sebuah alam semesta. Selain penambahan kecil pada jalur dan parameter jalur tambahan, pemanggilan tersebut identik.

Banyak endpoint mengembalikan jalur sebagai bagian dari respons mereka, yang dapat Anda gunakan untuk membuat permintaan lebih lanjut. Jika API memerlukan lebih dari beberapa detik untuk memenuhi permintaan, biasanya mengembalikan operasi daripada sumber daya atau respons itu sendiri.

Operasi yang berlangsung lama

Beberapa metode mengembalikan objek Operation yang mewakili permintaan yang berlangsung lama yang mengembalikan respons asinkron nanti. Objek ini berisi bidang berikut:

• path - Jalur endpoint untuk memanggil untuk memeriksa penyelesaian permintaan. Tambahkan jalur ke URL dasar asli dari metode sumber daya.
• done - Nilai boolean yang mewakili apakah operasi tersebut telah selesai atau tidak.
• response - Objek respons. Bidang ini kosong sampai bidang done memiliki nilai true.
• metadata - Metadata khusus untuk permintaan yang sedang dilakukan.

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 memeriksa kapan sumber daya sudah siap. Strategi yang baik adalah menggunakan penundaan eksponensial. Misalnya, Anda mungkin memeriksa 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 penundaan pada pemeriksaan pertama
        if (currentRetries == 0):
            results = GetOperation(operationPath)
        # Logika ulang untuk pemeriksaan berikutnya
        else:
            time.sleep(retryPollingDelay)
            results = GetOperation(operationPath)
            # Penundaan eksponensial
            retryPollingDelay *= retryPollingMultiplier
        # Periksa hasil dan kembalikan jika ada
        if (results.status_code != 200 or results.json()[doneJSONKey]):
            return results
        # Jika tidak, tingkatkan jumlah percobaan
        else:
           currentRetries += 1

Untuk contoh kode yang lebih lengkap yang menggunakan interval percobaan tetap daripada penundaan eksponensial, lihat Periksa hasil.

Penyaringan

Beberapa metode memungkinkan Anda menyaring respons dengan menyertakan parameter filter dalam permintaan. Bagian berikut menjelaskan sintaks dan pedoman filter untuk endpoint yang ditentukan.

Daftar keanggotaan grup

Karakter wildcard - dapat digunakan sebagai pengganti ID grup untuk mendaftar keanggotaan di semua grup: groups/-/memberships.

Penyaringan mematuhi Common Expression Language (CEL). Hanya dua operator yang didukung:

• ==
• in [...]

Jika Anda menentukan ID grup dalam jalur 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 menentukan karakter wildcard untuk ID grup, Anda harus menyaring keanggotaan berdasarkan pengguna (hingga 50) dalam format berikut:

• Filter pengguna: filter=user in ['users/1', 'users/156', 'users/9876543210', ...]

Daftar item inventaris

Anda dapat menyaring berdasarkan status kolektibel, tipe item inventaris, dan ID item inventaris. Jika Anda tidak memberikan filter, seluruh inventaris pengguna akan dikembalikan.

Format filter adalah daftar yang dipisahkan oleh tanda titik koma:

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

• {field} dapat berupa salah satu bidang tipe yang sudah ditentukan atau bidang ID dalam tabel berikut.
• {value} dapat berupa string, boolean, atau enum. Bergantung pada jenis bidang, ini dapat berupa satu nilai (bidang boolean) atau beberapa nilai (bidang daftar).

Bidang tipe

Bidang ID

Contoh

• Mengembalikan semua item kolektibel yang dimiliki pengguna:

  filter=onlyCollectibles=true;inventoryItemAssetTypes=*

• Mengembalikan semua item dari tipe tertentu:

  filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY

• Mengembalikan semua item dari tipe yang tercantum atau akses permainan apa pun. Mengecualikan lencana dari hasil (perilaku yang sama seolah badges tidak disertakan 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, akses permainan, 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