Partekatu bidez

Canalizaciones de control e implementación de código fuente en API para GraphQL (versión preliminar)

Obtenga información sobre cómo funcionan las canalizaciones de implementación e integración de Git con API para GraphQL en Microsoft Fabric. Este artículo le ayuda a comprender cómo configurar una conexión al repositorio, administrar la API para GraphQL e implementarlas en distintos entornos.

Quién usa el control de código fuente y la implementación

La integración y los pipelines de implementación de Git son esenciales para:

  • Ingenieros de datos que administran configuraciones de Fabric GraphQL API a través del control de versiones y los flujos de trabajo de CI/CD
  • Administradores del área de trabajo de Fabric que coordinan las implementaciones entre áreas de trabajo de Fabric de desarrollo, pruebas y producción
  • Equipos de DevOps que implementan canalizaciones de implementación para las API de Fabric en varios entornos y capacidades
  • Equipos de plataforma que requieren funcionalidades de gobernanza, seguimiento y reversión para los cambios de la API de Fabric

Use las canalizaciones de implementación y control de código fuente cuando necesite administrar las API de GraphQL como parte de un ciclo de vida de desarrollo estructurado con varios entornos.

Nota:

La API para el control de código fuente y la implementación de GraphQL se encuentran actualmente en versión preliminar.

Prerrequisitos

Información general

Fabric ofrece herramientas eficaces para CI/CD (integración continua e implementación continua) y administración del ciclo de vida de desarrollo a través de dos componentes principales: Integración de Git (CI) e canalizaciones de implementación (CD). Las áreas de trabajo sirven como componentes centrales para las fases de sincronización e implementación de Git.

Integración de Git (CI): sincroniza los elementos del área de trabajo (por ejemplo, código, configuraciones, API) con repositorios de control de versiones, habilitando el control de versiones y el seguimiento de cambios a través de Git.

Canalizaciones de implementación (CD): habilita la creación de fases (por ejemplo, desarrollo, prueba, producción) con áreas de trabajo vinculadas. Los elementos admitidos en cada fase se replican automáticamente en las fases posteriores y los cambios en una implementación de desencadenador de área de trabajo en una canalización de versión. Puede configurar la canalización para asegurarse de que los cambios se prueban e implementan de forma eficaz en todos los entornos.

Fabric admite varios flujos de trabajo de CI/CD adaptados a escenarios comunes. Para obtener más información, consulte Opciones de flujo de trabajo de CI/CD en Fabric.

Nota:

Solo se copian los metadatos durante la implementación; y los datos no se copian.

Los elementos del área de trabajo se almacenan en el repositorio Git asociado como Infraestructura como Código (IaC). Los cambios de código en el repositorio pueden desencadenar la implementación en canalizaciones. Este método permite que los cambios de código se repliquen automáticamente entre fases con fines de prueba y versión de producción.

Métodos de autenticación del origen de datos

Al crear la API para GraphQL, puede elegir cómo autentican y acceden los clientes a los orígenes de datos. Esta opción tiene implicaciones significativas para las canalizaciones de implementación y el comportamiento de enlace automático. Comprender estos métodos de autenticación es esencial para planear el flujo de trabajo de CI/CD. Para obtener más información sobre el enlace automático y el proceso de implementación, consulte Descripción del proceso de implementación.

Hay dos opciones de conectividad disponibles al conectar orígenes de datos a la API para GraphQL: inicio de sesión único (SSO) y credenciales guardadas.

Captura de pantalla de las opciones de conexión de GraphQL a orígenes de datos.

Inicio de sesión único (SSO)

Con el inicio de sesión único, los clientes de API usan sus propias credenciales para acceder a las fuentes de datos. El usuario de API autenticado debe tener permisos para la API y el origen de datos subyacente.

Utilice SSO cuando:

  • Exposición de orígenes de datos de Fabric (casas de datos, almacenes, puntos de conexión de SQL Analytics)
  • Quiere que los usuarios accedan a los datos en función de sus permisos individuales.
  • Necesita seguridad de nivel de fila u otras directivas de acceso a datos para aplicarlas por usuario.

Requisitos de permiso:

  • Los usuarios de la API necesitan permisos de ejecución en GraphQL API (ejecutar consultas y mutaciones)
  • Los usuarios de api necesitan permisos de lectura o escritura en el origen de datos
  • Como alternativa, agregue usuarios como miembros del área de trabajo con el rol Colaborador donde se encuentran tanto la API como el origen de datos.

Comportamiento de enlace automático en canalizaciones de implementación: Al implementar una API mediante SSO desde el área de trabajo de origen (por ejemplo, Desarrollo) en el área de trabajo de destino (por ejemplo, Prueba):

  • El origen de datos y GraphQL API se implementan en el área de trabajo de destino.
  • La API del área de trabajo de destino se enlaza automáticamente a la copia del origen de datos local en el área de trabajo de destino.
  • Cada entorno (desarrollo, prueba, producción) usa su propia instancia de origen de datos.

