Kalıpler

Bu sayfa, özellikle istek göndermek ve yanıtları işlemek ile ilgili yaygın kalıpları Open Cloud API'leri ile kapsar.

Yollar

Açık Bulut API'lerine bir istek göndermek için önce bir URL oluşturmalısınız.Bu URL, temel URL'nin ( https://apis.roblox.com/cloud/v2 ), Açık Bulut API yolunun (örneğin, /universes/{universe_id}/places/{place_id}/user-restrictions) ve herhangi bir sorgu parametrinin bir kombinasyonudur (örneğin, ?maxPageSize=25 ).Tam bir istek URL'si şöyle görünebilir:


https://apis.roblox.com/cloud/v2/users/4687549151/inventory-items?maxPageSize=100

Yukarıdaki örnek dahil birçok yol, API referansındaki tırtıllı parantezler tarafından belirlenen yol parametlerine sahiptir.Yol parametleri, istek yapmadan önce eklediğiniz sadece değişkenlerdir ve neredeyse daima kimliklerdir: kullanıcı kimlikleri, grup kimlikleri, yer kimlikleri vb.Kimlikler genellikle sayısal olsa da, mutlaka değil; örneğin, veri depolama ve hafıza depolama kimlikleri daha geniş bir karakter ayarladestekler.

Bazı kaynakların çok sayıda yol modeli vardır ve API referansındaki Kaynak Yolları başlığı altında görülebilir.Örneğin, Kullanıcı Sınırlarını Listeleme URL'si takip edilenbiri 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

Muhtemelen iki arasındaki farkı tahmin edebilirsiniz: bazı kullanıcı kısıtlamaları bir evrenin (deneyimin) tümüne uygulanırken, diğerleri bir evrenin belirli yerlerine uygulanır.Yol ve ekstra yol parametresine yapılan küçük eklemlerin yanı sıra, çağrılar aynıdır.

Birçok API, yanıtın bir parçası olarak bir yol döndürür, ki bunu daha fazla istek göndermek için kullanabilirsiniz.Bir API, bir talepyerine getirmek için birkaç saniyeden fazla süre gerektiriyorsa, genellikle kaynak veya yanıtın kendisi yerine bir operasyonu döndürür.

İçerik uzunluğu ve yaz

Birçok API çağrısı, özellikle kaynakları oluşturan veya güncelleyenler, bir JSON istek vücutgerektirir.Talebiniz bir vücutiçeriyorsa, Content-Length ve Content-Type başlıklarını dahil ettiğinizden emin olun.Çoğu HTTP istemcisi bu başlıkları otomatik olarak ekler.

Sayfa Düzeni

talepmaxPageSize belirtirseniz, bazı yöntemler sayfalı sonuçlar döndürür - temelde kısmi yanıtlar:


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"
}

Bir yanıt nextPageToken için bir değer içeriyorsa, bir sonraki istekte bir sonraki sayfayı almak için bu değeri pageToken parametresinde kullanın.nextPageToken boş veya tamamen atlanırsa, sonuçlarınızın sonuna ulaştınız:


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": [
    ...
  ]
}

pageToken dışında, sayfa düzgün çalışması için aynı sorguyu kullanmalısınız. Herhangi bir filtre parametresinin değiştirilmesi 400 hatasına neden olur.

Uzun süren işlemler

Bazı yöntemler, daha sonra asenkron bir yanıt döndüren uzun süren bir isteği temsil eden bir Operation nesnesi döndürür.Nesne aşağıdaki alanları içerir:

yol - İstek tamamlanması için oylama yapmak için son nokta yolunu ekleyin kaynak yönteminin orijinal URL'sine.
tamamlandı - Operasyonun bitip bitmediğini temsil eden bir mantık değeri
yanıt - Yanıt nesnesi. Bu alan alanına sahip olana kadar boş.
meta veri - Yapılan isteğe özel özel metin veri.

Örnek Operasyon Nesnesi
{
  "path": "v1/assets/12345/operation/xyz",
  "done": true,
  "response": {
    "value1": "myValue",
    "value2": 1234
  },
  "metadata": {
    "metadata1": "string",
    "metadata2": 5678
  }
}

Kaynak hazır olduğunda oylamak için Operation nesnenin yolunu kullanın.İyi bir strateji, üstel geri çekmeyi kullanmaktır.Örneğin, hemen anket yapabilirsiniz, ardından bir saniye, iki saniye, dört saniye vb.


