Conectar aplicaciones a la API de Fabric para GraphQL

Artículo
11/20/2024

Nota:

La API de Microsoft Fabric para GraphQL está en versión preliminar.

Para conectar una aplicación a una API para GraphQL, necesita tres informaciones importantes: un identificador de cliente, el identificador de inquilino y la dirección del punto de conexión de GraphQL en Fabric. En las secciones siguientes se muestra cómo crear y recuperar todos los datos que necesita y cómo acceder a la API mediante una aplicación de ejemplo.

Requisitos previos

Actualmente, la API para GraphQL requiere que las aplicaciones utilicen Microsoft Entra para la autenticación. La aplicación debe registrarse y configurarse adecuadamente para realizar llamadas API en Fabric. Para obtener más información, vea Crear una aplicación de Microsoft Entra en Azure.
El usuario autenticado que llama a la API debe ser miembro del área de trabajo donde tanto la API como los elementos del origen de datos se encuentran con un rol colaborador. Para más información, consulte Proporcionar acceso a los usuarios a las áreas de trabajo en Power BI.
Antes de conectar una aplicación, debe tener una API para GraphQL en Fabric. Para obtener más información, consulte Crear una API para GraphQL en Fabric y añadir datos.

Crear una aplicación de Microsoft Entra

En los pasos siguientes, se muestra cómo configurar la compatibilidad con una aplicación ReactJS en Microsoft Entra.

Inicie sesión en Azure Portal.
Busque y seleccione Microsoft Entra ID.
En la lista Administrar, seleccione Registros de aplicación.
Seleccione Nuevo registro.
Rellene la información necesaria:
- Nombre: escriba un nombre para la aplicación.
- Tipos de cuentas compatibles: seleccione qué cuentas desea que admita la aplicación.
- (Opcional) URI de redirección: escriba un URI si es necesario.
Seleccione Registrar. Los valores de Id. de aplicación (cliente) e Id. de directorio (inquilino) se muestran en el cuadro Resumen. Registre estos valores según sea necesario más adelante.
En la lista Administrar, seleccione Permisos de API y a continuación Agregar un permiso.
Agregue el servicio PowerBI, seleccione Permisos delegados y seleccione el permiso Item.Execute.All. Asegúrese de que el consentimiento del administrador no es necesario.
En la lista Administrar, seleccione Autenticación>Agregar una plataforma, >Aplicación de página única.
Para fines de desarrollo local, agregue http://localhost:3000 en URI de redirección y confirme que la aplicación está habilitada para el flujo de código de autorización con clave de prueba para Intercambio de código (PKCE). Seleccione el botón Configurar para guardar los cambios. En caso de que la aplicación reciba un error relacionado con las solicitudes entre orígenes, agregue la plataforma de aplicaciones móviles y de escritorio en el paso anterior con el mismo URI de redirección.
Vuelva a Autorización, desplácese hacia abajo hasta Configuración avanzada y, en Permitir flujos de cliente públicos, seleccione Sí para Habilitar los siguientes flujos de escritorio y móviles.

Configuración de una API de GraphQL de ejemplo para el acceso a aplicaciones

En este ejemplo, creamos una API de GraphQL para exponer datos de ejemplo de Lakehouse a los clientes.

Desde la página principal del portal de Fabric, seleccione Ingeniería de datos en la lista de cargas de trabajo.
En la experiencia de Ingeniero de datos, seleccione Usar un ejemplo y, en Lakehouse, seleccione Días festivos públicos para crear automáticamente una nueva instancia de Lakehouse con datos de días festivos públicos.
Siguiendo los pasos descritos en Creación de una API para GraphQL, cree una nueva API de GraphQL y seleccione la instancia de Lakehouse que creó. Agregue la tabla días festivos públicos para permitir que los clientes accedan a estos datos.