Nota:

Existen limitaciones específicas al utilizar SSO con Endpoints de SQL Analytics. Consulte Limitaciones actuales para obtener más información.

Credenciales guardadas

Con las credenciales guardadas, una única credencial compartida se autentica entre la API y los orígenes de datos. Los usuarios de api solo necesitan acceso a la propia API, no a los orígenes de datos subyacentes.

Use las credenciales guardadas cuando:

  • Exposición de orígenes de datos de Azure (Azure SQL Database, bases de datos externas)
  • Quiere una administración simplificada de permisos (los usuarios solo necesitan acceso a la API)
  • Todos los usuarios de la API deben acceder a los mismos datos con los mismos permisos.
  • Necesita credenciales coherentes en todas las solicitudes de API.

Requisitos de permiso:

  • Los usuarios de la API solo necesitan permisos de ejecución en GraphQL API (ejecutar consultas y mutaciones)
  • La propia credencial guardada debe tener los permisos adecuados en el origen de datos.
  • Los desarrolladores que implementan la API deben tener acceso a la credencial guardada.

Comportamiento de enlace automático en canalizaciones de implementación: Al implementar una API mediante credenciales guardadas desde el área de trabajo de origen (Desarrollo) en el área de trabajo de destino (prueba):

  • El origen de datos se implementa en el espacio de trabajo de destino.
  • La API del área de trabajo de destino permanece conectada al origen de datos en el área de trabajo de origen (desarrollo)
  • No se produce el enlace automático: la API implementada continúa usando la credencial guardada que apunta al origen de datos original.
  • Debe volver a configurar manualmente las conexiones o crear nuevas credenciales guardadas en cada entorno de destino.

Importante

Una vez que elija un método de autenticación para la API, se aplica a todos los orígenes de datos agregados a esa API. No puedes combinar SSO y credenciales guardadas en la misma API.

Conexiones entre áreas de trabajo

Si la API del área de trabajo de origen (Desarrollo) se conecta a un origen de datos en otra área de trabajo, la API implementada en el área de trabajo de destino (Prueba) permanece conectada a ese origen de datos externo independientemente del método de autenticación. El enlace automático solo funciona cuando la API y el origen de datos están en el mismo área de trabajo de origen.

En el diagrama siguiente se muestran estos escenarios de implementación:

Captura de pantalla de la canalización para varias conexiones y escenarios de origen de datos.

Para obtener más información sobre cómo configurar estos métodos de autenticación al crear la API, consulte Conexión a un origen de datos.

API para la integración de GraphQL con Git

Fabric API for GraphQL admite la integración de Git, lo que le permite administrar las API de GraphQL como código dentro del sistema de control de versiones. Esta integración proporciona historial de versiones, colaboración a través de ramas y solicitudes de incorporación de cambios, la capacidad de revertir los cambios y una pista de auditoría completa de las modificaciones de api. Al tratar la configuración de GraphQL API como infraestructura como código (IaC), puede aplicar procedimientos recomendados de desarrollo de software a la capa de acceso a datos.

La integración de Git es esencial para:

  • Control de versiones: realice un seguimiento de todos los cambios en el esquema de GraphQL, las conexiones del origen de datos y las relaciones a lo largo del tiempo.
  • Colaboración: Trabajar con miembros del equipo mediante ramas, solicitudes de incorporación de cambios y revisiones de código
  • Funcionalidad de reversión: revertir a configuraciones de API anteriores cuando surjan problemas
  • Promoción del entorno: use Git como origen de la verdad para implementar API en entornos.

Conexión del área de trabajo a Git

Para habilitar la integración de Git para las API de GraphQL:

  1. Abra la configuración del Espacio de trabajo que contiene su API para GraphQL.
  2. Configuración de la conexión de Git al repositorio (Azure DevOps, GitHub u otro proveedor de Git)
  3. Una vez conectado, todos los elementos del área de trabajo, incluidas las API de GraphQL, aparecen en el panel de control de código fuente .

Para obtener instrucciones detalladas sobre la configuración, consulte Introducción a la integración de Git.

Captura de pantalla del estado del área de trabajo y del control de código fuente.

Confirmación y sincronización de las API de GraphQL

Después de conectarse a Git, puede confirmar las configuraciones de API para GraphQL en el repositorio. Cada confirmación crea una instantánea de la definición de la API, entre las que se incluyen:

  • Definiciones de esquema de GraphQL
  • Conexiones de origen de datos y configuración de autenticación
  • Configuraciones de relaciones
  • Definiciones de consulta y mutación

Una vez confirmada, las API de GraphQL aparecen en el repositorio de Git con una jerarquía de carpetas estructuradas. Desde este punto, puede aprovechar los flujos de trabajo de Git estándar, como la creación de solicitudes de incorporación de cambios, la administración de ramas y la colaboración con el equipo mediante revisiones de código. Para obtener más información sobre cómo trabajar con ramas, consulte Administración de ramas.

