Permintaan HTTP dalam permainan

Anda dapat menggunakan HttpService untuk mengirim permintaan HTTP umum ke layanan web pihak ketiga untuk kasus penggunaan seperti analitik, penyimpanan data, atau pencatatan kesalahan. HttpService juga mendukung titik akhir tertentu dari Open Cloud.

Aktifkan permintaan HTTP

Metode HttpService:GetAsync(), HttpService:PostAsync(), dan HttpService:RequestAsync() tidak diaktifkan secara default. Untuk mengirim permintaan, Anda harus Mengizinkan Permintaan HTTP di bawah Pengaturan Pengalaman untuk permainan Anda.

Menggunakan di plugin

Anda dapat menggunakan HttpService di plugin Studio untuk memeriksa pembaruan, mengunduh konten, atau logika bisnis lainnya. Pertama kali plugin mencoba menggunakan layanan tersebut, pengguna mungkin diminta untuk memberikan izin kepada plugin untuk berkomunikasi dengan alamat web tertentu. Pengguna dapat menerima, menolak, dan mencabut izin ini kapan saja melalui jendela Manajemen Plugin.

Plugin juga dapat berkomunikasi dengan perangkat lunak lain yang berjalan di komputer yang sama melalui host localhost dan 127.0.0.1. Dengan menjalankan program yang kompatibel dengan plugin tersebut, Anda dapat memperluas fungsionalitas plugin Anda di luar kemampuan normal Studio, seperti berinteraksi dengan sistem file komputer Anda. Perlu diingat bahwa perangkat lunak tersebut harus didistribusikan secara terpisah dari plugin itu sendiri dan dapat menimbulkan risiko keamanan.

Menggunakan dengan Open Cloud

HttpService saat ini dapat memanggil subset dari titik akhir Open Cloud. Anda dapat memanggil titik akhir ini dengan cara yang sama seperti Anda memanggil titik akhir lain melalui HttpService. Satu-satunya perbedaan adalah Anda harus menyertakan kunci API Open Cloud dalam permintaan:

1. Buat kunci API Open Cloud.
2. Simpan kunci API ke penyimpanan rahasia Anda.
3. Buat permintaan.

Berikut adalah contoh kode yang menunjukkan bagaimana memperbarui keanggotaan grup pengguna dari dalam permainan:

local HttpService = game:GetService("HttpService")

local groupId = "your_group_id"
local membershipId = "your_membership_id"
local roleId = "your_role_id"

local function request()
	local response = HttpService:RequestAsync({
		Url = `https://apis.roblox.com/cloud/v2/groups/{groupId}/memberships/{membershipId}`,
		Method = "PATCH",
		Headers = {
			["Content-Type"] = "application/json", -- Saat mengirim JSON, atur ini!
			["x-api-key"] = HttpService:GetSecret("APIKey"), -- Atur di Creator Hub
		},
		Body = HttpService:JSONEncode({ role = `groups/{groupId}/roles/{roleId}` }),
	})

	if response.Success then
		print("Respons berhasil:", response.StatusCode, response.StatusMessage)
	else
		print("Respons mengembalikan kesalahan:", response.StatusCode, response.StatusMessage)
	end
	print("Isi respons:\n", response.Body)
	print("Header respons:\n", HttpService:JSONEncode(response.Headers))
end

-- Bungkus fungsi dalam pcall() untuk keamanan
local success, errorMessage = pcall(request)
if not success then
	print("Permintaan HTTP gagal dikirim:", errorMessage)
end

Titik Akhir Open Cloud yang Didukung

Titik akhir berikut didukung. Karena keterbatasan saat ini pada HttpService, string .. tidak diizinkan dalam parameter jalur URL ke domain Roblox. Ini berarti, misalnya, bahwa penyimpanan data dan entri yang mengandung string ini saat ini tidak dapat diakses dari HttpService.

Aset

• GetAsset
• ListAssetVersions
• GetAssetVersion

Larangan dan blokir

• ListUserRestrictions (Tempat)
• GetUserRestriction (Tempat)
• UpdateUserRestriction (Tempat)
• ListUserRestrictions (Universe)
• GetUserRestriction (Universe)
• UpdateUserRestriction (Universe)
• ListUserRestrictionLogs (Universe)

Konfigurasi

• GetConfigRepositoryValues
• GetConfigRepositoryDraft
• UpdateDraft
• DeleteDraft
• OverwriteDraft
• GetConfigRepositoryFull
• PublishDraft
• ListRevisions
• RestoreRevision

Toko Pembuat

• CreateCreatorStoreProduct
• GetCreatorStoreProduct
• UpdateCreatorStoreProduct
• CreatorStoreAssetsSearch

Produk pengembang

• CreateDeveloperProduct
• UpdateDeveloperProduct
• GetDeveloperProductConfig
• ListDeveloperProductConfigsByUniverse

Game pass

• CreateGamePass
• UpdateGamePass
• GetGamePassConfig
• ListGamePassConfigsByUniverse

Data dan penyimpanan memori

Penyimpanan data:

• ListDataStores
• SnapshotDataStores
• ListDataStoreEntries
• CreateDataStoreEntry
• GetDataStoreEntry
• DeleteDataStoreEntry
• UpdateDataStoreEntry
• IncrementDataStoreEntry
• ListDataStoreEntryRevisions
• ListDataStoreEntries (Dengan Ruang Lingkup)
• CreateDataStoreEntry (Dengan Ruang Lingkup)
• GetDataStoreEntry (Dengan Ruang Lingkup)
• DeleteDataStoreEntry (Dengan Ruang Lingkup)
• UpdateDataStoreEntry (Dengan Ruang Lingkup)
• IncrementDataStoreEntry (Dengan Ruang Lingkup)
• ListDataStoreEntryRevisions (Dengan Ruang Lingkup)

Penyimpanan memori:

• CreateMemoryStoreQueueItem
• DiscardMemoryStoreQueueItems
• ReadMemoryStoreQueueItems
• ListMemoryStoreSortedMapItems
• CreateMemoryStoreSortedMapItem
• GetMemoryStoreSortedMapItem
• DeleteMemoryStoreSortedMapItem
• UpdateMemoryStoreSortedMapItem
• FlushMemoryStore

Penyimpanan data terurut:

• ListOrderedDataStoreEntries
• CreateOrderedDataStoreEntry
• GetOrderedDataStoreEntry
• DeleteOrderedDataStoreEntry
• UpdateOrderedDataStoreEntry
• IncrementOrderedDataStoreEntry

Grup

• GetGroup
• ListGroupJoinRequests
• AcceptGroupJoinRequest
• DeclineGroupJoinRequest
• ListGroupMemberships
• UpdateGroupMembership
• ListGroupRoles
• GetGroupRole
• GetGroupShout

Inventaris

• ListInventoryItems

Eksekusi Luau

• CreateLuauExecutionSessionTaskBinaryInput
• CreateLuauExecutionSessionTask
• CreateLuauExecutionSessionTask (dengan versi)
• GetLuauExecutionSessionTask
• ListLuauExecutionSessionTaskLogs

Notifikasi

• CreateUserNotification

Tempat

• GetPlace
• UpdatePlace
• GetInstance
• UpdateInstance

Alam semesta

• UpdateUniverse
• GetUniverse
• PublishUniverseMessage
• RestartUniverseServers

Pengguna

• GetUser
• GenerateUserThumbnail

Keterbatasan

• Hanya header x-api-key dan content-type yang diizinkan.
• Header x-api-key harus berupa Secret. Lihat Penyimpanan rahasia.
• String ".." tidak diizinkan dalam parameter jalur URL.
• Hanya protokol HTTPS yang didukung.
• Anda tidak dapat menggunakan port 1194 atau port apa pun di bawah 1024, kecuali 80 dan 443. Jika Anda mencoba menggunakan port yang diblokir, Anda akan menerima kesalahan 403 Forbidden atau ERR_ACCESS_DENIED.

Batasan kecepatan

Untuk setiap server permainan Roblox, ada batasan 2500 permintaan Open Cloud per menit. Melebihi ini dapat menyebabkan metode pengiriman permintaan terhenti sekitar 30 detik. pcall() Anda juga mungkin gagal dengan pesan Jumlah permintaan Open Cloud melebihi batas.

• Permintaan Open Cloud tidak mengonsumsi batasan total yang sama sebesar 500 permintaan HTTP per menit yang diberlakukan pada semua permintaan lainnya.
• Setiap titik akhir memiliki batasannya sendiri per pemilik kunci API (dapat berupa pengguna atau grup) yang diberlakukan terlepas dari dari mana panggilan tersebut berasal (HttpService, web, dll.).

Untuk informasi lebih lanjut tentang batasan kecepatan Open Cloud, pembatasan berbasis autentikasi, dan praktik terbaik, lihat Batasan Kecepatan.

Praktik terbaik

Untuk mengoptimalkan penggunaan HttpService Anda dan menghindari melebihi batas, terapkan praktik terbaik berikut:

• Tangani kesalahan dengan baik. Permintaan web dapat gagal karena berbagai alasan. Gunakan pcall() dan miliki rencana untuk ketika permintaan gagal. Selain itu, secara ketat validasi dan sanitasi semua data yang diterima dari API eksternal, memastikan data yang benar.

• Gunakan exponential backoff untuk tetap di bawah batas.

  Jika sebuah permintaan mengembalikan kesalahan yang dapat dipulihkan, alih-alih segera mencoba kembali, tunggu selama dua detik, lalu empat, delapan, dll. antara percobaan. Ini membantu membatasi kemacetan dan meningkatkan kemungkinan permintaan yang berhasil dengan memberi waktu titik akhir untuk "mendinginkan".

• Aggregasikan dan kirim data dalam jumlah besar.

  Jika memungkinkan, disarankan untuk membiarkan server Anda mengumpulkan semua data yang diperlukan untuk mengirim satu permintaan HTTP, daripada beberapa permintaan kecil. Misalnya, jika Anda mengirim permintaan HTTP untuk setiap pemain di server Anda, periksa apakah API memiliki titik akhir bulk/batch dan, jika demikian, kumpulkan informasi dari semua pemain dan kirim semuanya dalam satu permintaan.

  Dalam beberapa kasus Anda mungkin harus menggunakan HttpService:RequestAsync() untuk menyertakan data dalam tubuh permintaan.

• Gunakan titik akhir HTTP/2. HTTP/2 memberikan manfaat kinerja yang signifikan melalui fitur seperti kompresi header dan multiplexing permintaan/respons melalui satu koneksi. HttpService secara otomatis menggunakan HTTP/2 saat tersedia. Perhatikan bahwa spesifikasi HTTP/2 mengharuskan semua nama header dikirim dalam huruf kecil.

Observabilitas

Dasbor Observabilitas memberikan wawasan dan analitik untuk memantau dan memecahkan masalah penggunaan HttpService Anda. Dasbor ini memiliki dua grafik utama: Jumlah Permintaan yang melacak volume permintaan HttpService dari permainan Anda, dan Waktu Respons yang mengukur latensi bagi titik akhir untuk merespons.

Dimensi yang tersedia untuk pemfilteran dan pemecahan didefinisikan sebagai berikut:

Jenis Permintaan

• GET
• POST
• PUT
• PATCH
• DELETE
• Lainnya (untuk jenis permintaan yang tidak ditentukan)

Status

• Sukses (kode status HTTP 1xx dan 2xx)
• Pengalihan (kode status HTTP 3xx)
• 400 (Permintaan Buruk)
• 401 (Tidak Terotorisasi)
• 403 (Dilarang)
• 404 (Tidak Ditemukan)
• 429 (Terlalu Banyak Permintaan)
• 500 (Kesalahan Internal Server)
• 503 (Layanan Tidak Tersedia)
• ExternalError (kode kesalahan lain dari layanan eksternal yang tidak ditentukan)
• InternalError (masalah yang dikembalikan dari HttpService di dalam Roblox)

Grafik Waktu Respons tidak terkait dengan data status. Jika Anda memilih "Status" sebagai pemecah atau filter, grafik ini tidak akan menampilkan data.

Pertimbangan tambahan

• Permintaan harus memberikan bentuk autentikasi yang aman, seperti kunci rahasia yang telah disepakati sebelumnya, sehingga aktor jahat tidak dapat berpura-pura menjadi salah satu server Roblox Anda.
• Harap perhatikan kapasitas umum dan kebijakan pembatasan kecepatan dari server web ke mana permintaan dikirim.