Compartir vía

Fabric API for GraphQL schema view and schema explorer (API de Fabric para GraphQL schema view and schema explorer)

Fabric API para GraphQL genera automáticamente un esquema que define la estructura de la API en función de los orígenes de datos que conecte. El esquema, escrito en GraphQL Schema Definition Language (SDL), describe todos los tipos, campos, consultas y mutaciones disponibles que los clientes pueden usar para interactuar con los datos.

La vista de esquema proporciona una vista de solo lectura basada en texto del esquema graphQL completo, mientras que el explorador de esquemas del panel izquierdo le permite navegar, inspeccionar y modificar los objetos expuestos a través de la API. Juntas, estas herramientas le ayudan a comprender la estructura de la API y controlar qué datos son accesibles para los clientes.

Quién usa la vista de esquema

La vista de esquema y el explorador son útiles para:

  • Ingenieros de datos que configuran qué objetos lakehouse y de almacenamiento de Fabric exponen a través de GraphQL
  • Desarrolladores de aplicaciones que detectan tipos de datos, campos y relaciones disponibles de Fabric antes de escribir consultas
  • Colaboradores del área de trabajo de Fabric que comprenden y administran la estructura de acceso a datos para su área de trabajo
  • Desarrolladores de BI que revisan las relaciones de datos de Fabric al compilar aplicaciones de análisis personalizadas

Use la vista de esquema para explorar la estructura de la API y el explorador de esquemas para modificar qué objetos de datos se exponen.

Acceso y exploración del esquema

Puede acceder a la vista de esquema desde el editor de consultas o directamente desde el elemento graphQL API. Para abrir la vista de esquema, seleccione Esquema en la esquina inferior izquierda. La vista de esquema muestra una versión de solo lectura basada en texto de su SDL de GraphQL completa con todos los tipos, campos, consultas y mutaciones generados.

En la imagen siguiente se muestra la vista de esquema con el panel Explorador de esquemas de la izquierda:

Captura de pantalla de la pantalla de vista de esquema de API, que incluye el Explorador de esquemas en el panel izquierdo.

El Explorador de esquemas del panel izquierdo le permite navegar e inspeccionar todos los objetos de la API. El explorador está disponible tanto en la vista de esquema como en el editor de consultas, lo que facilita la exploración de la estructura de LA API al escribir consultas.

Expanda los nodos en el explorador de esquemas para ver:

  • Tipos: los tipos de GraphQL generados a partir de las tablas y vistas del origen de datos
  • Consultas: operaciones de lectura generadas automáticamente para recuperar datos
  • Mutaciones: operaciones de escritura generadas automáticamente para crear, actualizar y eliminar datos (solo almacenamiento)

Tipos

Los tipos representan la estructura de los datos y aparecen bajo el nombre del origen de datos desde el que se generaron. En la imagen siguiente se muestra el tipo SalesOrderDetail generado a partir de la tabla SalesOrderDetail en el punto de conexión de analytics SQL de AdventureWorks.

Captura de pantalla del panel Explorador de esquemas que muestra la lista expandida de tipos disponibles en un origen de datos de ejemplo denominado SalesOrderDetail.

Queries

La API genera automáticamente consultas para recuperar datos de los objetos que expone. Expanda el nodo de consultas para ver todas las operaciones de lectura disponibles:

Captura de pantalla del panel Explorador de esquemas, en la que se muestra una lista expandida de consultas generadas automáticamente.

Mutaciones

Las mutaciones son operaciones de escritura para crear, actualizar y eliminar datos. Expanda el nodo de mutaciones para ver todas las operaciones de escritura disponibles:

Captura de pantalla del panel Explorador de esquemas, en la que se muestra una lista expandida de mutaciones generadas automáticamente.

Nota:

Las mutaciones solo se generan para los orígenes de datos de Fabric Data Warehouse. Los puntos de conexión de SQL Analytics (Lakehouses y bases de datos reflejadas) son de solo lectura y únicamente permiten consultas. Si no ve las mutaciones en el explorador de esquemas, compruebe que se ha conectado a Fabric Data Warehouse.

Modificación de objetos mediante el explorador de esquemas

Una vez que la API genera el esquema inicial, puede usar el explorador de esquemas para refinar lo que se expone a través de la API. El explorador de esquemas proporciona opciones de administración que permiten controlar la estructura de la API sin modificar los orígenes de datos subyacentes. Estas herramientas son esenciales para mantener una API limpia y bien organizada que expone solo los datos que necesitan los clientes.

