Editor de la API de Fabric para GraphQL

La API de Fabric para GraphQL proporciona un entorno de desarrollo gráfico de GraphQL en el explorador, que permite que un área de juegos interactiva cree, pruebe y vea los resultados en directo de las consultas y mutaciones de GraphQL.

Quién usa el editor de GraphQL

El editor de GraphQL es esencial para:

• Los desarrolladores de aplicaciones crean prototipos y prueban consultas en datos de Fabric antes de implementarlas en aplicaciones
• Ingenieros de datos que exploran las estructuras de datos de lakehouse y almacenamiento y validan los diseños de esquema de GraphQL
• Colaboradores del área de trabajo de Fabric que prueban los permisos de acceso a datos y solucionan problemas de consulta
• Desarrolladores de BI que aprenden la estructura de API y crean patrones de acceso a datos para aplicaciones personalizadas
• Equipos de desarrollo que colaboran en el desarrollo de consultas y solución de problemas de acceso a datos en áreas de trabajo de Fabric

Use el editor siempre que necesite desarrollar, probar o depurar consultas GraphQL interactivamente contra los orígenes de datos de Fabric.

Introducción al editor de GraphQL

Siga estos pasos para empezar a usar el editor de GraphQL:

1. Abra el elemento GraphQL API : vaya al área de trabajo en Fabric y abra el elemento API para GraphQL.

2. Acceso al editor : seleccione Consulta en la esquina inferior izquierda de la pantalla del portal.

   

3. Escribir la consulta : escriba las consultas de GraphQL directamente en la pestaña Consulta . Use IntelliSense con métodos abreviados de teclado:

   • Windows: CTRL + Espacio
   • macOS: comando + espacio

   

4. Ejecutar la consulta : seleccione Ejecutar para ejecutar la consulta y recuperar datos del origen de datos.

Generación de código

El editor de API genera automáticamente código reutilizable de Python o Node.js que refleja la consulta o mutación de GraphQL que está probando actualmente en el editor. A medida que crea prototipos y refina las consultas, el código generado se actualiza en consecuencia. Una vez que esté satisfecho con los resultados, puede ver y copiar el código generado para ejecutarlo localmente con fines de prueba o reutilizarlo en el proceso de desarrollo de aplicaciones.

Importante

El código generado usa credenciales interactivas del explorador y solo debe usarse con fines de prueba. En producción, registre siempre una aplicación en Microsoft Entra y use los ámbitos y client_id adecuados. Puede encontrar un ejemplo completo con código de ejemplo en Conectar aplicaciones.

Para empezar:

1. Escribir una consulta : escriba la consulta de ejemplo siguiente (o la suya propia) en el editor de consultas:

   query {
     addresses(first: 5) {
        items {
           AddressID
           City
           StateProvince
           CountryRegion
        }  
     }
   }
   

2. Ejecute la consulta : seleccione Ejecutar para ejecutar la consulta y compruebe que funciona correctamente en el editor antes de continuar.

3. Generar código: seleccione el botón Generar código y, a continuación, seleccione el lenguaje de programación preferido (Python o JavaScript/Node.JS):

   

4. A continuación, puede copiar el código generado y guardarlo como un archivo en una carpeta local. Según el idioma elegido, siga estos pasos rápidos para probar localmente:

Python

1. Cree un archivo denominado editor.py y pegue el código generado a partir de la consulta de ejemplo anterior.

2. Cree un entorno virtual mediante la ejecución del comando python -m venv .venv.

3. Active mediante venv la ejecución .venv\Scripts\activate de o source .venv/bin/activate.

4. Instale la dependencia necesaria mediante la ejecución pip install azure-identityde .

5. Ejecute el código con python editor.py.

6. Se le pedirá que inicie sesión a través de una ventana del explorador para autenticar la solicitud.

7. La respuesta de la API se imprime en la consola.

   {
   	"data": {
   		"addresses": {
   			"items": [
   				{
   					"AddressID": 9,
   					"City": "Bothell",
   					"StateProvince": "Washington",
   					"CountryRegion": "United States"
   				},
   				{
   					"AddressID": 11,
   					"City": "Bothell",
   					"StateProvince": "Washington",
   					"CountryRegion": "United States"
   				},
   				{
   					"AddressID": 25,
   					"City": "Dallas",
   					"StateProvince": "Texas",
   					"CountryRegion": "United States"
   				},
   				{
   					"AddressID": 28,
   					"City": "Phoenix",
   					"StateProvince": "Arizona",
   					"CountryRegion": "United States"
   				},
   				{
   					"AddressID": 32,
   					"City": "Montreal",
   					"StateProvince": "Quebec",
   					"CountryRegion": "Canada"
   				}
   			]
   		}
   	}
   }
   

Node.JS

1. Cree un archivo denominado editor.js y pegue el código generado a partir de la consulta de ejemplo anterior.

2. En la misma carpeta que editor.js, cree un package.json archivo con el siguiente contenido:

   {
     "type": "module",
     "dependencies": {}
   }
   

3. Instala Node.js en tu máquina de desarrollo (incluye npm)

4. Ejecute npm install @azure/identity o un comando similar en el administrador de paquetes elegido para instalar la versión más reciente de la biblioteca de identidades.

