Oyun içi HTTP istekleri

HttpService'i, analiz, veri depolama veya hata kaydı gibi kullanım durumları için üçüncü taraf web hizmetlerine genel HTTP istekleri göndermek için kullanabilirsiniz. HttpService, belirli Open Cloud uç noktalarını da destekler.

HTTP isteklerini etkinleştirin

HttpService:GetAsync(), HttpService:PostAsync() ve HttpService:RequestAsync() yöntemleri varsayılan olarak etkin değildir. İstek göndermek için, Studio'da Dosya ⟩ Deneyim Ayarları ⟩ Güvenlik altında HTTP İsteklerine İzin Ver seçeneğini etkinleştirmeniz gerekir.

Eklentilerde kullanın

HttpService'i, güncellemeleri kontrol etmek, içerik indirmek veya diğer iş mantıkları için Studio eklentilerinde kullanabilirsiniz. Bir eklenti hizmeti kullanmaya çalıştığında, kullanıcıdan belirli bir web adresiyle iletişim kurmak için eklentiye izin vermesi istenebilir. Kullanıcılar, bu izinleri Eklenti Yönetimi penceresi aracılığıyla her zaman kabul edebilir, reddedebilir veya geri alabilir.

Eklentiler ayrıca aynı bilgisayarda çalışan diğer yazılımlarla localhost ve 127.0.0.1 ana bilgisayarları aracılığıyla iletişim kurabilir. Bu tür eklentilerle uyumlu programlar çalıştırarak, eklentinizin işlevselliğini Studio'nun normal yeteneklerinin ötesine genişletebilir, örneğin bilgisayarınızın dosya sistemiyle etkileşimde bulunabilirsiniz. Ancak, bu tür yazılımların eklentiden ayrı olarak dağıtılması gerektiğini ve güvenlik riskleri oluşturabileceğini unutmayın.

Open Cloud ile kullanın

HttpService, şu anda Open Cloud uç noktalarının bir alt kümesini çağırabilir. Bu uç noktaları, HttpService aracılığıyla herhangi bir diğer uç noktayı çağırdığınız gibi çağırabilirsiniz. Tek fark, istekte bir Open Cloud API anahtarı dahil etmeniz gerektiğidir:

1. Open Cloud API anahtarı oluşturun.
2. API anahtarını gizli depolama alanınıza kaydedin.
3. İsteği yapın.

Aşağıdaki kod örneği, bir oyunun içinden bir kullanıcının grup üyeliğini nasıl güncelleyebileceğini göstermektedir:

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", -- JSON gönderirken bunu ayarlayın!
			["x-api-key"] = HttpService:GetSecret("APIKey"), -- Creator Hub'da ayarlandı
		},
		Body = HttpService:JSONEncode({ role = `groups/{groupId}/roles/{roleId}` }),
	})

	if response.Success then
		print("Yanıt başarılıydı:", response.StatusCode, response.StatusMessage)
	else
		print("Yanıt bir hata döndürdü:", response.StatusCode, response.StatusMessage)
	end
	print("Yanıt gövdesi:\n", response.Body)
	print("Yanıt başlıkları:\n", HttpService:JSONEncode(response.Headers))
end

-- Güvenlik için fonksiyonu pcall() içinde sarın
local success, errorMessage = pcall(request)
if not success then
	print("HTTP isteği gönderilemedi:", errorMessage)
end

Desteklenen Open Cloud uç noktaları

Aşağıdaki uç noktalar desteklenmektedir. HttpService üzerindeki mevcut sınırlamalar nedeniyle, URL yol parametrelerinde .. dizesine izin verilmez. Bu, örneğin, veri depolarının ve bu dizeyi içeren girişlerin şu anda HttpService üzerinden erişilemez olduğu anlamına gelir.

Varlıklar

• GetAsset
• ListAssetVersions
• GetAssetVersion

Yasaklar ve engellemeler