Opciones de modificación de acceso

Para modificar un objeto, seleccione los puntos suspensivos (...) junto a cualquier tipo del explorador de esquemas. En el ejemplo siguiente se muestra el menú de modificación del tipo SalesOrderDetail :

Captura de pantalla del explorador de esquemas con los puntos suspensivos seleccionados, en la que se muestran las opciones de menú disponibles.

Opciones de modificación disponibles

Actualizar esquema : sincroniza el esquema de GraphQL con la estructura más reciente del origen de datos. Úselo cuando haya agregado nuevas tablas, vistas o columnas al origen de datos y quiera exponerlas a través de la API. Esta operación detecta y agrega nuevos objetos a la vez que conserva la configuración existente.

Cambiar nombre : cambia la apariencia del objeto en GraphQL API. Esto resulta útil para crear convenciones de nomenclatura de API más intuitivas o ocultar los detalles de implementación de los clientes. Por ejemplo, puede cambiar el nombre tbl_SalesOrderDetail a simplemente SalesOrderDetail. El cambio de nombre solo afecta al esquema de api y no modifica el objeto de origen de datos subyacente.

Quitar del esquema - Quita el objeto de la API de GraphQL, haciéndolo no disponible para los clientes. Úselo para ocultar datos confidenciales, quitar objetos en desuso o simplificar la superficie de API. Los datos permanecen en el origen de datos; solo se elimina la exposición de la API.

Administrar relaciones : abre la interfaz de administración de relaciones donde puede definir cómo se conectan los objetos entre sí. Las relaciones permiten consultas anidadas y recorridos de grafos, lo que permite a los clientes recuperar datos relacionados en una sola solicitud. Para más información, consulte Administrar relaciones en la API de Fabric para GraphQL.

Propiedades : muestra metadatos detallados sobre el objeto, incluido el nombre original tal como aparece en el origen de datos, el nombre del tipo GraphQL, el propietario y la ubicación (área de trabajo y nombre del origen de datos). Úselo para verificar cómo los objetos se asignan entre su origen de datos y la API de GraphQL.

Habilitación y deshabilitación de consultas y mutaciones

La característica habilitar o deshabilitar para consultas y mutaciones proporciona a los administradores y desarrolladores un control pormenorizado sobre el acceso y el uso de la API. Permite activar o desactivar de forma selectiva consultas y mutaciones específicas dentro del esquema GraphQL. Esto te permite administrar las funcionalidades de API dinámicamente sin modificar el código ni implementar los cambios.

Use esta característica para escenarios como:

  • Control de versiones de API: deshabilite las operaciones en desuso al realizar la transición de los clientes a nuevas versiones
  • Ventanas de mantenimiento: deshabilitar temporalmente las operaciones de escritura (mutaciones) durante el mantenimiento de datos
  • Seguridad y cumplimiento: Restringir el acceso a operaciones confidenciales sin quitarlos del esquema
  • Lanzamientos por fases: habilite nuevas consultas o mutaciones para las pruebas antes de que estén disponibles ampliamente

Las consultas y las mutaciones en el explorador de esquemas tienen otras dos opciones:

  • Deshabilitar: impide que las solicitudes ejecuten la consulta o la mutación. Si se intenta ejecutar, se devuelve un error. Después de deshabilitar una consulta o mutación, se produce una recarga de esquema y la consulta o mutación aparece atenuada en el explorador de esquemas.

Captura de pantalla de la opción deshabilitar la consulta o la mutación que se muestra en el explorador de esquemas.

  • Habilitar: permite volver a habilitar una consulta o una mutación deshabilitadas anteriormente. La consulta o mutación está disponible inmediatamente después de la operación de recarga de esquema que se produce al seleccionar la opción Habilitar .

Captura de pantalla de la opción habilitar la consulta de mutación que se muestra en el explorador de esquemas.

Nota:

Las consultas y las mutaciones generadas automáticamente a partir de procedimientos almacenados se comportan de forma diferente a las generadas a partir de tablas o vistas. Solo se pueden eliminar, no deshabilitar. Después de la eliminación, puede leerlos mediante las opciones Obtener datos o Actualizar esquema . Para obtener más información, consulte Procedimientos almacenados.

Contenido relacionado

  • Last updated on