Importación de GraphQL API

SE APLICA A: Todos los niveles de API Management

En API Management, puede agregar una GraphQL API en uno de los dos modelos: pasar a un punto de conexión de GraphQL existente o importar un esquema GraphQL y crear una GraphQL API sintética con solucionadores de campos personalizados. Para obtener más información, consulte introducción a GraphQL.

En este artículo, hará lo siguiente:

• Cómo agregar una GraphQL API de tránsito a la instancia de API Management.
• Probar la GraphQL API.

Si desea importar un esquema de GraphQL y configurar solucionadores de campos que usan puntos de conexión de API REST o SOAP, consulte Importación de un esquema de GraphQL y configuración de solucionadores de campos.

Requisitos previos

• Una instancia de Azure API Management. Cree una suscripción si todavía no lo ha hecho.

• CLI de Azure, si quiere usarla para importar la API.

  • Use el entorno de Bash en Azure Cloud Shell. Para más información, consulte Introducción a Azure Cloud Shell.

    

  • Si prefiere ejecutar comandos de referencia de la CLI localmente, instale la CLI de Azure. Si utiliza Windows o macOS, considere la posibilidad de ejecutar la CLI de Azure en un contenedor Docker. Para obtener más información, consulte Ejecución de la CLI de Azure en un contenedor de Docker.

    • Si usa una instalación local, inicie sesión en la CLI de Azure mediante el comando az login. Siga los pasos que se muestran en el terminal para completar el proceso de autenticación. Para ver otras opciones de inicio de sesión, consulte Autenticación en Azure mediante la CLI de Azure.

    • En caso de que se le solicite, instale las extensiones de la CLI de Azure la primera vez que la use. Para obtener más información sobre las extensiones, consulte Uso y administración de extensiones con la CLI de Azure.

    • Ejecute az version para buscar cuál es la versión y las bibliotecas dependientes que están instaladas. Para realizar la actualización a la versión más reciente, ejecute az upgrade.

• Azure PowerShell, si quiere usarlo para importar la API.

  • Si opta por usar Azure PowerShell en un entorno local:
    • Instale la última versión del módulo Az de PowerShell.
    • Conéctese a su cuenta de Azure mediante el cmdlet Connect-AzAccount.
  • Si decide usar Azure Cloud Shell:
    • Para más información, consulte Introducción a Azure Cloud Shell.

Agregar una GraphQL API

Portal

1. En Azure Portal, vaya a la instancia de API Management.

2. En el panel izquierdo, seleccione APIs>APIs.

3. Seleccione Agregar API.

4. En Definir una nueva API, seleccione el icono graphQL .

   

5. En el cuadro de diálogo resultante, seleccione Completo y, a continuación, escriba valores en los campos obligatorios, como se describe en la tabla siguiente.

   

   Importancia	Descripción
   Nombre para mostrar	Nombre con el que se mostrará la GraphQL API.
   Nombre	Nombre bruto de la API de GraphQL. Se rellena automáticamente a medida que escribe el nombre para mostrar.
   Tipo GraphQL	Seleccione GraphQL de tránsito para importar desde un punto de conexión de GraphQL API existente.
   Punto de conexión de API de GraphQL	Dirección URL base con el nombre del punto de conexión de la GraphQL API. Por ejemplo: https://example.com/your-GraphQL-name. También puede usar un punto de conexión común de GraphQL de SWAPI, como https://swapi-graphql.azure-api.net/graphql con fines de demostración.
   Cargar esquema	Opcionalmente, seleccione esta opción para cargar el archivo de esquema para reemplazar el esquema que se recupera del punto de conexión de GraphQL (si tiene uno).
   Descripción	Agregue una descripción de la API.
   Esquema URL	Seleccione un esquema basado en el punto de conexión de GraphQL. Seleccione una de las opciones que incluye un esquema WebSocket (WS o WSS) si GraphQL API incluye el tipo de suscripción. La selección predeterminada es HTTP(S).
   Sufijo de dirección URL de API	Agregue un sufijo url para identificar la API específica en la instancia de API Management. Debe ser único en la instancia de API Management.
   URL base	Campo no editable que muestra la dirección URL base de la API.
   Etiquetas	Opcionalmente, asocie graphQL API con etiquetas nuevas o existentes.
   Productos	Asocie la GraphQL API a un producto para publicarla.
   ¿Definir versión de esta API?	Active la casilla para aplicar un esquema de control de versiones a graphQL API.

6. Seleccione Crear.

7. Una vez creada la API, revise o modifique el esquema en la pestaña Esquema .

CLI de Azure

En el ejemplo siguiente se usa el comando az apim api import para importar una API de paso de GraphQL de la dirección URL especificada en una instancia de API Management que se denomina apim-hello-world.

