Fabric Uygulamalarının Sorunlarını Giderin

bir Fabric Apps projesi geliştirirken veya dağıtırken sık karşılaşılan sorunları tanılayın. Bu makalede oturum açma, yerel hizmetler, şema değişiklikleri, statik barındırma ve CLI ile ilgili sorunlar ele alınıyor.

Dağıtım sorunları

Dağıtım 401 veya 403 hatasıyla başarısız oluyor

Belirti: Çalıştırma npx rayfin up bir kimlik doğrulama hatası döndürür.

Neden: Kimlik doğrulama oturumunuzun süresi doldu veya oturumunuz açık değil.

Çözüm:

Dağıtımı yeniden doğrulayın ve yeniden deneyin:

npx rayfin login
npx rayfin up

Statik dağıtım boyut sınırını aşıyor

Belirti: Statik içerik dağıtımı boyut sınırı hatasıyla başarısız oluyor.

Neden: Sıkıştırılmış arşiv 100 MB'ı aşıyor.

Çözüm:

Derleme çıktısı boyutunu küçültmek için:

  • Kaynak haritalarını üretim derlemelerinin dışında bırakma
  • Büyük resimleri ve videoları iyileştirme veya kaldırma
  • İkili dosyaları paketlemek yerine depolamaya taşıma
  • Paketleyici yapılandırmanızın doğrulanması geliştirme yapıtlarını dışlar

Statik dağıtımda uzak uç nokta yoktur

Belirti: Çalıştırılırken npx rayfin up staticapp deploy hiçbir uzak uç nokta ayarlanmadığını bildiriyor.

Sebep: Sadece statik dağıtım, mevcut bir dağıtımı günceller. İlk uzaktan uygulamayı sağlayamıyor.

Çözüm:

Tam bir dağıtımı bir kez çalıştırın:

npx rayfin up

Sağlama işlemi tamamlandıktan sonra, bundan sonraki yalnızca statik güncellemeler için npx rayfin up staticapp deploy kullanın.

Kimlik doğrulaması sorunları

Kimlik doğrulama token edinimi başarısız oldu

Belirti:npx rayfin login veya kimliği doğrulanmış başka bir CLI komutu, Failed to acquire authentication token ya da bir kimlik bilgisi depolama hatası bildirir.

Sebep: CLI giriş yapmamış veya ortam işletim sistemi destekli kimlik bilgilerini depolamaz.

Çözüm:

Tekrar giriş yapın:

npx rayfin login

Kimlik kaydı depolama olmadan kısıtlı yerel geliştirme ortamı için, şifreleme yedek seçeneğini etkinleştirebilirsiniz:

npx rayfin login --encryption-fallback-enabled

Warning

Şifreleme geri dönüş yöntemi, token önbelleğini açık metin olarak saklar. Sadece güvenilir bir geliştirme ortamında kullanın. Üretimde veya paylaşılan ortamlarda kullanmayın.

Oturum açma sonrasında oturum kalıcı değil

Belirti: Kullanıcıların kimlik doğrulamasından hemen sonra oturumları kapatılır.

Neden: İstemci doğru temel URL veya yayımlanabilir anahtarla yapılandırılmamış.

Çözüm:

RayfinClient yapılandırmasının backend’inizle eşleştiğini doğrulayın:

const client = new RayfinClient({
  baseUrl: import.meta.env.VITE_RAYFIN_API_URL ?? 'http://localhost:5168',
  publishableKey: import.meta.env.VITE_RAYFIN_PUBLISHABLE_KEY,
});

Fabric SSO açılır penceresi engellendi

Symptom: Browser, oturum açma sırasında Fabric portalı penceresini engeller.

Neden:ensureSignedInWithFabric() kullanıcı hareketi işleyicisinden çağrılmadı.

Çözüm:

zaman uyumlu bir olay işleyicisinden işlevini çağırın:

async function handleClick() {
  await ensureSignedInWithFabric(client.auth, options);
}

// Attach to button click
<button onClick={handleClick}>Sign in</button>

Fabric kimlik doğrulaması zaman aşımına uğruyor

Belirti: Fabric doğrulaması beş dakika sonra başarısız oluyor.

Sebep: Fabric portalı, akış süresi dolmadan önce handoff kodunu geri göndermedi.

