Conectar aplicaciones a la API de Fabric para GraphQL

La conexión de aplicaciones a la API de Fabric para GraphQL permite a las aplicaciones web, móviles y back-end consultar orígenes de datos de Fabric mediante una API moderna y eficaz. Esta integración requiere una autenticación adecuada a través del identificador de Entra de Microsoft y la configuración de la aplicación para llamar al punto de conexión de GraphQL de forma segura.

En este artículo se explica cómo conectar una aplicación react a Fabric GraphQL API mediante:

1. Creación y configuración de una aplicación de Microsoft Entra para la autenticación
2. Configuración de graphQL API de ejemplo en Fabric con datos que se van a consultar
3. Clonación y configuración de una aplicación react completa desde GitHub
4. Prueba de la conexión autenticada

El tutorial usa React, pero los conceptos de autenticación se aplican a cualquier lenguaje. Para obtener ejemplos en C#, Python u otros lenguajes, consulte el repositorio de GitHub ejemplos de Microsoft Fabric.

Quién necesita conectar aplicaciones

La configuración de la conexión de la aplicación es esencial para:

• Desarrolladores web y móviles que crean aplicaciones que consumen datos de almacenes de lago y almacenes de Fabric.
• Desarrolladores de integración que conectan datos de Fabric a aplicaciones personalizadas y flujos de trabajo automatizados
• Desarrolladores de back-end que crean servicios que se integran con la plataforma de análisis unificada de Fabric
• Ingenieros de datos que configuran flujos de trabajo de procesamiento de datos automatizados que consumen datos de Fabric a través de API

Use esta guía cuando necesite autenticar y autorizar aplicaciones para acceder a las API de Fabric GraphQL.

Requisitos previos

• Herramientas de desarrollo: necesita Node.js (versión LTS) y Visual Studio Code instalados en el equipo.

• Antes de conectar una aplicación, asegúrese de que tiene una API para GraphQL en Fabric. Para obtener más información, consulte Crear una API para GraphQL en Fabric y añadir datos.

• La API para GraphQL requiere que las aplicaciones usen Microsoft Entra para la autenticación. Registre y configure la aplicación para realizar llamadas API en Fabric. Para obtener más información, vea Crear una aplicación de Microsoft Entra en Azure.

• La credencial autenticada (entidad de servicio, entidad de servicio o identidad administrada) que llama a la API necesita permisos de ejecución para graphQL API (opción Ejecutar consultas y mutaciones al agregar permisos de acceso directo). Si usa el inicio de sesión único (SSO) como opción de conectividad en la API, asegúrese de que la credencial tiene permisos de lectura o escritura en el origen de datos elegido. Para obtener más información, consulte Conexión a un origen de datos y compilación del esquema.

Resumen de autenticación y permisos

El acceso a GraphQL API requiere la autenticación y autorización adecuadas tanto en el nivel de API como en el nivel de origen de datos subyacente. Puede autenticarse mediante un principal de usuario (que representa a un usuario individual) o un principal de servicio (que representa una aplicación o servicio). Para la conectividad del origen de datos, puede usar el inicio de sesión único (SSO) donde se pasa la identidad del autor de la llamada al origen de datos o las credenciales guardadas en las que se usa una conexión preconfigurada.

En la tabla siguiente se resumen los distintos escenarios de autenticación admitidos y los permisos mínimos necesarios para los clientes que acceden a GraphQL API:

Autor de la llamada API	Conectividad de origen de datos	Permisos obligatorios de GraphQL API	Permisos obligatorios del origen de datos	Ámbito de la aplicación Microsoft Entra
Entidad de seguridad de usuario (UPN)	Inicio de sesión único (SSO)	Ejecutar consultas y mutaciones en el nivel de API	Permisos de lectura y escritura adecuados concedidos al UPN en el origen de datos	GraphQLApi.Execute.All
Entidad de servicio (SPN)	Inicio de sesión único (SSO)	Ejecutar consultas y mutaciones en el nivel de API	Permisos de lectura y escritura adecuados concedidos a la SPN en el origen de datos	No es aplicable
Entidad de seguridad de usuario (UPN)	Credenciales guardadas	Ejecutar consultas y mutaciones en el nivel de API	Permisos de lectura y escritura adecuados concedidos a la credencial guardada (conexión) en el origen de datos	GraphQLApi.Execute.All
Entidad de servicio (SPN)	Credenciales guardadas	Ejecutar consultas y mutaciones en el nivel de API	Permisos de lectura y escritura adecuados concedidos a la SPN en el origen de datos	No es aplicable