# Details specific to API Management instance.
APIMServiceName="apim-hello-world"
ResourceGroupName="myResourceGroup"

# API-specific details.
APIId="my-graphql-api"
APIPath="myapi"
DisplayName="MyGraphQLAPI"
SpecificationFormat="GraphQL"
SpecificationURL="<GraphQL backend endpoint>"

# Import API.
az apim api import \
    --path $APIPath \
    --resource-group $ResourceGroupName \
    --service-name $APIMServiceName --api-id $APIId \
    --display-name $DisplayName --specification-format $SpecificationFormat \
    --specification-url $SpecificationURL

Después de importar la API, puede actualizar la configuración mediante el comando az apim api update , si es necesario.

PowerShell

En el ejemplo siguiente se usa el cmdlet de Azure PowerShell Import-AzApiManagementApi para importar una API de paso de GraphQL de la dirección URL especificada en una instancia de API Management que se denomina apim-hello-world.

# Details specific to API Management instance.
$apimServiceName = "apim-hello-world"
$resourceGroupName = "myResourceGroup"

# API-specific details.
$apiId = "my-graphql-api"
$apiPath = "myapi"
$specificationFormat = "GraphQL"
$specificationUrl = "<GraphQL backend endpoint>"

# Get context of the API Management instance. 
$context = New-AzApiManagementContext -ResourceGroupName $resourceGroupName -ServiceName $apimServiceName

# Import API.
Import-AzApiManagementApi -Context $context -ApiId $apiId -SpecificationFormat $specificationFormat -SpecificationUrl $specificationUrl -Path $apiPath

Después de importar la API, puede actualizar la configuración mediante el cmdlet Set-AzApiManagementApi , si es necesario.

Probar la GraphQL API

1. Vaya a la instancia de API Management.

2. En el panel izquierdo, en la sección API , seleccione API.

3. En Todas las API, seleccione la GraphQL API.

4. Seleccione la pestaña Prueba para acceder a la consola de prueba.

5. En Encabezados:

   1. Seleccione el encabezado en el menú Nombre .
   2. Escriba el valor en el cuadro Valor .
   3. Para agregar más encabezados, seleccione Agregar encabezado.
   4. Elimine los encabezados con el botón papelera de reciclaje.

6. Si ha agregado un producto a la GraphQL API, agregue un ámbito de producto bajo Aplicar ámbito de producto.

7. En el Editor de consultas, realice una de las acciones siguientes:

   1. Seleccione al menos un campo o subcampo de la lista del menú a la izquierda del editor. Los campos y subcampos que seleccione aparecerán en el editor de consultas.

   2. Comience a escribir en el editor de consultas para crear una consulta.

      

8. En Variables de consulta, agregue variables para reutilizar la misma consulta o mutación y pasar valores diferentes.

9. Seleccione Enviar.

10. Vea la Respuesta.

    

11. Repita los pasos anteriores para probar diferentes cargas.

12. Cuando haya terminado las pruebas, salga de la consola de prueba.

Cómo probar una suscripción

Si GraphQL API admite una suscripción, puede probarla en la consola de prueba.

1. Asegúrese de que la API permite un esquema de dirección URL de WebSocket (WS o WSS) adecuado para la API. Puede habilitar esta opción en la pestaña Configuración.

2. Configure una consulta de suscripción en el editor de consultas y seleccione Conectar para establecer una conexión WebSocket con el servicio de back-end.

   

3. Revise los detalles de conexión en el panel Suscripción.

   

4. Los eventos suscritos aparecen en el panel Suscripción. La conexión de WebSocket se mantiene hasta que se desconecta o se conecta a una nueva suscripción de WebSocket.

   

Cómo proteger la GraphQL API

Proteja la API de GraphQL aplicando las directivas de autenticación y autorización existentes y una directiva de validación de GraphQL para protegerse frente a ataques específicos de GraphQL.

Contenido relacionado

• Limitaciones de importación de API
• Importación de una especificación de OpenAPI
• Importación de una API de SOAP
• Importar una API de SOAP y convertir en REST
• Importación de App Service API
• Importación de una API de aplicación de contenedor
• Importar una API de WebSocket
• Importar API de GraphQL
• Importar un esquema GraphQL y configurar solucionadores de campos
• Importación de una API de aplicación de funciones
• Importación de una API de aplicación lógica
• Importación de un servicio Service Fabric
• Importación de una API de Azure AI Foundry
• Importar una API de Azure OpenAI
• Importación de una API de LLM
• Importar una API de OData
• Exportación de una API REST como servidor MCP
• Exposición de un servidor MCP existente
• Importación de una API de agente de A2A
• Importar metadatos de SAP OData
• Importar una API de gRPC
• Edición de una API