Microsoft Fabric REST API'leri ile ilgili sorunları giderme

Giriş

Bu makale, Microsoft Fabric REST API'leri tarafından döndürülen yaygın hataları anlamanıza ve gidermenize yardımcı olur. Hizmet tarafından kullanılan standart hata biçimini açıklar ve en sık karşılaşılan HTTP durum kodlarını çözümlemek için rehberlik sağlar.

Microsoft Fabric Hata Yanıtlarını Anlama

Microsoft Fabric REST API'sine yönelik bir istek işlenirken bir hata oluştuğunda, hizmet yanıt gövdesinde standart ErrorResponse bir nesne döndürür.

Sorun giderme sırasında, isteği benzersiz olarak tanımladığı ve Microsoft desteğine başvururken gerekli olduğu için her zaman requestId öğesini yakalayın ve günlüğe kaydedin. İstek kimliği hem yanıt gövdesinde hem de yanıt üst bilgilerinde kullanılabilir.

Önemli

• errorCode değerleri kararlı ve sözleşme tabanlıdır.
• İnsan tarafından okunabilen message metin zaman içinde değişebilir ve program aracılığıyla ayrıştırılmamalıdır.

ErrorResponse şeması

İsim	Türü	Description
errorCode	string	Hata koşulu için kararlı bir tanımlayıcı. Hata işleme mantığını uygularken bu değeri kullanın.
message	string	Hatanın insan tarafından okunabilen açıklaması.
moreDetails	ErrorResponseDetails[]	ek hata ayrıntılarının isteğe bağlı listesi.
relatedResource	ErrorRelatedResource	Varsa hatayla ilişkili kaynakla ilgili bilgiler.
requestId	string	Başarısız isteğin benzersiz tanımlayıcısı. Microsoft desteğine başvururken bu değeri ekleyin.

ErrorResponseDetails şeması

Karmaşık hata senaryoları için ek bağlam sağlar.

İsim	Türü	Description
errorCode	string	Belirli hata ayrıntılarını açıklayan kararlı bir tanımlayıcı.
message	string	Hata ayrıntılarının insan tarafından okunabilir bir açıklaması.
relatedResource	ErrorRelatedResource	Bu özel hata ayrıntısıyla ilişkili kaynak.

ErrorRelatedResource şeması

Hataya dahil olan kaynağı tanımlar.

İsim	Türü	Description
resourceId	string	Hataya dahil olan kaynağın kimliği.
resourceType	string	Kaynağın türü (örneğin, çalışma alanı, öğe veya kapasite).

Yaygın HTTP hata senaryoları

Aşağıdaki bölümlerde, Tipik kök nedenler ve önerilen çözümlerin yanı sıra Microsoft Fabric REST API'leri tarafından döndürülen yaygın HTTP durum kodları açıklanmaktadır.

API 401 – Yetkisiz döndürür

401 yanıtı, isteğin kimlik doğrulaması veya erişim belirteci doğrulaması sırasında başarısız olduğunu gösterir.

Yaygın kök nedenler

Hata kodu	Description	Çözüm
TokenExpired	Erişim belirtecinin süresi doldu.	Yeni bir erişim belirteci alın ve isteği yeniden deneyin.
InsufficientScopes	Erişim belirteci gerekli kapsamları içermez.	API belirtiminde belirtildiği gibi gerekli kapsamları istemek için uygulamayı güncelleştirin veya Microsoft Entra uygulama kaydını güncelleştirin.

API 403 – Yasak değerini döndürür

403 yanıtı, çağıranın kimliğinin doğrulandığını ancak hedef kaynakta istenen işlemi gerçekleştirmek için yeterli izinlere sahip olmadığını gösterir.

Yaygın kök nedenler

Hata kodu	Description	Çözüm
InsufficientPrivileges	Çağıranın kaynağa erişmek için gerekli izinleri yok.	Bir çalışma alanı veya kaynak yöneticisinden çağıran kullanıcıya veya hizmet sorumlusuna yeterli izinleri vermesini isteyin.

API 404 – Bulunamadı sonucunu döndürür

404 yanıtı, istenen veya başvuruda bulunılan bir kaynağın mevcut olmadığını veya çağıranın erişemediğini belirtir.

Not

Tek tek API'ler API'ye özgü ek hata kodları tanımlayabilir. Yetkili ayrıntılar için her zaman API belirtimine bakın.

Yaygın kök nedenler

Hata kodu	Description	Çözüm
WorkspaceNotFound	Belirtilen çalışma alanı bulunamadı.	Doğru çalışma alanı nesne kimliğinin sağlandığını doğrulayın.
EntityNotFound	İstenen kaynak bulunamadı.	Doğru kaynak kimliğinin sağlandığını onaylayın. Eksik varlık, hata yanıtı alanında relatedResource tanımlanır.