Crear una aplicación de Microsoft Entra

Para que su aplicación pueda llamar a la API de Fabric GraphQL, debe registrarla en Microsoft Entra ID. Este registro crea una identidad para la aplicación y define los permisos que necesita. El proceso de registro genera un identificador de cliente (identificador de aplicación) y establece el flujo de autenticación que usa la aplicación para obtener tokens de acceso.

En el caso de las aplicaciones React, configure las opciones de aplicación de página única (SPA) que usan el flujo PKCE, un método de autenticación seguro diseñado para aplicaciones basadas en explorador en las que los secretos de cliente no se pueden almacenar de forma segura.

1. Registro de una aplicación mediante los pasos descritos en Inicio rápido: Registro de una aplicación con la plataforma de identidad de Microsoft.

2. Los valores de Id. de aplicación de aplicación de Microsoft Entra (cliente) e Id. de directorio (inquilino) aparecen en el cuadro Resumen. Registre estos valores porque los necesita al configurar la aplicación React.

3. Configure los permisos de API para que la aplicación pueda acceder a Fabric GraphQL API. En la lista Administrar, seleccione permisos de APIy luego Agregar permiso.

4. Agregue el servicio PowerBI, seleccione Permisos delegados y seleccione GraphQLApi.Execute.All permisos. Este permiso permite a la aplicación ejecutar consultas y mutaciones en nombre del usuario que ha iniciado sesión. Confirme que el consentimiento del administrador no es necesario.

5. Vuelva a la lista Administrar y seleccione Autenticación>Agregar una> de plataforma.

6. 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. Si la aplicación encuentra un error relacionado con las solicitudes entre orígenes, agregue la plataforma aplicaciones móviles y de escritorio en el paso anterior con el mismo URI de redirección.

7. Vuelva a Autenticación, desplácese hasta Configuración avanzada y, en Permitir flujos de clientes públicos, seleccione Sí para Habilitar los siguientes flujos de dispositivos móviles y de escritorio.

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

Con la aplicación de Microsoft Entra registrada, necesita una API de GraphQL en Fabric para consultar. En esta sección se explica cómo crear una API de ejemplo mediante el conjunto de datos de días festivos públicos de Fabric. Esto le proporciona una API de trabajo para probar la autenticación y la recuperación de datos sin necesidad de configurar sus propios orígenes de datos.

La API de ejemplo expone datos festivos de una tabla de Lakehouse, que la aplicación React consulta para mostrar días festivos públicos.

1. Desde la página principal del portal de Fabric, seleccione Ingeniería de datos en la lista de cargas de trabajo.

2. En la experiencia de ingeniería 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.

   

3. Siga los pasos descritos en Creación de una API para GraphQL para crear una nueva GRAPHQL API y seleccionar la instancia de Lakehouse que creó. Agregue la tabla días festivos públicos para que los clientes puedan acceder a estos datos.

   

4. Antes de compilar la aplicación React, compruebe que la API funciona correctamente mediante la prueba en el editor de API. Use la consulta siguiente: esta es la misma consulta que ejecuta la aplicación React más adelante:

    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. Seleccione Copiar punto de conexión en la barra de herramientas del elemento de API.

   

6. En la pantalla Copiar vínculo, seleccione Copiar.

   

7. Registre el identificador de cliente y el identificador de inquilino de la aplicación Microsoft Entra y el URI del punto de conexión. Necesita estos valores al configurar la aplicación React.

Clonación y configuración de la aplicación React

