GraphQL için Doku API'sine uygulama bağlama

Uygulamaları GraphQL için Fabric API'sine bağlamak, web, mobil ve arka uç uygulamalarınızın modern, verimli bir API kullanarak Fabric veri kaynaklarını sorgulamasını sağlar. Bu tümleştirme, GraphQL uç noktasını güvenli bir şekilde çağırmak için Microsoft Entra Kimliği ve uygulamanızın yapılandırması aracılığıyla doğru kimlik doğrulaması gerektirir.

Bu makalede, react uygulamasını Doku GraphQL API'sine bağlama adımları şunlardır:

1. Kimlik doğrulaması için Microsoft Entra uygulaması oluşturma ve yapılandırma
2. Sorgulamak için verilerle Fabric'de örnek bir GraphQL API'si ayarlama
3. GitHub'dan tam bir React uygulamasını kopyalama ve yapılandırma
4. Kimliği doğrulanmış bağlantıyı test etme

Öğreticide React kullanılır, ancak kimlik doğrulama kavramları tüm diller için geçerlidir. C#, Python veya diğer dillerdeki örnekler için bkz. Microsoft Fabric Örnekleri GitHub deposu.

Uygulamaları bağlaması gereken kişiler

Uygulama bağlantısı kurulumu şu nedenler için gereklidir:

• Web ve mobil uygulama geliştiricileri, Fabric'in lakehouse ve veri ambarlarından veri tüketen uygulamalar geliştiriyor.
• Fabric verilerini özel uygulamalara ve otomatik iş akışlarına bağlayan tümleştirme geliştiricileri
• Arka uç geliştiricileri , Fabric'in birleşik analiz platformuyla tümleşen hizmetler oluşturuyor
• Veri mühendisleri, API'ler aracılığıyla Fabric verilerini kullanan otomatik veri işleme iş akışlarını ayarlama.

Doku GraphQL API'lerinize erişmek için uygulamaların kimliğini doğrulamanız ve yetkilendirmeniz gerektiğinde bu kılavuzu kullanın.

Önkoşullar

• Geliştirme araçları: Makinenizde Node.js (LTS sürümü) ve Visual Studio Code'un yüklü olması gerekir.

• Bir uygulamayı bağlamadan önce, Doku'da GraphQL için bir API'niz olduğundan emin olun. Daha fazla bilgi için bkz . Dokuda GraphQL için API oluşturma ve veri ekleme.

• GraphQL API'sinin, uygulamaların kimlik doğrulaması için Microsoft Entra kullanmasını gerektirir. Uygulamanızı Doku'ya karşı API çağrıları gerçekleştirecek şekilde kaydedin ve yapılandırın. Daha fazla bilgi için bkz . Azure'da Microsoft Entra uygulaması oluşturma.

• API'yi çağıran kimliği doğrulanmış kimlik bilgisi (kullanıcı sorumlusu, hizmet sorumlusu veya yönetilen kimlik) GraphQL API'sinde Yürütme izinleri gerekir (Doğrudan erişim izinleri eklerken Sorguları ve Mutasyonları Çalıştır seçeneği). API'de bağlantı seçeneği olarak çoklu oturum açma (SSO) kullanıyorsanız, kimlik bilgilerinin seçilen veri kaynağında okuma veya yazma izinlerine sahip olduğundan emin olun. Daha fazla bilgi için bkz. Veri kaynağına bağlanma veşemanızı oluşturma.

Kimlik doğrulaması ve izin özeti

GraphQL API'sine erişim için hem API düzeyinde hem de temel alınan veri kaynağı düzeyinde doğru kimlik doğrulaması ve yetkilendirme gerekir. Bir kullanıcı sorumlusu (tek bir kullanıcıyı temsil eden) veya hizmet sorumlusu (bir uygulamayı veya hizmeti temsil eden) kullanarak kimlik doğrulaması yapabilirsiniz. Veri kaynağı bağlantısı için, çağıranın kimliğinin veri kaynağına geçirildiği çoklu oturum açma (SSO) veya önceden yapılandırılmış bir bağlantının kullanıldığı kayıtlı kimlik bilgilerini kullanabilirsiniz.