Çözüm:

Uygulamanızın returnOrigin kaynağıyla eşleştiğinden emin olun, açılır pencereyi kapatın ve giriş akışını yeniden başlatın.

Fabric SSO, orijin uyumsuzluğu bildiriyor

Belirti: Fabric SSO aktarımı, kaynağı eşleşmediği için yanıtı reddeder.

Neden:returnOrigin, allowedRedirectUris, ya da fabricPortalUrl uygulama ile Fabric portalının çalıştığı ortamla uyuşmuyor.

Çözüm:

  1. returnOrigin değerini uygulamanızın yalın origin’i olarak ayarlayın.
  2. Orijinin services.auth.allowedRedirectUris içinde göründüğünü doğrulayın.
  3. Doğru üretim, önizleme veya geliştirme ortamı için Fabric portal URL'sini kullanın.
  4. npx rayfin up öğesini değiştirdikten sonra rayfin.yml öğesini çalıştırın.

Daha fazla bilgi için bkz. Kimlik doğrulama yönlendirme URI'lerini yapılandırma.

initEmbeddedAuth(), null döndürür.

Belirti: Gömülü kimlik doğrulama oturum oluşturmaz.

Sebep: SDK, uygulamanın Fabric içinde çalıştığını tespit etmedi.

Çözüm:

Uygulama URL’sine ?fabricEmbedded=true ekleyin veya FabricAuthOptions içinde fabricEmbedded: true ayarlayın.

Fabric doğrulama durum uyumsuzluğu bildirir

Belirti: Giriş başarısız olur çünkü yanıt durumu istek durumuyla eşleşmiyor.

Sebep: Yanıt, süresi dolan bir akışa veya önceki bir giriş girişimine aittir.

Çözüm:

Fabric açılır penceresini kapatın ve giriş akışını yeniden başlatın. Önceki bir denemeden geri çağrı URL'lerini veya durum değerlerini tekrar kullanmayın.

Veri modeli sorunları

Veri API'si dağıtımdan sonra dahili sunucu hatası döndürür

Belirti:npx rayfin up veya npx rayfin up db apply başarılı olursa, ancak GraphQL veya REST veri API'si dahili sunucu hatası döndürür.

Sebep: Microsoft SQL Server'da, @text() içermeyen bir max alanı, NVARCHAR(MAX) sütunu oluşturur; bu da GraphQL şeması oluşturulmasını engelleyebilir.

Çözüm:

Her etkilenen metin alanına açık bir maksimum uzunluk ekleyin:

@text({ max: 200 })
title!: string;

Sonra şema değişikliğini gözden geçirip uygula:

npx rayfin up db apply --force

Caution

--force kullanmadan önce bildirilen tüm işlemleri gözden geçirin. Bu seçenek kalıcı veri kaybına yol açabilir.

Veri hizmeti için bir lehçe gereklidir

Belirti: HTTP 400 yanıtıyla dağıtım başarısız olur ve raporlar Dialect is required when Data module is enabledbildirir.

Neden:services.data.enabled , trueama rayfin.yml bir lehçeyi tanımlamaz.

Çözüm:

Microsoft SQL Server'ı yapılandırın:

services:
  data:
    enabled: true
    dialect: mssql

Dağıtımdan sonra yeni bir varlık mevcut değildir

Belirti: Dağıtım başarılı olur, ancak yeni veya değiştirilmiş bir varlığa karşı yapılan sorgular başarısız olur veya varlık yokmuş gibi davranır.

Sebep: Veritabanı şeması hâlâ geçerli olabilir ya da ön yüz mod eski oluşturulmuş türler veya önbelleklenmiş yapılandırmalar kullanıyor olabilir.

Çözüm:

  1. Dağıtımı kontrol edin:

    npx rayfin up status

  2. Dağıtım sağlıklı duruma gelene kadar bekleyin.

  3. Ön ucu yenileyin veya yeniden oluşturun.

  4. Varlık hâlâ başarısız olursa, şemayı açıkça uygulayın:

    npx rayfin up db apply

Tam iş akışı için bkz. Uygulama ve şema değişikliklerini doğrula.

API'de görünmeyen ilişkiler

Belirti: sorgularken ilgili varlık alanları kullanılamaz.

Neden: Gezinti dekoratörü eksik veya şema uygulanmadı.

