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 más información, consulte la 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 mediante puntos de conexión de LA API REST o SOAP, consulte Importación de un esquema graphQL y configuración de solucionadores de campos.

Requisitos previos

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

• Una GraphQL API.

• Azure CLI

  • Use el entorno de Bash en Azure Cloud Shell. Para más información, consulte Inicio rápido para Bash en 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 más información, vea 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 Inicio de sesión con 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 más información sobre las extensiones, consulte Uso 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 opta por usar Azure PowerShell en un entorno local:
    • Instale la versión más reciente 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. Vaya a la instancia de API Management en Azure Portal.

2. En el menú izquierdo, seleccione API>+ Agregar API.

3. En Definir una API nueva, seleccione el icono GraphQL.

   

4. En el cuadro de diálogo, seleccione Completo y rellene los campos necesarios del formulario.

   

   Campo	Description
   Nombre para mostrar	Nombre con el que se mostrará la GraphQL API.
   Nombre	Nombre sin formato de la GraphQL API. 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 la GraphQL API	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 "swapi" como https://swapi-graphql.azure-api.net/graphql como demo.
   Cargar esquema	Opcionalmente, seleccione examinar y cargar el archivo de esquema para reemplazar el esquema recuperado del punto de conexión de GraphQL (si está disponible).
   Descripción	Agregue una descripción de la API.
   Esquema URL	Realice una selección basada 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. Selección predeterminada: HTTP(S).
   Sufijo de dirección URL de API	Agregue un sufijo de URL para identificar esta API específica en esta instancia de API Management. Tiene que ser único en esta instancia de API Management.
   URL base	Campo no editable que muestra la dirección URL base de la API
   Etiquetas	Asocie la GraphQL API a etiquetas nuevas o existentes.
   Productos	Asocie la GraphQL API a un producto para publicarla.
   ¿Definir versión de esta API?	Seleccione esta opción para aplicar un esquema de control de versiones a la API de GraphQL.

5. Seleccione Crear.

6. Una vez creada la API, examine o modifique el esquema en la pestaña Diseño.

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.

# API Management service-specific details
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, si es necesario, puede actualizar la configuración mediante el comando az apim api update.

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.

# API Management service-specific details
$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, si es necesario, puede actualizar la configuración mediante el cmdlet Set-AzApiManagementApi.

Probar la GraphQL API

1. Navegue hasta su instancia de API Management.

2. En el menú de navegación lateral, 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ú desplegable Nombre.
   2. Escriba el valor en el campo Valor.
   3. Agregue más encabezados seleccionando + Agregar encabezado.
   4. Elimine los encabezados mediante el icono de la papelera.

6. Si ha agregado un producto a la GraphQL API, aplique el ámbito del producto en Aplicar ámbito del producto.

7. En el Editor de consultas, haga una de las opciones siguientes:

   1. Seleccione al menos un campo o subcampo de la lista en el menú lateral. 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. Una vez completadas 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.

Temas relacionados

• Limitaciones de importación de API
• Importación de una especificación de OpenAPI
• Importación de una API de SOAP
• Importación de API de SOAP y conversión en REST
• Importación de App Service API
• Importación de una aplicación de contenedor de Azure como una API
• Importación de WebSocket API
• Importación de GraphQL API
• Importación de un esquema GraphQL y configuración de solucionadores de campos
• Importación de una aplicación de Azure Function App
• Importación de una aplicación lógica de Azure.
• Importación de un servicio Service Fabric
• Importación de una API de Azure OpenAI
• Importación de una API de OData
• Importación de metadatos de SAP OData
• Importación de una API de gRPC
• Edición de una API

Pasos siguientes

Transformación y protección de una API publicada