Ahora que tiene configurada la aplicación Microsoft Entra y graphQL API, puede configurar una aplicación react para conectarse a ellas. La aplicación usa la Biblioteca de autenticación de Microsoft (MSAL) para controlar la autenticación y realiza solicitudes de GraphQL con tokens de portador.

1. Clone el repositorio de ejemplos de GitHub:

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

2. Vaya a la carpeta de la aplicación React:

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

   La carpeta contiene una aplicación React completa. Solo tiene que editar src/authConfig.js para configurar el punto de conexión y las credenciales específicos.

3. Abra el proyecto en el editor de código:

   code .
   

4. En el editor, vaya a la src carpeta y abra authConfig.js.

5. Reemplace los siguientes valores de marcador de posición por tus detalles específicos.

   • Enter_the_GraphQL_Endpoint_Here - Sustituir por el endpoint de tu API GraphQL desde Configurar una API de GraphQL de ejemplo para el acceso a la aplicación
   • Enter_the_Application_Id_Here- Reemplace con su ID de aplicación (cliente) de la aplicación 'Create a Microsoft Entra'.
   • Enter_the_Tenant_Info_Here- Reemplace por el identificador de directorio (inquilino) de Creación de una aplicación de Microsoft Entra.

   Importante

   En el mismo archivo, la loginRequest constante incluye el ámbito https://analysis.windows.net/powerbi/api/GraphQLApi.Execute.All. Este ámbito exacto es necesario para acceder a las API de Fabric GraphQL. No quite ni modifique este ámbito; De lo contrario, se produce un error en la autenticación.

6. Guarde el archivo.

7. En el terminal, vaya a la carpeta raíz del proyecto y ejecute:

   npm install
   

   Esto instala todas las dependencias necesarias.

Prueba de la aplicación

Con la aplicación configurada, ejecútelo localmente para comprobar que todo funciona correctamente:

1. En el terminal, ejecute:

   npm start
   

   Este comando inicia el servidor de desarrollo y abre la aplicación en el explorador.

2. Complete el flujo de autenticación cuando la aplicación se cargue en http://localhost:3000. Siga los pasos de inicio de sesión descritos en la sección tutorial Llamada a la API desde la aplicación.

3. Después de iniciar sesión correctamente, seleccione el botón Query Fabric API for GraphQL Data (API de Query Fabric para GraphQL Data ). Esto desencadena el flujo de autenticación, adquiere un token de acceso y ejecuta la consulta graphQL en la API de Fabric.

   

4. Si todo está configurado correctamente, la aplicación muestra días festivos públicos en una tabla. Esto confirma que:

   • La aplicación Microsoft Entra tiene los permisos correctos.
   • El token de acceso se adquirió correctamente
   • GraphQL API ha autenticado la solicitud.
   • La consulta ejecutada sobre los datos del Lakehouse

   

Otros comandos de npm

Más allá de npm start y npm install, puede usar estos comandos comunes de npm para distintos escenarios de desarrollo.

• npm run dev - Forma alternativa de iniciar el servidor de desarrollo
• npm run build - Crear una compilación de producción optimizada de tu aplicación
• npm run preview - Probar la compilación de producción localmente antes de implementar
• npm test - Ejecutar pruebas automatizadas para comprobar que el código funciona correctamente.

Contenido relacionado

Ahora que tiene una aplicación en funcionamiento conectada a fabric GraphQL API, explore estos recursos para crear soluciones más sofisticadas:

• Creación de una API para GraphQL en Fabric y adición de datos : aprenda a exponer sus propios orígenes de datos
• Consulta de varios orígenes de datos en Fabric API para GraphQL : combinación de datos de orígenes diferentes en una sola consulta
• Editor de Fabric API para GraphQL : prueba y desarrollo de consultas de forma interactiva
• Creación de una aplicación de Microsoft Entra en Azure : guía detallada para el registro de aplicaciones de producción
• Ejemplos de Microsoft Fabric GraphQL : examinar ejemplos en varios idiomas