Aşağıdaki tabloda desteklenen farklı kimlik doğrulama senaryoları ve GraphQL API'sine erişen istemciler için gereken en düşük izinler özetlenmektedir:

API Çağıranı	Veri kaynağı bağlantısı	Gerekli GraphQL API izinleri	Gerekli Veri Kaynağı izinleri	Microsoft Entra uygulama kapsamı
Kullanıcı Sorumlusu (UPN)	Çoklu oturum açma (SSO)	Sorguları ve Mutasyonları API düzeyinde çalıştırma	Veri kaynağında UPN'ye verilen uygun Okuma/Yazma izinleri	GraphQLApi.Execute.All
Hizmet Sorumlusu (SPN)	Çoklu oturum açma (SSO)	Sorguları ve Mutasyonları API düzeyinde çalıştırma	Veri kaynağında SPN'ye verilen uygun Okuma/Yazma izinleri	Geçerli değil
Kullanıcı Sorumlusu (UPN)	Kaydedilen kimlik bilgileri	Sorguları ve Mutasyonları API düzeyinde çalıştırma	Veri kaynağındaki kayıtlı kimlik bilgilerine (bağlantı) verilen uygun Okuma/Yazma izinleri	GraphQLApi.Execute.All
Hizmet Sorumlusu (SPN)	Kaydedilen kimlik bilgileri	Sorguları ve Mutasyonları API düzeyinde çalıştırma	Veri kaynağında SPN'ye verilen uygun Okuma/Yazma izinleri	Geçerli değil

Microsoft Entra uygulaması oluşturma

Uygulamanızın Fabric GraphQL API'sini çağırabilmesi için önce Bunu Microsoft Entra Id'ye kaydetmeniz gerekir. Bu kayıt, uygulamanız için bir kimlik oluşturur ve hangi izinlere ihtiyaç duyduğunu tanımlar. Kayıt işlemi bir İstemci Kimliği (uygulama tanımlayıcısı) oluşturur ve uygulamanızın erişim belirteçlerini almak için kullandığı kimlik doğrulama akışını oluşturur.

React uygulamaları için, istemci gizli dizilerinin güvenli bir şekilde depolanmadığı tarayıcı tabanlı uygulamalar için tasarlanmış güvenli bir kimlik doğrulama yöntemi olan PKCE akışını kullanan tek sayfalı uygulama (SPA) ayarlarını yapılandırabilirsiniz.

1. Hızlı Başlangıç:Microsoft kimlik platformuna uygulama kaydetme başlığı altında açıklanan adımları kullanarak bir uygulamayı kaydetme.

2. Özet kutusunda Microsoft Entra uygulaması Uygulaması (istemci) Kimliği ve Dizin (kiracı) Kimliği değerleri görüntülenir. React uygulamasını yapılandırırken bunlara ihtiyacınız olduğundan bu değerleri kaydedin.

3. Uygulamanızın Doku GraphQL API'sine erişebilmesi için API izinlerini yapılandırın. Yönet listesinin altında, API izinleriniseçin, ardından "İzin ekle"'yi seçin.

4. PowerBI Hizmetini ekleyin, Temsilci izinleri'ni seçin ve GraphQLApi.Execute.All izinleri'ni seçin. Bu izin, uygulamanızın oturum açmış kullanıcı adına sorgular ve mutasyonlar yürütmesine olanak tanır. Yönetici onayının gerekli olmadığını onaylayın.

5. Yönet listesine dönün, Kimlik Doğrulaması>Platform> ekleTek sayfalı uygulama'yı seçin.

6. Yerel geliştirme amacıyla Yeniden Yönlendirme URI'leri bölümüne ekleyin http://localhost:3000 ve uygulamanın Kod Değişimi için Proof Key (PKCE) ile yetkilendirme kodu akışı için etkinleştirildiğini onaylayın. Değişikliklerinizi kaydetmek için Yapılandır düğmesini seçin. Uygulama çıkış noktaları arası isteklerle ilgili bir hatayla karşılaşırsa, önceki adımda aynı yeniden yönlendirme URI'sine sahip Mobil ve masaüstü uygulamaları platformunu ekleyin.

7. Kimlik Doğrulaması'ne dönün, ekranı aşağı kaydırarak gelişmiş ayarlar gidin ve genel istemci akışlarına izin veraltında için Evet'i seçinaşağıdaki mobil ve masaüstü akışlarını etkinleştirin.

Uygulama erişimi için örnek bir GraphQL API'sini ayarlama

Microsoft Entra uygulamanızı kaydettikten sonra, sorgulamak için Fabric'de bir GraphQL API'sine ihtiyacınız vardır. Bu bölümde, Doku'nun resmi tatiller veri kümesini kullanarak örnek bir API oluşturma adımları açıklanmıştır. Bu, kendi veri kaynaklarınızı yapılandırmanıza gerek kalmadan kimlik doğrulamasını ve veri alımını test etmek için çalışan bir API sağlar.

Örnek API, React uygulamanızın resmi tatilleri görüntülemek için sorguladığı bir Lakehouse tablosundaki tatil verilerini kullanıma sunar.

1. Doku portalı giriş sayfasında, iş yükleri listesinden Veri Madenciliği seçin.

2. Veri Mühendisliği deneyiminde Örnek kullan'ı seçin ve Lakehouse'un altında Resmi tatiller'i seçerek resmi tatil verileriyle otomatik olarak yeni bir Lakehouse oluşturun.

   

3. Yeni bir GraphQL API'sini oluşturmak ve oluşturduğunuz Lakehouse'u seçmek için GraphQL için API oluşturma adımlarını izleyin. İstemcilerin bu verilere erişebilmesi için resmi tatiller tablosunu ekleyin.

   

4. React uygulamasını derlemeden önce API düzenleyicisinde test ederek API'nizin düzgün çalıştığını doğrulayın. Aşağıdaki sorguyu kullanın; bu, React uygulamanızın daha sonra yürüttüğü sorguyla aynıdır:

    query {
    publicholidays (filter: {countryRegionCode: {eq:"US"}, date: {gte: "2024-01-01T00:00:00.000Z", lte: "2024-12-31T00:00:00.000Z"}}) {
        items {
          countryOrRegion
          holidayName
          date
        }
      }
    }
   

5. API öğesinin araç çubuğunda Uç noktayı kopyala'yı seçin.

   

6. Bağlantıyı kopyala ekranında Kopyala'yı seçin.

   

7. Microsoft Entra uygulamasından ve uç nokta URI'sinden İstemci Kimliğini ve Kiracı Kimliğini kaydedin. React uygulamasını yapılandırırken bu değerlere ihtiyacınız vardır.

React uygulamasını kopyalama ve yapılandırma

Artık Microsoft Entra uygulamasını ve GraphQL API'sini ayarladığınıza göre, bunlara bağlanmak için bir React uygulaması yapılandırabilirsiniz. Uygulama, kimlik doğrulamasını işlemek için Microsoft Kimlik Doğrulama Kitaplığı'nı (MSAL) kullanır ve Taşıyıcı belirteçleri ile GraphQL istekleri yapar.

1. GitHub'dan örnek deposunu kopyalayın:

   git clone https://github.com/microsoft/fabric-samples.git
   

2. React uygulaması klasörüne gidin:

   cd fabric-samples/docs-samples/data-engineering/GraphQL/React
   

   klasörü tam bir React uygulaması içerir. Belirli uç noktanızı ve kimlik bilgilerinizi yapılandırmak için yalnızca src/authConfig.js düzenlemeniz gerekir.

3. Projeyi kod düzenleyicinizde açın:

   code .
   