Çözüm:

  1. İlişki dekoratörlerinin mevcut olduğunu doğrulayın:

    @one(() => Notebook) notebook?: Notebook;

  2. Şemayı yeniden uygulayın.

Yetkilendirme ilkesi çalışmıyor

Belirti: Kullanıcılar görmemeleri gereken kayıtlara erişebilir.

Neden: İlke ifadesi yanlış veya talep adları eşleşmiyor.

Çözüm:

  1. İlkenin doğru talep adlarını (sub, email, role) kullandığını doğrulayın:

    policy: (claims, item) => claims.sub.eq(item.user_id)

  2. Talep değerlerinin kodunuzla eşleştiğinden emin olmak için kodu çözülen JWT'yi günlüğe yazın.

Eski API yanıtları

Belirti: Ön uç, şema değişikliklerinin ardından eski veri şekillerini döndürür.

Neden: Oluşturulan yapılandırma önbelleğe alınır.

Çözüm:

  1. Arka ucu durdurun.

  2. .temp/ içindeki rayfin/ dizinini silin:

    rm -rf rayfin/.temp/

  3. Hizmetleri yeniden başlatın ve şemayı yeniden uygulayın.

CLI sorunları

Komut bulunamadı

Belirti: Komutunu çalıştırmak npx rayfin "komut bulunamadı" sonucunu döndürür.

Neden: CLI yüklü değil veya npm PATH'inizde değil.

Çözüm:

  1. Node.js ve npm'nin yüklendiğini doğrulayın:

    node --version
npm --version

  2. Bağımlılıkları yeniden yükleyin:

    npm install

CLI sürümü uyuşmazlığı

Belirti: CLI komutları güncelleştirildikten sonra beklenmeyen hatalarla başarısız olur.

Neden: Önbelleğe alınan CLI sürümü güncel değil.

Çözüm:

Güncelleştirin ve yeniden yükleyin:

npm update --save
npm install
npx rayfin --version

CLI küresel ve yerel versiyon uyumsuzluğu

Belirti: CLI komutları projeler arasında beklenmeyen hatalarla başarısız olur.

Neden: CLI sürümlerinin genel ve yerel yüklemesi ve bunlar eşleşmiyor.

Çözüm: Yerel sürümü npm list @microsoft/rayfin-clidoğrulayın. Bu, geçerli projenizin node_modules klasöründeki sürümü gösterir. Genel sürümü npm list -g @microsoft/rayfin-clidenetleyin. Bu, sistem genelinde yüklü sürümü gösterir. npm uninstall -g Genel sürümü kaldırmak ve yerel sürümlerinizi kullanmak için Rayfin CLI paketiyle kullanın.

Gizli yönetim sorunları

Gizli komut istem vermez

Belirti:npx rayfin secret set <NAME> Bir değer sormadan çıkar.

Sebep: Standart girdi etkileşimli bir terminal değildir veya CI ortam değişkeni olarak trueayarlanmıştır. Komut, maskeli etkileşimli bir prompt kullanır.

Çözüm:

Etkileşimsiz gizli oluşturma için aşağıdaki desteklenen alternatiflerden birini kullanın:

  • Bir sırrı komuta değerini göndererek ayarlayın:

    Get-Content .\secret.txt | npx rayfin secret set <NAME> --stdin

  • Bir ortam dosyasından birden fazla sır ayarlayın:

    npx rayfin secret set --env-file .\secrets.env

Gizli değerleri shell geçmişinizden uzak tutun ve secret.txt veya .\secrets.env öğelerini kaynak denetimine commit etmeyin.

Gizli komut, "izin reddedildi" hatası döndürüyor

Belirti:npx rayfin secret set veya npx rayfin secret list izin hatası döndürür.

Sebep: Uygulama dağıtılmıyor ya da giriş yapan hesap hedef Fabric çalışma alanına erişemiyor.

Çözüm:

  1. Uygulamayı hazırlamak için npx rayfin up çalıştırın.
  2. npx rayfin login öğesini çalıştırın ve çalışma alanına erişimi olan bir hesap seçin.
  3. Gizli komutu tekrar dene.

Daha fazla bilgi için bkz. Fonksiyon sırlarını yönet.

Derleme ve paketleme sorunları

