Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Sayfalama

Bu sayfa, liste döndüren uçların sayfalarını nasıl gezeceğinizi anlatır. Open Play’de tek bir sayfalama biçimi yoktur: çoğu uç opak imleç (cursor) kullanır, birkaç uç ise farklı bir yöntem kullanır. Aşağıdaki tablo hangi uçta hangisinin geçerli olduğunu ve sayfa boyutu sınırlarını gösterir.

İmleç (keyset) sayfalama

Çekirdek liste uçlarının çoğu imleç tabanlıdır:

  • İstek: ?limit=<n>&cursor=<imleç>. İlk sayfada cursor vermezsiniz.
  • Yanıt: {"items":[…],"next_cursor":"…"}. next_cursor null ise son sayfadasınız.
  • Sonraki sayfa: cursor olarak bir önceki yanıttaki next_cursor değerini aynen verin.
  • İmleç opaktır: içeriğini ayrıştırmayın, değiştirmeyin, saklayıp uzun süre sonra kullanmayı varsaymayın. Bozuk imleç 400 alır.
  • Sıralama sabittir ve OFFSET kullanılmaz; sayfalar arasında yeni kayıt eklenirse atlama ya da tekrar oluşmaz (kayıtlar sabit anahtara göre sıralanır).
  • Sayfa boyutu limit ile verilir; sınırların dışındaki değer çoğu uçta kısılır (hata vermez). İstisnalar tabloda belirtilmiştir.
GET /v1/characters?limit=2 HTTP/1.1
Authorization: Bearer crx_live_<önek>_<gizli>

{"items":[{"id":"…","definition":"hero","version":3}],"next_cursor":"<opak-imleç>"}

GET /v1/characters?limit=2&cursor=<opak-imleç> HTTP/1.1
Authorization: Bearer crx_live_<önek>_<gizli>

Uca göre biçimler

UçBiçimVarsayılanSınır
GET /v1/charactersİmleç (definition süzgeci)501 ile 200 arası kısılır
GET /v1/characters/{id}/events, …/timelineİmleç (artan seq)501 ile 200 arası kısılır
GET /v1/rules, GET /v1/webhooksİmleç501 ile 200 arası kısılır
GET /v1/ledgerİmleç (wallet_id zorunlu)501 ile 200 arası kısılır
GET /v1/items, GET /v1/player/itemsİmleç (owner ile)501 ile 200 arası kısılır
GET /v1/assetsİmleç50 (0 ya da yok = varsayılan)en çok 200
GET /v1/catalog/items, GET /v1/catalog/charactersİmleç501 ile 100 arası kısılır
GET /v1/notificationsİmleç (status, limit, cursor)501 ile 100 arası kısılır
GET /v1/leaderboards/{key}/entriesİmleç20 (0 ya da yok = varsayılan)en çok 100; fazlası 400 (kısılmaz)
GET /v1/leaderboards/{key}/around-meOyuncu çevresi (player_id, radius)—Sayfa yok; çevre pencereleri sınırlıdır
GET /v1/player/leaderboards/{key}Tek sayfa (limit)201 ile 50; dışı 400
GET /v1/chat/channels/{channel_id}/messagesZaman tabanlı (before_ms + limit)501 ile 100 (service doğrular)
GET /v1/questsoffset + limit (search süzgeci)20 (0 ya da yok = varsayılan)limit en çok 100, offset en çok 100000; fazlası 400
GET /v1/auth/admin/list-playersİmleç (UUID)uç varsayılanıUca özgü
GET /v1/clans, GET /v1/partiesSayfalama yok; tüm sonuç (parti için player_id süzgeci)——
GET /v1/wallets, GET /v1/inventories/{owner}Sayfalama yok (sahibe göre tüm liste)——
Eklenti sorguları (/v1/plugins/…/queries/…)Eklentiye özgü; girdi şemasında tanımlıdır—Eklentinin şema belgesi

Not

Yanıtta imleç alanı çekirdek REST’te next_cursor (yılan_harf) olarak gelir. Sohbet mesajlarında yeni sayfa için en eski mesajın sent_at_ms değerini before_ms olarak verirsiniz. Panel API’lerinin sayfalaması (offset/ızgara) panel arayüzünün iç kullanımıdır ve bu dokümanın kapsamında değildir.

SDK’da sayfalama

TypeScript SDK’sı imleçli listeler için yineleyiciler sunar: iterateListCharacterEvents, iterateGetCharacterTimeline, iterateListRules, iterateListWebhooks. Bu yineleyiciler next_cursor’ı sizin yerinize izler. Önemli kurallar:

  • İmleç opaktır; yineleyici onu çevirmeden geri verir.
  • Boş next_cursor döngüyü bitirir; imleç döngüsü (aynı imlecin tekrar gelmesi) ya da maxPages aşımı sessiz kesme değil, pagination türünde hatadır.
  • limit tel üzerinde u32’dir; sunucu 1 ile 200 aralığına kısar.

Örüntüler

Hepsini gezmek (sunucudan sunucuya iş): imleç boş gelene kadar döngü kurun; her sayfada kısa bir üst sınır (ör. en çok 1000 sayfa) koyun.

cursor = yok
tekrarla:
    sayfa = GET /v1/rules?limit=200[&cursor=cursor]
    sayfa.items işlenir
    cursor = sayfa.next_cursor
    cursor boşsa dur

Oyun içi “daha fazla yükle” listesi: küçük limit (20 ile 50) kullanın, next_cursor’ı bellekte tutun, kullanıcı kaydırdıkça bir sonraki sayfayı isteyin. İmleci kalıcı saklamayın.

Tutarlılık: imleçli sayfalar canlı veriyi gezer; gezerken eklenen yeni kayıtlar, imlecin gerisinde kalıyorsa görünmeyebilir. Anlık görüntü gerektiren raporlar için sorgu zamanını (örneğin as of) kendi tarafınızda kaydedin.

İlgili: uç noktalar, hız sınırları.