def PollForResults(operationPath):
    currentRetries = 0
    maxRetries = 10
    retryPollingDelay = 1
    retryPollingMultiplier = 2
    while (currentRetries < maxRetries):
        # İlk kontrol etgecikme yok
        if (currentRetries == 0):
            results = GetOperation(operationPath)
        # Sonraki kontroller için mantığı yeniden deneyin
        else:
            time.sleep(retryPollingDelay)
            results = GetOperation(operationPath)
            # Üstel geri çekilme
            retryPollingDelay *= retryPollingMultiplier
        # Sonuçları kontrol edin ve varsa geri dönün
        if (results.status_code != 200 or results.json()[doneJSONKey]):
            return results
        # Aksi takdirde, yeniden deneme sayısını artır
        else:
           currentRetries += 1

Exponential backoff yerine sabit bir yeniden deneme süresi kullanan daha kapsamlı bir kod örneği için, Sonuçlar için oy verin bakın.

Süzme

Bazı yöntemler, isteğe bir filter parametresi ekleyerek talepfiltrelemenizi sağlar.Aşağıdaki bölümler, belirtilen son noktalar için filtre sözdizimi ve yönergelerini açıklar.

Grup üyeliklerini listele

Vahşi karakter - , tüm gruplardaki üyelikleri listelemek için grup kimliğinin yerine kullanılabilir: groups/-/memberships .

Filtreleme, Sıradan İfade Dili'ne (CEL) uyuyor. Sadece iki operatör destekleniyor:

==
in [...]

Kaynak yolunda bir grup kimliği belirtirseniz, üyelikleri aşağıdaki formatlardan biriyle kullanıcı veya rol tarafından filtreleyebilirsiniz:

Kullanıcı filtresi : filter="user == 'users/9876543210'"
Rol filtresi : filter="role == 'groups/123/roles/7920705'"

Grup kimliği için joker karakterini belirttiyseniz, üyelikleri aşağıdaki formatla kullanıcıya göre filtrelemelisiniz (en fazla 50):

Kullanıcı filtresi : filter="user in ['users/1', 'users/156', 'users/9876543210', ...]"

Envanter öğelerini listele

Koleksiyon durumu, envanter öğe yazve envanter öğesi ID'si ile filtreleyebilirsiniz.Bir filtre sağlamazsanız, kullanıcının tüm envanteri iade edilir.

Filtre biçimi virgülle ayrılmış bir listedir:

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

{field} aşağıdaki tablolardaki önceden tanımlanmış tür alanları veya kimlik alanlarından herhangi biri olabilir.
{value} bir dizi, mantık veya sayısal olabilir.Alan yazbağlı olarak, bu tek bir değer (booleen alanlar) veya çok sayıda değer ( listed alanlar) olabilir.

Aynı filtrede tür ve kimlik alanlarını birleştiremezsiniz.

Alanları yaz

| Filtre | Tür | Açıklama | | :------------------------ | :------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | badges | boolean | Yanıtlara rozetler ekleyin.Varsayılan değer yoktur. | | gamePasses | boolean | Yanıtın içine oyun geçişleri dahil edin.Varsayılan değer yoktur. | | inventoryItemAssetTypes | Bütün varlık türlerinin tam listesi için varlıkDetayları görün.| Dahil edilecek aset türlerinin virgülle ayrılmış listesi.Varsayılan değer yoktur.Tüm varlık türleri için * belirtin.Satın alınan yerler tarafından filtrelenmek için Envanter okuma alanına sahip olmalıdır. | | onlyCollectibles | boolean | Yanıtın içine sadece toplama nesneleri dahil edin.Varsayılan değer yoktur.Bu alan, öğeleri döndürmek ve sadece UGC sınırlı öğeleri döndürmek için inventoryItemAssetTypes alanıyla birlikte kullanılmalıdır ve sadece UGC sınırlı öğeleri döndürür.| | privateServers | boolean | Yanıta özel sunucuları dahil edin.Varsayılan değer yoktur.Bu alanla filtreleme yapmak için Envanter okuma alanına sahip olmalıdır. |

Kimlik alanları

Örnekler

Kullanıcının sahip olduğu tüm koleksiyon öğelerini döndürür:

filter=onlyCollectibles=true;inventoryItemAssetTypes=*
Belirtilen türlerin tüm öğelerini döndürür:

filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY
Listelenen türlerin veya herhangi bir oyun geçişinin tüm öğelerini döndürür.Sonuçlardan rozetleri dışlar (filtreye dahil edilmediği gibi aynı davranış):

filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY;gamePasses=true;badges=false
Belirtilen kimliklere uyan varlıkları döndürür:

filter=assetIds=1,2,3,4
Belirtilen kimliklere uyan varlıklar, başarımlar, oyun geçişleri ve özel sunucuları iade eder:

filter=assetIds=1,2,3,4;badgeIds=1,2,3,4;gamePassIds=1,2,3,4;privateServerIds=1,2,3,4

Bu sayfadakiler