• ListUserRestrictions (Yer)
• GetUserRestriction (Yer)
• UpdateUserRestriction (Yer)
• ListUserRestrictions (Evrensel)
• GetUserRestriction (Evrensel)
• UpdateUserRestriction (Evrensel)
• ListUserRestrictionLogs (Evrensel)

Yapılandırmalar

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

Yaratıcı Mağazası

• CreateCreatorStoreProduct
• GetCreatorStoreProduct
• UpdateCreatorStoreProduct
• CreatorStoreAssetsSearch

Geliştirici ürünleri

• CreateDeveloperProduct
• UpdateDeveloperProduct
• GetDeveloperProductConfig
• ListDeveloperProductConfigsByUniverse

Oyun geçişleri

• CreateGamePass
• UpdateGamePass
• GetGamePassConfig
• ListGamePassConfigsByUniverse

Veri ve bellek depoları

Veri depoları:

• ListDataStores
• SnapshotDataStores
• ListDataStoreEntries
• CreateDataStoreEntry
• GetDataStoreEntry
• DeleteDataStoreEntry
• UpdateDataStoreEntry
• IncrementDataStoreEntry
• ListDataStoreEntryRevisions
• ListDataStoreEntries (Kapsam ile)
• CreateDataStoreEntry (Kapsam ile)
• GetDataStoreEntry (Kapsam ile)
• DeleteDataStoreEntry (Kapsam ile)
• UpdateDataStoreEntry (Kapsam ile)
• IncrementDataStoreEntry (Kapsam ile)
• ListDataStoreEntryRevisions (Kapsam ile)

Bellek depoları:

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

Sıralı veri depoları:

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

Gruplar

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

Envanterler

• ListInventoryItems

Luau yürütmesi

• CreateLuauExecutionSessionTaskBinaryInput
• CreateLuauExecutionSessionTask
• CreateLuauExecutionSessionTask (sürüm ile)
• GetLuauExecutionSessionTask
• ListLuauExecutionSessionTaskLogs

Bildirimler

• CreateUserNotification

Yerler

• GetPlace
• UpdatePlace
• GetInstance
• UpdateInstance

Evrenseller

• UpdateUniverse
• GetUniverse
• PublishUniverseMessage
• RestartUniverseServers

Kullanıcılar

• GetUser
• GenerateUserThumbnail

Sınırlamalar

• Sadece x-api-key ve content-type başlıklarına izin verilmektedir.
• x-api-key başlığı bir Secret olmalıdır. Gizli depolar için bakın.
• URL yol parametrelerinde ".." dizesine izin verilmez.
• Sadece HTTPS protokolü desteklenmektedir.
• 1194 numaralı portu veya 1024'ten düşük herhangi bir portu, 80 ve 443 dışında kullanamazsınız. Engellenen bir portu kullanmaya çalışırsanız, ya 403 Forbidden ya da ERR_ACCESS_DENIED hatası alırsınız.

Hız sınırlamaları

Her Roblox oyun sunucusu için, dakikada 2500 Open Cloud isteği limiti vardır. Bu limiti aşmak, istek gönderme yöntemlerinin yaklaşık 30 saniye boyunca durmasına neden olabilir. pcall()'ınız da Open Cloud istekleri limiti aşıldı mesajıyla başarısız olabilir.

• Open Cloud istekleri, diğer tüm isteklere uygulanan dakikada 500 HTTP isteği genel limitini tüketmez.
• Her uç noktanın, çağrıların nereden geldiğine bakılmaksızın (örneğin HttpService, web vb.) uygulanan kendi limiti vardır (bir kullanıcı veya grup olabilir).

Open Cloud hız sınırlamaları, kimlik doğrulama tabanlı hız sınırlaması ve en iyi uygulamalar hakkında ayrıntılı bilgi için Hız Sınırlamaları sayfasına bakın.

En iyi uygulamalar