5. Ejecute node editor.js para ejecutar el código.

6. Se le pedirá que inicie sesión a través de una ventana del explorador para autenticar la solicitud.

7. La respuesta de la API se imprime en la consola.

   {
   	"data": {
   		"addresses": {
   			"items": [
   				{
   					"AddressID": 9,
   					"City": "Bothell",
   					"StateProvince": "Washington",
   					"CountryRegion": "United States"
   				},
   				{
   					"AddressID": 11,
   					"City": "Bothell",
   					"StateProvince": "Washington",
   					"CountryRegion": "United States"
   				},
   				{
   					"AddressID": 25,
   					"City": "Dallas",
   					"StateProvince": "Texas",
   					"CountryRegion": "United States"
   				},
   				{
   					"AddressID": 28,
   					"City": "Phoenix",
   					"StateProvince": "Arizona",
   					"CountryRegion": "United States"
   				},
   				{
   					"AddressID": 32,
   					"City": "Montreal",
   					"StateProvince": "Quebec",
   					"CountryRegion": "Canada"
   				}
   			]
   		}
   	}
   }
   

Desarrollo de consultas y mutaciones

En los ejemplos siguientes se muestra la sintaxis de mutación y consulta de GraphQL mediante los datos de ejemplo de AdventureWorks. En estos ejemplos se supone que está trabajando con un almacenamiento de datos de Fabric que admite operaciones de escritura (mutaciones). Los orígenes de datos a los que se accede a través de endpoints de SQL Analytics (como Lakehouses y bases de datos reflejadas) son de solo lectura y solo admiten consultas, no modificaciones.

Revise este breve fragmento de esquema de GraphQL de AdventureWorks. Define un Product tipo con consultas para leer un único producto o enumerar todos los productos y mutaciones para crear, actualizar o eliminar productos, que admiten todos los casos de uso CRUDL (crear, leer, actualizar, eliminar, enumerar).

{
  type Product {
    ProductID: Int!
    Name: String!
    ProductNumber: String!
    Color: String
    ListPrice: Float!
    SellStartDate: DateTime!
  }

  type Query {
    products(first: Int, filter: ProductFilterInput): ProductConnection
    products_by_pk(ProductID: Int!): Product
  }

  type Mutation {
    createProduct(Name: String!, ProductNumber: String!, ListPrice: Float!, SellStartDate: DateTime!): Product
    updateProduct(ProductID: Int!, Name: String, Color: String, ListPrice: Float): Product
    deleteProduct(ProductID: Int!): Boolean
  }
}

Lea los datos expuestos a través de GraphQL mediante cualquier consulta definida en el esquema. La products_by_pk consulta recupera un único producto por su clave principal:

query MyQuery {
  products_by_pk(ProductID: 680) {
    ProductID
    Name
    ProductNumber
    Color
    ListPrice
  }
}

Respuesta:

{
  "data": {
    "products_by_pk": {
      "ProductID": 680,
      "Name": "HL Road Frame - Black, 58",
      "ProductNumber": "FR-R92B-58",
      "Color": "Black",
      "ListPrice": 1431.50
    }
  }
}

Use mutaciones como createProduct para escribir datos y crear un nuevo producto con los parámetros necesarios.

mutation MyMutation {
  createProduct(
    Name: "Mountain Bike Helmet - Blue", 
    ProductNumber: "HE-M897-B", 
    ListPrice: 89.99,
    SellStartDate: "2025-01-01T00:00:00Z"
  ) {
    ProductID
    Name
    ProductNumber
    ListPrice
  }
}

Respuesta:

{
  "data": {
    "createProduct": {
      "ProductID": 1001,
      "Name": "Mountain Bike Helmet - Blue",
      "ProductNumber": "HE-M897-B",
      "ListPrice": 89.99
    }
  }
}

Variables de consulta

Use el panel Variables de consulta en el lado derecho de la pestaña Consulta para pasar parámetros como variables a las consultas o mutaciones. Las variables funcionan como variables en otros lenguajes de programación. Cada variable se declara con un nombre que se usa para tener acceso al valor almacenado en ella. Con el ejemplo de mutación anterior, modificas ligeramente para usar variables de consulta.

mutation MyMutation ($name: String!, $productNumber: String!, $listPrice: Float!, $sellStartDate: DateTime!){
  createProduct(
    Name: $name, 
    ProductNumber: $productNumber, 
    ListPrice: $listPrice,
    SellStartDate: $sellStartDate
  ) {
    ProductID
    Name
    ProductNumber
    ListPrice
  }
}

Defina variables en el panel Variables de consulta mediante el ejemplo siguiente.

{
  "name": "Mountain Bike Helmet - Blue",
  "productNumber": "HE-M897-B",
  "listPrice": 89.99,
  "sellStartDate": "2025-01-01T00:00:00Z"
}

Las variables hacen que el código de mutación sea más limpio, fácil de leer, probar y modificar. También facilitan la reutilización de la misma mutación con valores diferentes cambiando simplemente las variables.

Contenido relacionado

• Más ejemplos de consulta y mutación
• Fabric API for GraphQL schema view and schema explorer (API de Fabric para GraphQL schema view and schema explorer)