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

Makale
12/27/2024

Bir uygulamayı GraphQL api'sine bağlamak için üç önemli bilgi parçasına ihtiyacınız vardır: İstemci Kimliği, Kiracı Kimliğiniz ve Doku'daki GraphQL uç nokta adresiniz. Aşağıdaki bölümlerde, ihtiyacınız olan tüm ayrıntıların nasıl oluşturulacağını ve alınacağını ve örnek bir uygulama kullanarak API'nize nasıl erişebileceğimizi göstereceğiz.

Önkoşullar

Şu anda GraphQL için API, uygulamaların kimlik doğrulaması için Microsoft Entra kullanmasını gerektirir. Uygulamanızın Doku'ya karşı API çağrıları gerçekleştirmek için yeterli şekilde kaydedilmesi ve yapılandırılması gerekir. Daha fazla bilgi için bkz . Azure'da Microsoft Entra uygulaması oluşturma.
API'yi çağıran kimliği doğrulanmış kullanıcının GraphQL API'si için Çalıştırma izinlerine ihtiyacı vardır (doğrudan erişim izinleri eklenirken Sorguları ve Mutasyonları Çalıştır seçeneği) ve API'de bağlantı seçeneği olarak Tek oturum açma (SSO) kullanılıyorsa, tercih edilen veri kaynağında okuma veya yazma izinleri gereklidir. Daha fazla bilgi için bkz. Veri kaynağına bağlanma veşemanızı oluşturma.
Bir uygulamayı bağlamadan önce, Doku'da GraphQL için bir API'niz olmalıdır. Daha fazla bilgi için bkz . Dokuda GraphQL için API oluşturma ve veri ekleme.

Microsoft Entra uygulaması oluşturma

Aşağıdaki adımlarda, Microsoft Entra'da ReactJS uygulaması desteğini yapılandırmayı göstereceğiz.

Hızlı Başlangıç:Microsoft kimlik platformuna uygulama kaydetme başlığı altında açıklanan adımları kullanarak bir uygulamayı kaydetme.
Microsoft Entra uygulaması Uygulama (istemci) kimliğiniz ve Dizin (kiracı) kimliği değerleriniz Özet kutusunda görüntülenir. Bu değerleri daha sonra gerekli olacak şekilde kaydedin.
Yönet listesinin altında, API izinleriniseçin, ardından "İzin ekle"'yi seçin.
PowerBI Hizmetiekleyin, Temsilci izinleriniseçin ve GraphQL.Execute.All izinlerini seçin. Yönetici onayı gerekli olmadığından emin olun.
Yönet listesine dönün, Kimlik Doğrulaması> ekle, > seçin.
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. Uygulamanın çıkış noktaları arası isteklerle ilgili bir hata alması durumunda, önceki adımda aynı yeniden yönlendirme URI'sine sahip Mobil ve masaüstü uygulamaları platformunu ekleyin.
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

Bu örnekte örnek Lakehouse verilerini istemcilere göstermek için bir GraphQL API'sini oluşturacağız.

Doku portalı giriş sayfasında, iş yükleri listesinden Veri Madenciliği seçin.
Veri Madenciliğ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.
GraphQL için API oluşturma adımlarını izleyerek yeni bir GraphQL API oluşturun ve oluşturduğunuz Lakehouse'u seçin. İstemcilerin bu verilere erişmesine izin vermek için resmi tatiller tablosunu ekleyin.

Aşağıdaki örnek sorguyu kullanarak GraphQL API'sini API düzenleyicisinde test edin. React istemci uygulamamızda kullandığımız 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
     }
   }
 }

API öğesinin araç çubuğunda Uç noktayı kopyala'yı seçin.
Bağlantıyı kopyala ekranında Kopyala'yı seçin.
Microsoft Entra uygulamasının İstemci Kimliği ve Kiracı Kimliği daha önce kaydedildiği gibi, uç nokta URI'sini daha sonra gerekli olduğu gibi kopyalayın.

Resmi tatiller API'sine erişmek için React uygulaması yapılandırma

Başlangıç noktası olarak mevcut bir React uygulamasını kullanırız. Proje yapısına eklenmesi gereken ek dosya ve klasörler de dahil olmak üzere, React tek sayfalı uygulama oluşturma öğreticisinin tüm adımlarını izleyin ve microsoft Entra kimlik doğrulaması zaten yapılandırılmış bir React projesi oluşturmak için bunu kimlik doğrulamasına hazırlayın. Uygulamayı GraphQL kullanım örneğimize uyarlamak için yalnızca üç dosyayı değiştirmemiz gerekir.

src klasöründe authConfig.js dosyasını açın ve dosyanın içeriğini aşağıdaki kod parçacığıyla değiştirin:

 /*
  * Copyright (c) Microsoft Corporation. All rights reserved.
  * Licensed under the MIT License.
  */

 import { LogLevel } from "@azure/msal-browser";

 /**
  * Configuration object to be passed to MSAL instance on creation. 
  * For a full list of MSAL.js configuration parameters, visit:
  * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/configuration.md 
  */

 export const graphqlConfig = {
     graphqlEndpoint: "`Enter_the_GraphQL_Endpoint_Here"
 };

 export const msalConfig = {
     auth: {
         clientId: "Enter_the_Application_Id_Here",
         authority: "https://login.microsoftonline.com/Enter_the_Tenant_Info_Here",
         redirectUri: "http://localhost:3000",
     },
     cache: {
         cacheLocation: "sessionStorage", // This configures where your cache will be stored
         storeAuthStateInCookie: false, // Set this to "true" if you are having issues on IE11 or Edge
     },
     system: {	
         loggerOptions: {	
             loggerCallback: (level, message, containsPii) => {	
                 if (containsPii) {		
                     return;		
                 }		
                 switch (level) {
                     case LogLevel.Error:
                         console.error(message);
                         return;
                     case LogLevel.Info:
                         console.info(message);
                         return;
                     case LogLevel.Verbose:
                         console.debug(message);
                         return;
                     case LogLevel.Warning:
                         console.warn(message);
                         return;
                     default:
                         return;
                 }	
             }	
         }	
     }
 };

 /**
  * Scopes you add here will be prompted for user consent during sign-in. 
  * By default, MSAL.js will add OIDC scopes (openid, profile, email) to any login request.
  * For more information about OIDC scopes, visit: 
  * https://docs.microsoft.com/azure/active-directory/develop/v2-permissions-and-consent#openid-connect-scopes
  */
 export const loginRequest = {
     scopes: ["https://analysis.windows.net/powerbi/api/GraphQL.Execute.All"]
 };

 /**
  * Add here the scopes to request when obtaining an access token for MS Graph API. For more information, see:
  * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/resources-and-scopes.md
  */
 export const graphConfig = {
     graphMeEndpoint: "https://graph.microsoft.com/v1.0/me",
 };

Yukarıdaki kodda da görebileceğiniz gibi uygulamaya erişmek için doğru kapsamın kullanılması önemlidir. Bizim durumumuzda https://analysis.windows.net/powerbi/api/GraphQL.Execute.All.

Aşağıdaki değerleri Microsoft Entra yönetim merkezindeki değerlerle değiştirin.
- clientId - İstemci olarak da adlandırılan uygulamanın tanımlayıcısı. değerini, kayıtlı Microsoft Entra uygulamasının genel bakış sayfasından daha önce kaydedilen Uygulama (istemci) KimliğiEnter_the_Application_Id_Heredeğiştirin.
- authority - Bu iki bölümden oluşur:
  - Örnek, bulut sağlayıcısının uç noktasıdır. Ulusal bulutlardaki farklı kullanılabilir uç noktaları denetleyin.
  - Kiracı Kimliği, uygulamanın kayıtlı olduğu kiracının tanımlayıcısıdır. Enter_the_Tenant_Info_Here değerini, kayıtlı uygulamanın genel bakış sayfasında daha önce kaydedilen Dizin (kiracı) kimliği değeriyle değiştirin.
- graphQLEndpoint - GraphQL uç noktası için Doku API'si. değerini daha önce kaydedilen GraphQL API uç noktasıyla değiştirin Enter_the_GraphQL_Endpoint_Here .
Dosyayı kaydedin.

Aynı src klasöründe App.js dosyasını açın ve dosyanın içeriğini aşağıdaki kod parçacığıyla değiştirin:

 import React, { useState } from 'react';
 import { PageLayout } from './components/PageLayout';
 import { loginRequest, graphqlConfig } from './authConfig';
 import { ProfileData } from './components/ProfileData';
 import { AuthenticatedTemplate, UnauthenticatedTemplate, useMsal } from '@azure/msal-react';
 import './App.css';
 import Button from 'react-bootstrap/Button';
 import Spinner from 'react-bootstrap/Spinner';

 /**
 * Renders information about the signed-in user or a button to retrieve data about the user
 */
 const ProfileContent = () => {
   const { instance, accounts } = useMsal();
   const [graphqlData, setGraphqlData] = useState(null);
   const [display, setDisplay] = useState(false);

   function RequestGraphQL() {
       // Silently acquires an access token which is then attached to a request for GraphQL data
       instance
           .acquireTokenSilent({
               ...loginRequest,
               account: accounts[0],
           })
           .then((response) => {
               callGraphQL(response.accessToken).then((response) => setGraphqlData(response));
           });
   }

 async function callGraphQL(accessToken) {
   setDisplay(true);
   const query = `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
       }
     }
   }`;
   fetch(graphqlConfig.graphqlEndpoint, {
           method: 'POST',
           headers: {
               'Content-Type': 'application/json',
               'Authorization': `Bearer ${accessToken}`,
           },
           body: JSON.stringify({ 
               query: query
           })
       })
       .then((res) => res.json())
       .then((result) => setGraphqlData(result));
 }

   return (
       <>
           <h5 className="card-title">Welcome {accounts[0].name}</h5>
           <br/>
           {graphqlData ? (
               <ProfileData graphqlData={graphqlData} />
           ) : (
               <Button variant="primary" onClick={RequestGraphQL}>
                   Query Fabric API for GraphQL Data 
                   {display ? (
                         <Spinner
                             as="span"
                             animation="border"
                             size="sm"
                             role="status"
                             aria-hidden="true"
                         />
                     ) : null}
               </Button>
           )}
       </>
   );
 };

 /**
 * If a user is authenticated the ProfileContent component above is rendered. Otherwise a message indicating a user is not authenticated is rendered.
 */
 const MainContent = () => {
   return (
       <div className="App">
           <AuthenticatedTemplate>
               <ProfileContent />
           </AuthenticatedTemplate>

           <UnauthenticatedTemplate>
               <h5>
                   <center>
                       Please sign-in to see your profile information.
                   </center>
               </h5>
           </UnauthenticatedTemplate>
       </div>
   );
 };

 export default function App() {
   return (
       <PageLayout>
           <center>
               <MainContent />
           </center>
       </PageLayout>
   );
 }

Dosyayı kaydedin.

Son olarak, src/components klasörünün altında ProfileData.jsx dosyasını açın ve dosyanın içeriğini aşağıdaki kod parçacığıyla değiştirin:

 import React from "react";
 import ListGroup from 'react-bootstrap/ListGroup'; 
 import Table from 'react-bootstrap/Table';
 /**
  * Renders information about the user obtained from MS Graph 
  * @param props
  */
 export const ProfileData = (props) => {
   const holidays = props.graphqlData.data.publicholidays.items;
   return (
     <Table striped bordered hover responsive>
     <thead>
       <tr>
         <th>Country</th>
         <th>Holiday</th>
         <th>Date</th>
       </tr>
     </thead>
     <tbody>
       {holidays.map((item,i) => (
       <tr key={i}>
         <td>{item.countryOrRegion}</td>
         <td>{item.holidayName}</td>
         <td>{item.date}</td>
       </tr>
       ))}
       </tbody>
     </Table>
 )};

Tüm dosya değişikliklerini kaydedin.
Tercih edilen terminal uygulamanızda React projesinin kök klasörüne gidin ve uygulamayı yerel olarak test etmek için komutunu npm start yürütür.
Uygulama tarayıcınıza uygulamasından http://localhost:3000yüklendikten sonra, kimlik doğrulaması için api'yi uygulamadan çağırma öğreticisinin son bölümündeki adımları izleyin.
Oturum açtıktan sonra GraphQL Verileri için Query Fabric API'sine tıklayın.
Doku'da GraphQL API'sine yapılan başarılı bir kimliği doğrulanmış istek, React istemci uygulamamızda GraphQL sorgusundan Lakehouse'a verileri döndürür:

Hizmet sorumlusu kullanma

Önceki bölümdeki adımların kullanıcı sorumlularına erişim sağlamak için gerekli olsa da GraphQL API'sine bir hizmet sorumlusuyla erişmek de mümkündür:

Benzer izinlere sahip ikinci bir Microsoft Entra uygulaması oluşturmak için önceki bölümdeki adımları izleyin (PowerBI Hizmetiiçin GraphQL.Execute.All kapsamı ). Yeni uygulamada, Sertifikalar ve Gizli Diziler'in altına bir gizli dizi ekleyin. Daha fazla bilgi için bkz. Microsoft Entra uygulamasını kaydetme ve hizmet sorumlusu oluşturma.
Kiracı Yöneticilerinin Dokuda Hizmet Sorumlularının kullanımını etkinleştirdiğinden emin olun. Kiracı Yöneticisi portalında Kiracı Ayarları'na gidin. Geliştirici Ayarları altında Hizmet Sorumluları Doku API'lerini kullanabilir'i etkinleştirin. Bu ayar etkinleştirildiğinde uygulama, rol veya izin ataması için Doku Portalı'nda görünür. Kimlik desteği hakkında daha fazla bilgi bulabilirsiniz.
Hizmet sorumlusunun hem GraphQL API'sine hem de veri kaynağına erişmesi, daha özel olarak GraphQL API'sine yürütme izni ve uygun şekilde veri kaynağında okuma veya yazma erişimi gerekir. Doku Portalı'nda çalışma alanını açın ve API'nin yanındaki üç noktayı seçin. API için izinleri yönet'i ve ardından Kullanıcı ekle'yi seçin. Uygulamayı ekleyin ve Hizmet sorumlusu için gerekli Yürütme izinlerini sağlayacak Sorguları ve Mutasyonları Çalıştır'ı seçin. Test amacıyla hem API hem de veri kaynağı için gerekli izinleri uygulamanın en kolay yolu, uygulamayı hem GraphQL API'sinin hem de veri kaynağı öğelerinin bulunduğu katkıda bulunan rolüne sahip bir çalışma alanı üyesi olarak eklemektir.

Önemli

API'niz için bağlantı seçeneğini tanımlarken, API'nin çoklu oturum açma (SSO) kullanacak şekilde yapılandırıldığından emin olun. Şu anda Hizmet Sorumluları kaydedilmiş kimlik bilgilerini desteklememektedir. Daha fazla bilgi için bkz . Dokuda GraphQL için API oluşturma ve veri ekleme

Hizmet Sorumlusu bir sertifika veya istemci gizli dizisi gerektirdiğinden, son adımda oluşturduğumuz React uygulaması gibi tek sayfalı uygulamalarda (SPA'lar) Microsoft Kimlik Doğrulama Kitaplığı (MSAL) tarafından desteklenmez. Gereksinimlerinize ve kullanım örneklerinize bağlı olarak iyi tanımlanmış yetkilendirme mantığıyla düzgün bir şekilde güvenli hale getirilen bir arka uç hizmetinden yararlanabilirsiniz.

API'nize bir Hizmet Sorumlusu tarafından erişilecek şekilde yapılandırıldıktan sonra, yerel makinenizde basit bir Node.JS uygulaması kullanarak api'nizi yerel olarak test edebilirsiniz:

const { ClientSecretCredential } = require('@azure/identity');

// Define your Microsoft Entra ID credentials
const tenantId = "<YOUR_TENANT_ID>";
const clientId = "<YOUR_CLIENT_ID>";
const clientSecret = "<YOUR_CLIENT_SECRET>"; // Service principal secret value

const scope = "https://api.fabric.microsoft.com/.default"; // The scope of the token to access Fabric

// Create a credential object with service principal details
const credential = new ClientSecretCredential(tenantId, clientId, clientSecret);

// Function to retrieve the token
async function getToken() {
    try {
        // Get the token for the specified scope
        const tokenResponse = await credential.getToken(scope);
        console.log("Access Token:", tokenResponse.token);
    } catch (err) {
        console.error("Error retrieving token:", err.message);
    }
}

Bağımlılıkları (@azure/identity) istediğiniz Node.JS paket yöneticinizle yükledikten, dosyayı gerekli bilgilerle değiştirdikten, kaydedip yürüttükten (node <filename.js> ) sonra Microsoft Entra'dan bir belirteç alabilirsiniz.

Belirteç daha sonra uygun ayrıntıları aldığınız belirteç, yürütmek istediğiniz GraphQL sorgusu ve GraphQL API Uç Noktası ile değiştirerek PowerShell kullanarak GraphQL API'nizi çağırmak için kullanılabilir:

$headers = @{
    Authorization = "Bearer <YOUR_TOKEN>"
    'Content-Type' = 'application/json'
}

$body = @{
    query = @"
    <YOUR_GRAPHQL_QUERY>
"@
}

# Make the POST request to the GraphQL API
$response = Invoke-RestMethod -Uri "<YOUR_GRAPHQL_API_ENDPOINT>" -Method POST -Headers $headers -Body ($body | ConvertTo-Json)

# Output the response
$response | ConvertTo-Json -Depth 10

Alternatif olarak, aynı sonucu elde etmek için cURL kullanabilirsiniz:

curl -X POST <YOUR_GRAPHQL_API_ENDPOINT> \
-H "Authorization: <YOUR_TOKEN>" \
-H "Content-Type: application/json" \
-d '{"query": "<YOUR_GRAPHQL_QUERY(in a single line)>"}'

Yerel test amacıyla Node.JS kodu, belirteci almak ve API'yi tek bir yürütmede çağırmak için ek bir bağımlılıkla (axios) biraz değiştirilebilir:

const { ClientSecretCredential } = require('@azure/identity');
const axios = require('axios');

// Microsoft Entra ID credentials
const tenantId = "<YOUR_TENANT_ID>";
const clientId = "<YOUR_CLIENT_ID>";
const clientSecret = "<YOUR_CLIENT_SECRET>"; // Service principal secret value

// GraphQL API details
const graphqlApiUrl = "YOUR_GRAPHQL_API_ENDPOINT>";
const scope = "https://api.fabric.microsoft.com/.default"; // The scope to request the token for

// The GraphQL query
const graphqlQuery = {
  query: `
  <YOUR_GRAPHQL_QUERY>
  `
};

// Function to retrieve a token and call the GraphQL API
async function fetchGraphQLData() {
  try {
    // Step 1: Retrieve token using the ClientSecretCredential
    const credential = new ClientSecretCredential(tenantId, clientId, clientSecret);
    const tokenResponse = await credential.getToken(scope);
    const accessToken = tokenResponse.token;

    console.log("Access token retrieved!");

    // Step 2: Use the token to make a POST request to the GraphQL API
    const response = await axios.post(
      graphqlApiUrl,
      graphqlQuery,
      {
        headers: {
          'Authorization': `Bearer ${accessToken}`,
          'Content-Type': 'application/json'
        }
      }
    );

    // Step 3: Output the GraphQL response data
    console.log("GraphQL API response:", JSON.stringify(response.data));
    
  } catch (err) {
    console.error("Error:", err.message);
  }
}

// Execute the function
fetchGraphQLData();

Diğer diller

Microsoft Fabric Örnekleri GitHub deposunda GraphQL API'nize bağlanmak için C#, Python ve diğer dil örneklerini bulun.

Aracılığıyla paylaş

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

Önkoşullar

Microsoft Entra uygulaması oluşturma

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

Resmi tatiller API'sine erişmek için React uygulaması yapılandırma

Hizmet sorumlusu kullanma

Diğer diller

Geri Bildirim

Ek kaynaklar

Aracılığıyla paylaş

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

Önkoşullar

Microsoft Entra uygulaması oluşturma

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

Resmi tatiller API'sine erişmek için React uygulaması yapılandırma

Hizmet sorumlusu kullanma

Diğer diller

İlgili içerik

Geri Bildirim

Ek kaynaklar