Derleme komutu başarısız

Belirti: Derleme komutu hiçbir çıkış üretmediğinden statik barındırma dağıtımı başarısız oluyor.

Neden: Derleme hataları veya yanlış yapılandırılmış derleme komutu.

Çözüm:

  1. Derleme komutunu el ile çalıştırın:

    npm run build

  2. Bildirilen hataları düzeltin.

  3. Çıkış klasörünün dosya içerdiğini doğrulayın.

Boş statik klasör

Belirti: Statik dağıtım "boş klasör" hatasıyla başarısız oluyor.

Neden: Yapılandırılan folder yol yanlış.

Çözüm:

içindeki folder yolunun rayfin.yml derleme çıkışınızla eşleştiklerini doğrulayın:

services:
  staticHosting:
    folder: dist  # Verify this matches your build output
    buildCommand: npm run build

Veritabanı sorunları

Veritabanı şeması uygulaması başarısız oldu

Belirti:npx rayfin up db apply veya npx rayfin up db apply --force çalıştırıldığında başarısız olur.

Sebep: Uzak veritabanındaki şema ile uygulama kodunda tanımlanan şema senkronize değil. Uygulama kodu, bir Fabric uygulaması için gerçeğin kaynağıdır.

Fabric portalı, SQL Server Management Studio (SSMS), Visual Studio Code için SQL Server uzantısı veya diğer SQL araçları aracılığıyla uzak veritabanı şemasını değiştirmeyin. Bir veri varlığındaki sütunlarda yapılan aşağıdaki değişiklikler desteklenmemektedir:

  • Bir sütunun adını değiştirmek.
  • Bir sütunun veri türünü değiştirmek.
  • Bir sütun çıkarıyorum.

Bir sütun eklemek desteklenir. Mevcut bir sütunu kaldırmak veya değiştirmek, uygulamayı ve Fabric'e dağıtımını bozabilir.

Çözüm:

  1. Uzak veritabanı şemasına yapılan manuel değişiklikleri uygulama kodundaki şema ile eşleştirecek şekilde geri alın.

  2. Bir kodlama ajanı uygulama kodunda desteklenmeyen bir şema değişikliği yaptıysa, ajana bu değişikliği geri almasını emredebilirsiniz.

  3. Şema uygula komutunu tekrar çalıştırın:

    npx rayfin up db apply

    Bir sütun yeniden adlandırması için, --force şema güncellemesinin tamamlanmasına izin verebilir:

    npx rayfin up db apply --force

    Caution

    kullanmak --force kalıcı veri kaybına neden olabilir. Önerilen işlemleri gözden geçirin ve ilerlemeden önce veri kaybı riskini kabul ettiğinizi doğrulayın.

Bağlantı reddedildi

Belirti: Veri işlemleri bağlantı hatalarıyla başarısız olur.

Neden: Veritabanı kapsayıcısı çalışmıyor veya sistem durumu denetimleri başarısız oldu.

Çözüm:

  1. Kapsayıcı günlüklerini gözden geçirin:

    docker compose logs -f

  2. Hizmetleri yeniden başlatın.

Yeniden başlatıldıktan sonra veri kaybı

Belirti: Hizmetler durdurulup başlatıldıktan sonra veriler kaybolur.

Neden: Birimler, --purge kullanılarak silindi.

Çözüm:

Verileri korumak için yerine --down kullanın--purge.

Bilinen sınırlamalar

Geçerli sınırlamalar ve önerilen geçici çözümler için bkz:

  • count() akıcı GraphQL istemcisinde kullanılamaz; kullanın results.length.
  • Çoktan çoğa ilişkiler desteklenmez; açık bir join varlığı kullanın.
  • Oturum nesneleri opaktır; isAuthenticated veya user özelliklerini kontrol edin.
  • içinde rayfin.ymlkimlik doğrulamasını etkinleştirdikten veya devre dışı bırakdıktan sonra arka ucu yeniden başlatın.

Yardım alın

Sorun devam ederse:

  1. Fabric Apps belgelerini gözden geçirin.
  2. Bilinen sorunlar için GitHub deposunu denetleyin.
  3. Ayrıntılı günlükleri ve çoğaltma adımlarını içeren bir hata raporu oluşturun.

İlgili içerik

  • Son güncelleştirme: