Permintaan HTTP dalam permainan

Anda dapat menggunakan HttpService untuk mengirim permintaan HTTP generik ke layanan web pihak ketiga untuk kasus penggunaan seperti analitik, penyimpanan data, atau pencatatan kesalahan. HttpService juga mendukung endpoint 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 File ⟩ Pengaturan Pengalaman ⟩ Keamanan di Studio.

Gunakan dalam plugin

Anda dapat menggunakan HttpService dalam plugin Studio untuk memeriksa pembaruan, mengunduh konten, atau logika bisnis lainnya. Pertama kali plugin mencoba menggunakan layanan ini, 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. Harap diperhatikan bahwa perangkat lunak semacam itu harus didistribusikan terpisah dari plugin itu sendiri dan dapat menimbulkan risiko keamanan.

Gunakan dengan Open Cloud

HttpService saat ini dapat memanggil subset dari endpoint Open Cloud. Anda dapat memanggil endpoint ini dengan cara yang sama seperti Anda memanggil endpoint lainnya 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. Lakukan permintaan.

Contoh kode berikut menunjukkan cara 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("Respon berhasil:", response.StatusCode, response.StatusMessage)
	else
		print("Respon mengembalikan kesalahan:", response.StatusCode, response.StatusMessage)
	end
	print("Isi respon:\n", response.Body)
	print("Header respon:\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

Endpoint Open Cloud yang Didukung

Endpoint berikut didukung. Karena batasan 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

Penyimpanan data dan memori

Penyimpanan data:

• ListDataStores
• SnapshotDataStores
• ListDataStoreEntries
• CreateDataStoreEntry
• GetDataStoreEntry
• DeleteDataStoreEntry
• UpdateDataStoreEntry
• IncrementDataStoreEntry
• ListDataStoreEntryRevisions
• ListDataStoreEntries (Dengan Lingkup)
• CreateDataStoreEntry (Dengan Lingkup)
• GetDataStoreEntry (Dengan Lingkup)
• DeleteDataStoreEntry (Dengan Lingkup)
• UpdateDataStoreEntry (Dengan Lingkup)
• IncrementDataStoreEntry (Dengan Lingkup)
• ListDataStoreEntryRevisions (Dengan 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

Universe

• UpdateUniverse
• GetUniverse
• PublishUniverseMessage
• RestartUniverseServers

Pengguna

• GetUser
• GenerateUserThumbnail

Batasan

• 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 laju

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

• Permintaan Open Cloud tidak mengkonsumsi batas keseluruhan yang sama dari 500 permintaan HTTP per menit yang diterapkan pada semua permintaan lainnya.
• Setiap endpoint memiliki batasnya sendiri per pemilik kunci API (bisa berupa pengguna atau grup) yang diterapkan tidak peduli dari mana panggilan berasal (HttpService, web, dll.).

Untuk informasi lebih lanjut tentang batasan laju Open Cloud, pembatasan laju berbasis otentikasi, dan praktik terbaik, lihat Batasan Laju.

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, validasi dan sanitasi semua data yang diterima dari API eksternal dengan ketat, memastikan data yang benar di mana Anda bisa.

• Gunakan exponential backoff untuk tetap di bawah batas.

  Jika permintaan mengembalikan kesalahan yang dapat dipulihkan, alih-alih segera mencoba lagi, tunggu selama dua detik, kemudian empat, delapan, dll. antara percobaan. Ini membantu membatasi kemacetan dan meningkatkan kemungkinan permintaan yang berhasil dengan memberikan waktu bagi endpoint untuk "mendingin."

• Agregasi 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 endpoint bulk/batch dan, jika ya, 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 endpoint 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 menampilkan dua grafik utama: Jumlah Permintaan yang melacak volume permintaan HttpService dari permainan Anda, dan Waktu Respon yang mengukur latensi untuk endpoint merespons.

Dimensi yang tersedia untuk penyaringan 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 Server Internal)
• 503 (Layanan Tidak Tersedia)
• ExternalError (kode kesalahan lain yang tidak ditentukan yang dikembalikan dari layanan eksternal)
• InternalError (masalah yang dikembalikan dari HttpService dalam Roblox)

Grafik Waktu Respon tidak berkorelasi dengan data status. Jika Anda memilih "Status" sebagai pemecahan atau penyaring, grafik ini tidak akan menampilkan data.

Pertimbangan tambahan

• Permintaan harus menyediakan bentuk otentikasi yang aman, seperti kunci rahasia yang dibagikan sebelumnya, sehingga aktor jahat tidak dapat berpura-pura sebagai salah satu server Roblox Anda.
• Waspadai kapasitas umum dan kebijakan pembatasan laju dari server web yang menjadi tujuan permintaan.