Modeller

Bu sayfa, Open Cloud API'leri ile ilgili istek yapma ve yanıtları ele alma konusundaki yaygın modelleri ele alır.

Yollar

Open Cloud API'lerine bir istek yapmak için öncelikle bir URL oluşturmalısınız. Bu URL, temel URL (örneğin, https://apis.roblox.com), Open Cloud API yolu (örneğin, /cloud/v2/universes/{universe_id}/places/{place_id}/user-restrictions) ve herhangi bir sorgu parametresinin (örneğin, ?maxPageSize=25) bir kombinasyonudur. 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ında süslü parantezlerle belirtilen yol parametrelerine sahiptir. Yol parametreleri, isteği yapmadan önce yerleştirdiğiniz değişkenlerdir ve çoğunlukla ID'lerdir: kullanıcı ID'leri, grup ID'leri, mekan ID'leri vb. ID'ler genellikle sayısaldır, ancak mutlaka öyle olmayabilir; örneğin, veri deposu ve bellek deposu ID'leri daha geniş bir karakter kümesini destekler.

İçerik uzunluğu ve türü

Birçok API çağrısı, özellikle oluşturma veya güncelleme işlemleri, bir JSON istek gövdesi gerektirir. Eğer isteğinizin bir gövdesi varsa, 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.

Sayfalandırma

Eğer isteğinizde maxPageSize belirttiyseniz, bazı yöntemler sayfalı sonuçlar döner—esasen 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, o değeri bir sonraki istekte pageToken parametresi olarak kullanın. nextPageToken boş veya tamamen atlanmış olduğunda, sonuçlarınızın sonuna ulaşmışsınız demektir:

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, sayfalama düzgün çalışması için aynı sorguyu kullanmalısınız. Herhangi bir filtre parametresini değiştirmeniz durumunda 400 hatası alırsınız.

Open Cloud v2

Birden fazla yol

Bazı kaynaklar, API referansında Kaynak Yolları başlığı altında görünen birden fazla yol modeline sahiptir. Örneğin, Kullanıcı Kısıtlamalarını Listele için URL, şu iki şekilde de 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

İkisi arasındaki farkı muhtemelen çıkarabilirsiniz: bazı kullanıcı kısıtlamaları tüm bir evrene (oyun) uygulanırken, diğerleri bir evrenin içindeki belirli mekanlara uygulanır. Yola eklenen küçük bir ek ve ekstra yol parametresi dışında, talepler aynıdır.

Birçok uç nokta, yanıtlarının bir parçası olarak bir yol döner; bu yolu daha fazla istek yapmak için kullanabilirsiniz. Eğer bir API, bir isteği yerine getirmesi için birkaç saniyeden fazla süre alıyorsa, genellikle kaynak veya yanıtın kendisi yerine bir işlem döner.

Uzun süreli işlemler

Bazı yöntemler, daha sonra asenkron bir yanıt dönecek uzun süreli bir isteği temsil eden bir Operation nesnesi döner. Bu nesne aşağıdaki alanları içerir:

• path - İsteğin tamamlanmasını kontrol etmek için çağrılacak uç nokta yolu. Yolu, kaynağın yönteminin orijinal temel URL'sine ekleyin.
• done - İşlemin tamamlanıp tamamlanmadığını temsil eden bir boolean değeri.
• response - Yanıt nesnesi. Bu alan, done alanının değeri true olana kadar boştur.
• metadata - Yapılan isteğe özel özel meta veri.

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

Kaynağın hazır olduğu zamanları kontrol etmek için Operation nesnesinin yolunu kullanın. İyi bir strateji, üssel geri yükleme kullanmaktır. Örneğin, hemen güncelleme yapabilir, sonra bir saniye, iki saniye, dört saniye vb. bekleyebilirsiniz.

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

Sabit bir tekrar aralığı kullanan daha kapsamlı bir kod örneği için Sonuçları kontrol et sayfasına bakın.

Filtreleme

Bazı yöntemler, istekte bir filter parametresi ekleyerek yanıtı filtrelemenize olanak tanır. Aşağıdaki bölümler, belirtilen uç noktalar için filtre sözdizimini ve kılavuzlarını tanımlar.

Grup üyeliklerini listele

Grup ID'si yerine wildcard karakteri - kullanılarak tüm gruplardaki üyeliklerin listesi elde edilebilir: groups/-/memberships.

Filtreleme, Common Expression Language (CEL) standartlarına uyar. Sadece iki operatör desteklenir:

• ==
• in [...]

Eğer kaynak yolunda bir grup ID'si belirttiyseniz, üyelikleri kullanıcıya veya role göre aşağıdaki formatlarda filtreleyebilirsiniz:

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

Eğer grup ID'si için wildcard karakterini belirttiyseniz, üyelikleri kullanıcıya (50'ye kadar) aşağıdaki formatta filtrelemeniz gereklidir:

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

Envanter öğelerini listele

Koleksiyon durumu, envanter öğesi türü ve envanter öğesi ID'sine göre filtreleme yapabilirsiniz. Eğer bir filtre sağlamazsanız, kullanıcının tüm envanteri döner.

Filtre formatı, noktalı virgülle ayrılmış bir listedir:

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

• {field}, aşağıdaki tablolarda önceden tanımlanmış tür alanlarından veya ID alanlarından biri olabilir.
• {value}, bir dize, boolean veya enum olabilir. Alan türüne bağlı olarak, bu tek bir değer (boolean alanlar) veya birden fazla değer (liste alanları) olabilir.

Tür alanları

ID Alanları

Örnekler

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

  filter=onlyCollectibles=true;inventoryItemAssetTypes=*

• Belirtilen türlerdeki tüm öğeleri döndürür:

  filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY

• Listelenen türlerden veya herhangi bir oyun geçişinden tüm öğeleri döndürür. Sonuçlardan rozetleri hariç tutar (filtrede badges dahil edilmediği gibi davranır):

  filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY;gamePasses=true;badges=false

• Belirtilen ID'lerle eşleşen varlıkları döndürür:

  filter=assetIds=1,2,3,4

• Belirtilen ID'lerle eşleşen varlıkları, rozetleri, oyun geçişlerini ve özel sunucuları döndürür:

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