Pruebe la API de GraphQL en el editor de API mediante la siguiente consulta de ejemplo. Es la misma consulta que usamos en nuestra aplicación cliente de React:

 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
     }
   }
 }

Seleccione Copiar punto de conexión en la barra de herramientas del elemento de API.
En la pantalla Copiar vínculo, seleccione Copiar.
Como Id. de cliente e Id. de inquilino de la aplicación Microsoft Entra que se registró anteriormente, copie el URI del punto de conexión, ya que es necesario más adelante.

Configuración de una aplicación React para acceder a la API de días festivos públicos

Usamos una aplicación React existente como punto de partida. Siga todos los pasos del tutorial Creación de una aplicación de página única de React y preparación para la autenticación para crear un proyecto de React con autenticación Microsoft Entra ya configurado, incluidos archivos y carpetas adicionales necesarios para agregarse a la estructura del proyecto. Solo es necesario cambiar tres archivos para adaptar la aplicación para nuestro caso de uso de GraphQL.

En la carpeta src, abra el archivo authConfig.js y sustituya el contenido del archivo por el siguiente fragmento de código:

 /*
  * 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/Item.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",
 };

Como puede ver en el código anterior, es importante usar el ámbito correcto para acceder a la aplicación. En nuestro caso https://analysis.windows.net/powerbi/api/Item.Execute.All.

Importante

Los ámbitos pueden cambiar durante la versión preliminar de la API de Microsoft Fabric para GraphQL.

Reemplace los siguientes valores por los del Centro de administración de Microsoft Entra.
- clientId - El identificador de la aplicación, también denominado cliente. Reemplace Enter_the_Application_Id_Here por el valor de Id. de la aplicación (cliente) que se registró anteriormente en la página de resumen de la aplicación Microsoft Entra registrada.
- authority - Se compone de dos partes:
  - La instancia es el punto de conexión del proveedor de nube. Consulte los diferentes puntos de conexión disponibles en nubes nacionales.
  - El Id. de inquilino es el identificador del inquilino en el que está registrada la solicitud. Reemplace Enter_the_Tenant_Info_Here por el valor de identificador del directorio (inquilino) que se ha registrado antes en la página de información general de la aplicación registrada.
- graphQLEndpoint - API de Fabric para el punto de conexión de GraphQL Reemplace Enter_the_GraphQL_Endpoint_Here por el punto de conexión de la API de GraphQL registrado anteriormente.
Guarde el archivo.

En la misma carpeta src, abra el archivo App.js y sustituya el contenido del archivo por el siguiente fragmento de código:

 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>
   );
 }

Guarde el archivo.

Por último, en la carpeta src/components, abra el archivo ProfileData.jsx y reemplace el contenido del archivo por el siguiente fragmento de código:

 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>
 )};

Guarde todos los cambios.
En la aplicación de terminal que prefiera, vaya a la carpeta raíz del proyecto React y ejecute el comando npm start para probar la aplicación localmente.
Una vez que la aplicación se cargue en el explorador desde http://localhost:3000, siga los pasos descritos en la última parte del tutorial Llamada a la API desde la aplicación para autenticarse.
Después de iniciar sesión, haga clic en el botón Query Fabric API for GraphQL Data (Api de Query Fabric para datos de GraphQL).

Captura de pantalla de la aplicación de ejemplo de React después de iniciar sesión.

Una solicitud autenticada correcta a la API de GraphQL en Fabric devuelve los datos de la consulta GraphQL a Lakehouse en nuestra aplicación cliente de React:

Uso de una entidad de servicio

Aunque los pasos de la sección anterior son necesarios para proporcionar acceso a las entidades de seguridad de usuario, también es posible acceder a GraphQL API con una entidad de servicio:

Siga los pasos de la sección anterior para crear una segunda aplicación de Microsoft Entra con permisos similares (ámbito Item.Execute.All para el servicio PowerBI). En la nueva aplicación, agregue un secreto de cliente en Certificados y secretos; para obtener más información, consulte Registrar una aplicación de Microsoft Entra y crear una entidad de servicio.
Asegúrese de que los administradores de inquilinos han habilitado el uso de entidades de servicio en Fabric. En el portal de administración de inquilinos, vaya a Configuración del inquilino. En Configuración del desarrollador habilite Las entidades de servicio pueden usar las API de Fabric. Con esta configuración habilitada, la aplicación estará visible en Fabric Portal para la asignación de roles o permisos. Puede encontrar más información sobre la Compatibilidad con Identity.
La entidad de servicio necesitará acceso tanto a la API de GraphQL como a la fuente de datos, más específicamente, permiso Ejecutar para la API de GraphQL y acceso de lectura o escritura requerido en la fuente de datos elegida según corresponda. En Fabric Portal, abra el área de trabajo y seleccione los puntos suspensivos junto a API. Seleccione Administrar permisos para la API y, después, Agregar usuario. Agregue la aplicación y seleccione Ejecutar consultas y mutaciones, lo cual le proporcionará los permisos necesarios Ejecutar a la entidad de servicio. Con fines de prueba, la manera más sencilla de implementar los permisos necesarios para la API y el origen de datos consiste en agregar la aplicación como miembro del área de trabajo con un rol de colaborador donde se encuentran tanto la API de GraphQL como elementos de origen de datos.

Importante

Al definir la opción de conectividad para la API, asegúrese de que la API está configurada para usar el inicio de sesión único (SSO). Actualmente, las entidades de servicio no admiten credenciales guardadas. Para obtener más información, consulte Crear una API para GraphQL en Fabric y añadir datos

Dado que una entidad de servicio requiere un certificado o un secreto de cliente, no es compatible con la Biblioteca de autenticación de Microsoft (MSAL) en aplicaciones de página única (SPA), como la aplicación React que compilamos en el último paso. Puede aprovechar un servicio back-end correctamente protegido con lógica de autorización bien definida en función de sus requisitos y casos de uso.

Una vez que una entidad de servicio haya configurado la API para acceder a ella, puede probarla localmente mediante una sencilla aplicación de Node.JS en la máquina local:

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);
    }
}

Después de instalar las dependencias (@azure/identity) con el administrador de paquetes de Node.JS de su elección, modificando el archivo con la información necesaria, guardando y ejecutándolo (node <filename.js>), podrá recuperar un token de Microsoft Entra.

Después, el token se puede usar para invocar la API de GraphQL mediante PowerShell reemplazando los detalles adecuados por el token que acaba de recuperar, la consulta de GraphQL que desea ejecutar y el punto de conexión de la API de GraphQL:

$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

Como alternativa, puede usar cURL para lograr el mismo resultado:

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)>"}'

Para realizar pruebas locales, el código de Node.JS se puede modificar ligeramente con una dependencia adicional (axios) para recuperar el token e invocar la API en una sola ejecución:

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();

Otros idiomas

Busque C#, Python y otros ejemplos de lenguaje para conectarse a su API de GraphQL en el repositorio de GitHub de ejemplos de Microsoft Fabric.

Compartir a través de

Conectar aplicaciones a la API de Fabric para GraphQL

Requisitos previos

Crear una aplicación de Microsoft Entra

Configuración de una API de GraphQL de ejemplo para el acceso a aplicaciones

Configuración de una aplicación React para acceder a la API de días festivos públicos

Uso de una entidad de servicio

Otros idiomas

Comentarios

Recursos adicionales

Compartir a través de

Conectar aplicaciones a la API de Fabric para GraphQL

Requisitos previos

Crear una aplicación de Microsoft Entra

Configuración de una API de GraphQL de ejemplo para el acceso a aplicaciones

Configuración de una aplicación React para acceder a la API de días festivos públicos

Uso de una entidad de servicio

Otros idiomas

Contenido relacionado

Comentarios

Recursos adicionales