Sorgu maliyetini ve throttle durumunu okuma
Her Admin API yanıtı, maliyetini ve kalan kotayı extensions.cost içinde bildirir. Bunu istekleri dengelemek ve THROTTLED hatalarını yönetmek için kullanın.
- API
- Admin GraphQL API
- Nerede
- Her yanıttaki extensions.cost
- Geri dolum hızı
- Standard 100 puan/sn, Advanced 200, Plus 1.000, Commerce Components 2.000
- Yerini aldığı REST çağrısı
- X-Shopify-Shop-Api-Call-Limit başlığı
- API sürümü
- 2026-10
- Son kontrol
Kısaca
Admin GraphQL API uygulamaları istek sayısıyla değil sorgu maliyetiyle sınırlar. Her yanıtta requestedQueryCost, actualQueryCost ve throttleStatus (maximumAvailable, currentlyAvailable, restoreRate) içeren extensions.cost bulunur. Bir sonraki sorgudan önce currentlyAvailable’ın maliyetini karşıladığını kontrol edin; karşılamıyorsa kovanın saniyede restoreRate puan hızla dolmasını bekleyin. Tek bir sorgu 1.000 puanı geçemez.
Nasıl kullanılır
- Her yanıttan extensions.cost’u okuyun; istenen maliyet sorgu çalışmadan önce ayrılır, kullanılmayan kısım iade edilir.
- Bir sonraki istekten önce beklenen maliyetini currentlyAvailable ile karşılaştırın ve gerekiyorsa bekleyin (wait-for-budget.js).
- THROTTLED hatasında bekleyip aynı isteği tekrar deneyin; Shopify en az bir saniye beklemeyi önerir.
- Her alanın maliyete ne kadar eklediğini görmek için Shopify-GraphQL-Cost-Debug: 1 başlığını gönderin.
Kod
products-with-cost.graphqlquery RecentProducts($first: Int!) {
products(first: $first, sortKey: UPDATED_AT, reverse: true) {
nodes {
id
title
variants(first: 5) {
nodes {
id
sku
}
}
}
}
}
products-with-cost.variables.json{
"first": 50
}
products-with-cost.response.json{
"data": {
"products": {
"nodes": [
{
"id": "gid://shopify/Product/1234567890",
"title": "Linen shirt",
"variants": {
"nodes": [
{"id": "gid://shopify/ProductVariant/1111111111", "sku": "LS-S"}
]
}
}
]
}
},
"extensions": {
"cost": {
"requestedQueryCost": 302,
"actualQueryCost": 14,
"throttleStatus": {
"maximumAvailable": 2000.0,
"currentlyAvailable": 1986,
"restoreRate": 100.0
}
}
}
}
throttled.json{
"errors": [
{
"message": "Throttled",
"extensions": {
"code": "THROTTLED",
"documentation": "https://shopify.dev/api/usage/limits#rate-limits"
}
}
],
"extensions": {
"cost": {
"requestedQueryCost": 302,
"actualQueryCost": null,
"throttleStatus": {
"maximumAvailable": 2000.0,
"currentlyAvailable": 120,
"restoreRate": 100.0
}
}
}
}
wait-for-budget.js// Waits until the bucket has room for the next query, using the throttle
// status Shopify returns in extensions.cost of every Admin API response.
const MS_PER_SECOND = 1000;
/** Milliseconds to wait before a query that will request `nextCost` points. */
export function waitBeforeNext(cost, nextCost) {
const {currentlyAvailable, restoreRate} = cost.throttleStatus;
if (currentlyAvailable >= nextCost) return 0;
return Math.ceil(((nextCost - currentlyAvailable) / restoreRate) * MS_PER_SECOND);
}
/** True when the response failed only because the bucket was empty. */
export function isThrottled(body) {
return Array.isArray(body.errors) && body.errors.some((e) => e.extensions?.code === 'THROTTLED');
}
Lintel tarafından yazıldı. MIT lisansı: kendi mağazanızda da müşteri işlerinizde de ücretsiz kullanabilirsiniz.
Sınırlar ve özel durumlar
- Varsayılan maliyetler: skaler ve enum 0, nesne 1, mutation 10, bağlantılar first ya da last’a göre. Shopify bazı alanlara farklı maliyet atayabilir.
- İstenen maliyet sayfaların dolu geleceğini varsayar. Daha küçük first değerleri ve daha az iç içe bağlantı maliyeti en çok düşürür.
- İstenen maliyeti 1.000 puanı aşan bir sorgu, çalışmadan MAX_COST_EXCEEDED ile başarısız olur. Sorguyu bölün ya da bulk operation kullanın.
- Sınırlar uygulama ve mağaza bazındadır: başka uygulamalar sizin kotanızı tüketmez.
- Girdi dizileri tüm Shopify API’lerinde en fazla 250 öğe olabilir.
Sık sorulan sorular
- Shopify GraphQL istek sınırı nedir?
- Maliyete dayalıdır: Standard planlarda saniyede 100 puan, Advanced’de 200, Plus’ta 1.000 ve Commerce Components’ta 2.000; sorgu başına en fazla 1.000 puan.
- THROTTLED hatalarından nasıl kaçınırım?
- Yalnızca ihtiyacınız olan alanları ve sayfa boyutlarını isteyin, currentlyAvailable’ı takip edip azaldığında bekleyin, büyük okuma ve yazmaları bulk operation’a taşıyın.
- İstenen maliyet neden gerçek maliyetten yüksek?
- İstenen maliyet her bağlantının dolu bir sayfa döndüreceğini varsayar. Gerçek maliyet dönen veriyi sayar; aradaki fark kotanıza iade edilir.
Shopify belgeleri
- Gösterilen tarihte, 2026-10 sürümünün Admin veya Storefront API şemasıyla doğrulandı. İstek adresinizdeki sürümü kontrol edin.
- Örneklerdeki ID’ler ve mağaza adresleri yer tutucudur. Kendi değerlerinizle değiştirin.
- Admin API çağrıları uygulamanızdan bir erişim anahtarı (access token) ister. Admin API anahtarını asla vitrine ya da temaya koymayın.
- MIT lisansı. Kodu kendi mağazanızda da müşteri işlerinizde de kullanabilirsiniz.
Mağazanız için kurulmasını, test edilmesini ve bakımını isterseniz: API entegrasyonları.