Representación de GraphQL API en Git

Cada elemento de API para GraphQL se almacena en Git con una estructura de carpetas bien definida que representa todos los aspectos de la configuración de la API:

Captura de pantalla de la representación de la estructura de archivos en Git para GraphQL.

Los archivos de definición de API contienen todos los metadatos necesarios para volver a crear graphQL API en cualquier área de trabajo de Fabric. Esto incluye definiciones de esquema, asignaciones de orígenes de datos y opciones de configuración. Cuando se sincroniza desde Git de nuevo a un área de trabajo de Fabric, el sistema usa estos archivos de definición para restaurar la API exactamente como estaba cuando se confirmaba:

Captura de pantalla de las definiciones de API para GraphQL almacenadas en Git.

Trabajar con archivos de definición de API:

El formato de definición de GraphQL API sigue los estándares de Infraestructura como Código (IaC) de Fabric. Puede ver y editar estos archivos directamente en el repositorio de Git, aunque la mayoría de las modificaciones se deben realizar a través del portal de Fabric para garantizar la validez del esquema. Los archivos de definición son especialmente útiles para:

  • Revisiones de código: Los miembros del equipo pueden revisar los cambios de API en los pull requests.
  • Documentación: los archivos sirven como documentación de la estructura de API.
  • Automatización: las canalizaciones de CI/CD pueden leer estos archivos para comprender las configuraciones de API.
  • Recuperación ante desastres: las definiciones de API completas se conservan en el control de versiones

Para obtener información detallada sobre el formato de definición, la sintaxis y los ejemplos de GraphQL API, consulte la documentación de las API del plano de control de Fabric:

API para GraphQL en la canalización de implementación

Las canalizaciones de implementación permiten promover las configuraciones de API para GraphQL entre entornos (normalmente desarrollo, prueba y producción). Al implementar una API para GraphQL a través de una canalización, solo se copian los metadatos de la API, incluidas las definiciones de esquema, las conexiones de origen de datos y las configuraciones de relación. Los datos reales permanecen en los orígenes de datos conectados y no se copian durante la implementación.

Consideraciones clave sobre la implementación:

Antes de implementar, comprenda cómo afectan los métodos de autenticación y la organización del área de trabajo a la implementación:

  • Las API que usan single Sign-On (SSO) pueden enlazarse automáticamente a orígenes de datos locales en el área de trabajo de destino (cuando el origen de datos también se implementó desde el mismo área de trabajo de origen).
  • Las API que usan credenciales guardadas no se conectan automáticamente y permanecen conectadas al origen de datos del área de trabajo de origen
  • Los orígenes de datos entre áreas de trabajo nunca se enlazarán automáticamente, independientemente del método de autenticación.

Para obtener una descripción completa del proceso de implementación, consulte Descripción del proceso de implementación.

Implementación de la API para GraphQL

Para implementar la API de GraphQL mediante canalizaciones de implementación:

  1. Cree una nueva canalización de implementación o abra una existente. Para obtener instrucciones detalladas, consulte Introducción a las canalizaciones de implementación.

  2. Asigne áreas de trabajo a las fases de canalización (desarrollo, prueba, producción) en función de la estrategia de implementación. Cada fase debe tener un área de trabajo dedicada.

  3. Revisar y comparar elementos entre fases. La canalización muestra cuáles APIs de GraphQL han cambiado, lo cual se indica por los recuentos de elementos en las áreas resaltadas. Esta comparación le ayuda a comprender lo que se verá afectado por la implementación.

    Captura de pantalla de la canalización que ilustra el estado de los elementos en cada fase de desarrollo.

  4. Seleccione las API de GraphQL y los elementos relacionados (como orígenes de datos conectados) que quiera implementar. A continuación, seleccione Implementar para moverlos a la siguiente fase.

    Captura de pantalla de la canalización que muestra los elementos seleccionados que deben implementarse.

  5. Revise el cuadro de diálogo de confirmación de implementación, que muestra todos los elementos a punto de implementarse. Seleccione Implementar para continuar.

    Captura de pantalla de la canalización que muestra el mensaje de confirmación de implementación.

Limitaciones actuales

Al implementar API para GraphQL a través de canalizaciones de implementación, el enlace automático tiene las siguientes limitaciones:

  • Elementos secundarios: el enlace automático no funciona cuando la API se conecta a un punto de conexión de SQL Analytics que es un elemento secundario de un origen de datos principal (como un Lakehouse). La API implementada permanece conectada al punto de conexión del área de trabajo de origen.

  • Credenciales guardadas: las API que usan el método de autenticación Credenciales guardadas no admiten el enlace automático. La API permanece conectada al origen de datos del área de trabajo de origen después de la implementación.

Para obtener información detallada sobre los métodos de autenticación y su comportamiento de enlace automático, consulte Métodos de autenticación de origen de datos.

Contenido relacionado

  • Last updated on