Tek API isteğiyle birden fazla Minecraft sunucusu nasıl sorgulanır?

Bir sunucu seçim ekranında lobi açıkken bir oyun modu yanıt vermeyebilir. Durumları tek tek beklemek yerine herkese açık giriş adreslerini POST /api/v1/status/bulk ile birlikte sorgula. Yanıt, gönderdiğin sırayı korur ve her hedef için ayrı bir status_code verir.

Java ve Bedrock adreslerini aynı isteğe koy

Aşağıdaki örneği status.mjs olarak kaydedip Node.js 22 ile node status.mjs komutunu çalıştır. example.invalid satırı, yanıt vermeyen bir adresin diğer sonuçları engellemediğini görmek için var.

const servers = [
  { address: 'mc.hypixel.net' },
  { address: 'geo.hivebedrock.network', bedrock: true },
  { address: 'example.invalid' },
];

const response = await fetch('https://mcapi.tr/api/v1/status/bulk', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ servers }),
  signal: AbortSignal.timeout(15000),
});

if (response.status === 429) {
  throw new Error('Rate limited. Retry-After: ' + (response.headers.get('Retry-After') ?? 'unknown'));
}
if (!response.ok) throw new Error('HTTP ' + response.status);

const { data } = await response.json();
console.table(data.map(({ address, status_code, data: server }) => ({
  address,
  status: status_code === 200 && server.online
    ? (server.stale ? 'stale' : 'online')
    : (status_code === 404 ? 'unreachable' : 'error'),
  players: server.players?.online ?? null,
})));

Sonuçları doğru yorumla

• Geçerli bir toplu istek HTTP 200 dönebilir ve bir satırın status_code değeri 404 olabilir. Her kartı kendi sonucuyla güncelle.
• stale: true olan satırı son bilinen durum olarak göster. Boş oyuncu sayısı bilinmeyen değerdir.
• Tek istekte 50 hedef gönderebilirsin. Limit IP başına dakikada 6 toplu istektir. Aynı listeyi birçok ziyaretçi görüyorsa sunucu tarafında bir kez sorgulayıp kısa süreli önbellekten dağıt. 429 geldiğinde Retry-After değerini dikkate al.

Velocity veya BungeeCord arkasındaki özel Paper adresleri dışarıdan sorgulanamaz. Genel durum sayfan için oyuncuların kullandığı proxy adreslerini seç. Oyun modlarının ayrı sayımı gerekiyorsa veriyi kendi ağının içinden topla.

Kaynaklar ve ilgili rehberler

• MCAPI API dokümantasyonu
• Oyuncu sayısını web sitesinde gösterme
• Topluluk tartışması (SpigotMC)