Bu sayfa, Open Cloud API'leri ile ilgili yaygın modelleri kapsar, özellikle istekleri işleme ve yanıtlanması konusunda.
Yollar
Açık Bulut API'lerine bir istek göndermek için önce bir URL oluşturmalısınız. Bu URL, Open Cloud API yolunu (örneğin, https://apis.roblox.com/cloud/v2 ) ile bir kombinasyondur. Ayrıca, t
Örneğin üstteki örnek dahil olmak üzere birçok yol, API referansındaki kıvrımlı parçalar tarafından belirlenmiş yol parametreleri vardır. Yol parametreleri, isteği yapmadan önce girilen değişkenlerdir ve neredeyse her zaman ID'lerdir: kullanıcı ID'leri, grubu ID'leri, yeri ID'leri
Bazı kaynakların çok sayıda yol patlası, API referansındaki Yol Kısıtlamaları başlığı altındaki görünür yol patlasıyla görünür. Örneğin, Liste Kullanıcı Sınırları için kullanılan URL, takip edilengibi olabilir:
- 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
İki arasındaki farkı muhtemelen iki arasındaki farkı belirtir: bazı kullanıcı kısıtlamaları bir tüm evren (deneyim) için geçerlidir, diğerleri ise bir evrenin içindeki belirli yerler için geçerlidir. Yol veya ekstra yol parametresine eklenen küçük ekstra eklentiden ayrı olarak, çağrılar aynıdır.
Birçok API, isteği yerine getirmenin bir yolunu olarak bir yolu içerir, which you can use to make further requests. Bir API'nin bir talepyerine getirmesi birkaç saniyeden daha fazla sürmez, genellikle kaynak veya yanıt kendisi değil operasyon olarak döndürür.
İçerik Uzunluğu ve Türü
Kaynaklar oluşturan veya güncellenen API çağrılarının birçoğunda, bir JSON isteği gerekir. Eğer isteğinizin bir vücutu varsa, Content-Length ve Content-Type başlıklarını ekleyin. çoğu HTTP istemcisi bu başlıkları otomatik olarak ekler.
Sayılandırma
Eğer isteğinizde maxPageSize belirtirseniz, bazı yöntemler sayfalı sonuçlar verir - aslında kısıl yanıtlar:
GET /cloud/v2/users/{userId}/inventory-items?maxPageSize=25
{
"inventoryItems": [
...
],
"nextPageToken": "aaaBBB"
}
Bir yanıt nextPageToken değerini içeriyorsa, sonraki istek içindeki pageToken parçında bu değeri kullanın. nextPageToken boşsa sonuçlarınız sona ermiştir:
GET /cloud/v2/users/{userId}/inventory-items?maxPageSize=25&pageToken=aaaBBB
{
"inventoryItems": [
...
],
"nextPageToken": ""
}
Sayfa boyutlandırması için aynı sorguyu kullanmalısınız. Herhangi bir filtre parametresini değiştirerek 400 hata oluşur.
Uzun Süreli İşlemler
Bazı yöntemler, çok yavaş bir yanıt içeren uzun süreli bir istek temsil eden bir Operation nesneyi döndürür. Objeden aşağıdaki alanlar içerir:
- yol - İstek tamamlanması için çağırılan yol. Yolu kaynağın metodu URL'sine bağla.
- done - Operasyonun tamamlandığını veya tamamlanmadığını temsil eden bir boBoolean değeri.
- yanıt - Yanıt nesnesi. Bu alan done alanına bir değer olmadan boştur.
- metadatenetkesi - İstek edilen isteğe özel metadatenetkesi.
Örnek Operasyon Obesi
{
"path": "v1/assets/12345/operation/xyz",
"done": true,
"response": {
"value1": "myValue",
"value2": 1234
},
"metadata": {
"metadata1": "string",
"metadata2": 5678
}
}
Kaynağın hazır olduğunda oy vermek için Operation nesnelerin yolunu kullanın. İyi bir strateji, bir yıldırım geri alıcı kullanmaktır. Örneğin, derhal, sonra bir saniye, iki saniye, dört saniye vb.
def PollForResults(operationPath):
currentRetries = 0
maxRetries = 10
retryPollingDelay = 1
retryPollingMultiplier = 2
while (currentRetries < maxRetries):
# İlk kontrol etiçin gecikme yok
if (currentRetries == 0):
results = GetOperation(operationPath)
# Sonraki kontroller için mantığı tekrar deneyin
else:
time.sleep(retryPollingDelay)
results = GetOperation(operationPath)
# Exponential backof
retryPollingDelay *= retryPollingMultiplier
# Sonuçları kontrol edin ve mevcutsa dönün
if (results.status_code != 200 or results.json()[doneJSONKey]):
return results
# Aksi takdirde, deneyin sayısını artırın
else:
currentRetries += 1
Exponential backoff yerine sabit bir deneme aralığı kullanan daha geniş bir kod örneği için, Sonuçlar için Oylama bakın.
Sıralama
Bazı yöntemler, isteğe bir filter parametresi ekleyerek talepfiltrelemene izin verir. Aşağıdaki bölümler, belirlenen sonuçlar için filtreleme kılavuzu ve kurallarını açıklar.
Liste Grubu Üyelikleri
Dizinlemeye katılımlar arasında grup kimliği listesini oluşturmak için wildcard karakteri - kullanılabilir: groups/-/memberships .
Filtreleme CommonExpressionLanguage (CEL) uyumludur. Sadece iki operatör desteklenir:
- ==
- in [...]
Kaynak yolunda bir grup ID'si belirtirseniz, üyelikleri aşağıdaki biçimlerden herhangi biriyle filtreleyebilirsiniz:
- Kullanıcı filtresi : filter="user == 'users/9876543210'"
- Rol süzgeci : filter="role == 'groups/123/roles/7920705''>
Grup ID'si için vahşi karakteri belirtirseniz, aşağıdaki biçimde üyelikleri kullanıcı (en fazla 50) olarak filtrelemelisiniz:
- Kullanıcı filtresi : filter="user in ['users/1', 'users/156', 'users/9876543210', ...]"
Envanter Öğeleri Listesi
Koleksiyonlara göre, envanter öğesi yazve envanter öğesi ID'sine göre filtreleyebilirsiniz. Eğer bir filtre sağlamazsanız, kullanıcının tüm envanteri iade edilir.
Filtre formatı semikolon ayrıklı bir listedir:
filter={field}={value};{field}={value},{value},...;{field}=...
- {field} önceden tanımlanmış herhangi bir tür alanı veya kimlik alanından herhangi biri olabilir.
- {value} bir yuva, bir boole veya bir열 olabilir. Alan yazbağlı olarak, bu tek bir değer (boole alanları) veya çok değer (liste alanları) olabilir.
Aynı filtrede tür ve kimlik alanlarını birleştiremezsiniz.
Türleri Alanlar
| Filtre | Tür | Açıklama - | | :
Kimlik Alanları
| Filtre | Tipe | Açıklama | | | : | | :
Örnekler
Kullanıcının sahip olduğu tüm toplayıcı öğeleri iade eder:
filter=onlyCollectibles=true;inventoryItemAssetTypes=*
Belirlenen tüm türlerin öğelerini iade eder:
filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY
Listelenen tüm türlerin veya oyun kartlarının tüm öğelerini içerir. Filtrede dahil edilmeyen başarımları gösterir (同じ行为，如果 badges filtre):
filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY;gamePasses=true;badges=false
Belirlenen ID'lerle eşleşen kaynakları iade eder:
filter=assetIds=1,2,3,4
Belirli kimliklere uyan kaynakları, rozetleri, oyun kartlarını ve özel sunucuları içerir:
filter=assetIds=1,2,3,4;badgeIds=1,2,3,4;gamePassIds=1,2,3,4;privateServerIds=1,2,3,4