HttpService kullanımınızı optimize etmek ve limitleri aşmaktan kaçınmak için aşağıdaki en iyi uygulamaları uygulayın:

• Hataları nazikçe yönetin. Web istekleri birçok nedenle başarısız olabilir. pcall() kullanın ve istekler başarısız olduğunda bir planınız olsun. Ayrıca, dış API'lerden alınan tüm verileri dikkatlice doğrulayın ve temizleyin, mümkün olduğunda doğru verileri sağladığınızdan emin olun.

• Limitlerin altında kalmak için üstel geri çekilme kullanın.

  Bir istek geri kazanılabilir bir hata döndürdüğünde, hemen yeniden denemek yerine, iki saniye bekleyin, ardından dört, sekiz vb. bekleyin. Bu, tıkanıklığı sınırlamaya yardımcı olur ve uç noktanın "soğuması" için zaman vererek başarılı bir isteğin olasılığını artırır.

• Verileri toplu olarak toplayın ve gönderin.

  Mümkünse, sunucunuzun gerekli tüm verileri toplamasına ve bir HTTP isteği göndermesine izin vermek, birden fazla küçük isteği göndermekten daha iyidir. Örneğin, sunucunuzdaki her oyuncu için bir HTTP isteği gönderiyorsanız, API'nin bir toplu/batch uç noktası olup olmadığını kontrol edin ve varsa, tüm oyunculardan bilgileri toplayın ve hepsini tek bir istekte gönderin.

  Bazı durumlarda, isteğin gövdesine veri eklemek için HttpService:RequestAsync() kullanmanız gerekebilir.

• HTTP/2 uç noktalarını kullanın. HTTP/2, başlık sıkıştırması ve tek bir bağlantı üzerinden istek/yanıt çoklama gibi özellikler aracılığıyla önemli performans avantajları sağlar. HttpService, mevcut olduğunda otomatik olarak HTTP/2 kullanır. HTTP/2 spesifikasyonu, tüm başlık adlarının küçük harfle gönderilmesini gerektirir.

Gözlemlenebilirlik

Gözlemlenebilirlik Gösterge Paneli, HttpService kullanımınızı izlemek ve sorun gidermek için içgörüler ve analizler sağlar. Gösterge paneli, oyununuzdan gelen HttpService isteklerinin hacmini izleyen İstek Sayısı ve uç noktaların yanıt vermesi için gecikmeyi ölçen Yanıt Süresi olmak üzere iki ana grafik içerir.

Filtreleme ve ayrıştırma için mevcut boyutlar aşağıdaki gibi tanımlanmıştır:

İstek Türü

• GET
• POST
• PUT
• PATCH
• DELETE
• Diğer (belirtilmemiş istek türleri için)

Durum

• Başarı (HTTP 1xx ve 2xx durum kodları)
• Yönlendirme (HTTP 3xx durum kodları)
• 400 (Kötü İstek)
• 401 (Yetkisiz)
• 403 (Yasak)
• 404 (Bulunamadı)
• 429 (Aşırı İstek)
• 500 (Dahili Sunucu Hatası)
• 503 (Hizmet Kullanılamıyor)
• ExternalError (dış hizmetten dönen diğer belirtilmemiş hata kodları)
• InternalError (HttpService içinde Roblox'tan dönen bir sorun)

Yanıt Süresi grafiği, durum verileriyle ilişkilendirilmez. "Durum"u bir ayrıştırma veya filtre olarak seçerseniz, bu grafik veri göstermez.

Ek hususlar

• İstekler, kötü niyetli aktörlerin Roblox sunucularınızdan biri gibi davranmasını engellemek için güvenli bir kimlik doğrulama biçimi sağlamalıdır, örneğin önceden paylaşılan bir gizli anahtar.
• İsteklerin gönderildiği web sunucularının genel kapasite ve hız sınırlama politikalarının farkında olun.