API 429 – Çok Fazla İstek döndürüyor

429 yanıtı, isteğin kısıtlandığını gösterir. Microsoft Fabric, her biri yanıt gövdesinde farklı bir errorCode ile tanımlanan iki ayrı nedenle 429 durum kodu döndürür.

Yaygın kök nedenler

Hata kodu	Description	Çözüm
RequestBlocked	İstek oranı, hizmet için belirlenen hız sınırlama limitlerini aştı.	Yeniden denemeden önce üst bilgide Retry-After belirtilen süreyi bekleyin. Bkz . Uygulamanızda hız sınırlamayı işleme.
CapacityLimitExceeded	Kapasitenizde tüketilen işlem gücü (kapasite birimleri), satın aldığınız Fabric SKU’sunun sınırlarını aştı.	İsteği daha sonra yeniden deneyin. Bkz. Kapasite kısıtlamasını yönetme.

Hız sınırlama (RequestBlocked)

RequestBlocked hatası, istek oranının hizmetin hız sınırlama limitlerini aştığını gösterir.

• Sınırlama, arayan kimliğine göre uygulanır.
• Hız sınırları genellikle bir dakikalık pencereler üzerinden değerlendirilir.

Zamanlama bilgilerini yeniden deneyin

Hız sınırlama gerçekleştiğinde, yeniden deneme bilgileri iki konumda sağlanır:

• Yanıt gövdesi (message)
  Örnek:
  "Request is blocked by the upstream service until: 12/24/2025 17:02:20 (UTC)"

• Retry-After HTTP yanıt üst bilgisi
  İstemcinin yeniden denemeden önce beklemesi gereken saniye sayısını belirtir.

Yeniden deneme mantığı uygulanırken her zaman Retry-After başlığı tercih edin.

Uygulamanızda hız sınırlamayı işleme

Uygulamalar şunları yapmalıdır:

• HTTP 429 yanıtlarını algılama.
• Üst bilgiyi ayrıştırın ve Retry-After dikkate alın.
• Yüksek ölçekli senaryolar için üstel geri çekilme ve dalgalanma gibi sınırlı bir yeniden deneme politikası uygulayın.
• Sonsuz yeniden deneme döngülerinden kaçının.

Hız sınırlama olasılığını azaltma

• Mümkünse toplu ve yığın işlemler kullanın.
• Yinelenen tek kaynak istekleri yerine liste API'lerini tercih edin.
• Sık erişilen verileri, özellikle de seyrek değişen meta verileri önbelleğe alın.
• İstekleri zaman içinde eşit bir şekilde dağıtarak trafik artışlarından kaçının.

Kapasite sınırı aşıldı (CapacityLimitExceeded)

Bir CapacityLimitExceeded hatası, kapasitenizde tüketilen işlem kaynaklarının (kapasite birimleri) satın alınan Fabric SKU'sunun sınırlarını aştığını gösterir. Oran sınırlamasının aksine, bu kısıtlama belirli bir istemcinin yaptığı API çağrılarının sayısından kaynaklanmaz; kapasitedeki tüm iş yükleri genelinde tüketilen toplam işlem kaynaklarını yansıtır.

Örnek yanıt gövdesi:

"Your organization's Fabric compute capacity has exceeded its limits. Try again later."

Kapasite kısıtlamasını yönetme

Bu azaltma, tekil istek hızınızdan ziyade kapasitenizde tüketilen toplam işleme bağlı olduğundan, Retry-After üst bilgisi geçerli değildir ve kapasitenin işlem kullanımı yeniden sınırları içine düşene kadar hemen yeniden denemenin başarılı olması pek olası değildir. Uygulamalar şunları yapmalıdır:

• İsteği daha sonra üstel geri alma ile sınırlanmış bir yeniden deneme ilkesi kullanarak yeniden deneyin.
• Hata devam ederse Fabric kapasitenizin ölçeğini artırmayı veya genişletmeyi göz önünde bulundurun.

Kapasite birimleri, SKU'lar ve Fabric kapasitenin nasıl tüketileceği hakkında daha fazla bilgi için bkz. Kapasite boyutunuzu planlama.

Özet

Microsoft Fabric REST API'leriyle güvenilir tümleştirmeler oluşturmak için güçlü hata işleme ve verimli istek desenleri gerekir. Hata yanıtlarını anlayarak, azaltma sinyallerini kabul ederek ve istek desenlerini iyileştirerek dayanıklı uygulamalar oluşturabilirsiniz.

---

İlgili içerik

Ek sorular veya topluluk kılavuzu için bkz. Microsoft Fabric Community