4. Düzenleyicinizde klasörüne src gidin ve dosyasını açın authConfig.js.

5. Aşağıdaki yer tutucu değerlerini kendi ayrıntılarınızla değiştirin:

   • Enter_the_GraphQL_Endpoint_Here - Uygulama erişimi için örnek bir GraphQL API'si ayarlama adımından GraphQL API uç noktanızla değiştirin
   • Enter_the_Application_Id_Here- Yerine Microsoft Entra uygulaması oluşturma bölümünden Uygulama (istemci) kimliğiniz ekleyin
   • Enter_the_Tenant_Info_Here - Microsoft Entra uygulaması oluşturma bölümünden Dizin (kiracı) kimliğinizi yerine yazın

   Önemli

   Aynı dosyada loginRequest sabit, kapsamını https://analysis.windows.net/powerbi/api/GraphQLApi.Execute.Alliçerir. Doku GraphQL API'lerine erişmek için tam olarak bu kapsam gereklidir. Bu kapsamı kaldırmayın veya değiştirmeyin; aksi takdirde kimlik doğrulaması başarısız olur.

6. Dosyayı kaydedin.

7. Terminalinizde proje kök klasörüne gidin ve şunu çalıştırın:

   npm install
   

   Bu, tüm gerekli bağımlılıkları yükler.

Uygulamayı test et

Uygulama yapılandırıldığında, her şeyin düzgün çalıştığını doğrulamak için yerel olarak çalıştırın:

1. Terminalinizde şunu çalıştırın:

   npm start
   

   Bu komut geliştirme sunucusunu başlatır ve uygulamayı tarayıcınızda açar.

2. Uygulama http://localhost:3000 konumunda yüklendiğinde kimlik doğrulama akışını tamamlayın. Api'yi uygulamadan çağırma öğreticisi bölümünde açıklanan oturum açma adımlarını izleyin.

3. Başarıyla oturum açtıktan sonra GraphQL Verileri için Query Fabric API'sini seçin. Bu, kimlik doğrulama akışını tetikler, bir erişim belirteci alır ve Doku API'nizde GraphQL sorgusunu yürütür.

   

4. Her şey doğru yapılandırıldıysa, uygulama resmi tatilleri bir tabloda görüntüler. Bu, şunu onaylar:

   • Microsoft Entra uygulamanız doğru izinlere sahip
   • Erişim belirteci başarıyla alındı
   • GraphQL API isteği kimlik doğruladı
   • Lakehouse verilerine karşı yürütülen sorgu

   

Diğer npm komutları

npm start ve npm install dışında, farklı geliştirme senaryoları için şu yaygın npm komutlarını kullanabilirsiniz:

• npm run dev - Geliştirme sunucusunu başlatmanın alternatif yolu
• npm run build - Uygulamanızın iyileştirilmiş bir üretim derlemesi oluşturma
• npm run preview - Dağıtmadan önce üretim derlemesini yerel olarak test edin
• npm test - Kodunuzun düzgün çalıştığını doğrulamak için otomatikleştirilmiş testler çalıştırma

İlgili içerik

Artık Fabric GraphQL API'nize bağlı çalışan bir uygulamanız olduğuna göre, daha gelişmiş çözümler oluşturmak için şu kaynakları keşfedin:

• Fabric'de GraphQL için bir API oluşturun ve veri ekleyin - Kendi veri kaynaklarınızı açma hakkında bilgi edinin
• GraphQL için Doku API'sinde birden çok veri kaynağını sorgulama - Farklı kaynaklardan gelen verileri tek bir sorguda birleştirme
• GraphQL düzenleyicisi için Fabric API - Sorguları etkileşimli bir şekilde test edin ve geliştirin.
• Azure'da Microsoft Entra uygulaması oluşturma - Üretim uygulaması kaydı için ayrıntılı kılavuz
• Microsoft Fabric GraphQL örnekleri - Birden çok dilde örneklere göz atın