Importare un'API GraphQL

SI APPLICA A: tutti i livelli di Gestione API

In Gestione API, è possibile aggiungere un'API GraphQL in uno dei due modelli: effettuare il pass-through a un endpoint GraphQL esistente o importare uno schema GraphQL e creare un'API GraphQL sintetica con sistemi di risoluzione di campi personalizzati. Per ulteriori informazioni, consultare la panoramica di GraphQL.

Contenuto dell'articolo:

• Aggiungere un'API GraphQL pass-through all'istanza di Gestione API.
• Testare l'API GraphQL.

Per importare uno schema GraphQL e configurare i resolver di campi che usano endpoint API REST o SOAP, vedere Importare uno schema GraphQL e configurare i resolver dei campi.

Prerequisiti

• Un'istanza di Gestione API. Crearne una se non è già stato fatto.

• Interfaccia della riga di comando di Azure, se si vuole usarla per importare l'API.

  • Utilizzare l'ambiente Bash in Azure Cloud Shell. Per altre informazioni, vedere Introduzione ad Azure Cloud Shell.

    

  • Se si preferisce eseguire i comandi di riferimento dell'interfaccia della riga di comando in locale, installare l'interfaccia della riga di comando di Azure. Per l'esecuzione in Windows o macOS, considerare l'esecuzione dell'interfaccia della riga di comando di Azure in un contenitore Docker. Per altre informazioni, vedere Come eseguire l’interfaccia della riga di comando di Azure in un contenitore Docker.

    • Se si usa un'installazione locale, accedere all'interfaccia della riga di comando di Azure con il comando az login. Per completare il processo di autenticazione, seguire la procedura visualizzata nel terminale. Per altre opzioni di accesso, vedere Eseguire l'autenticazione ad Azure con l'interfaccia della riga di comando di Azure.

    • Quando richiesto, al primo utilizzo installare l'estensione dell'interfaccia della riga di comando di Azure. Per altre informazioni sulle estensioni, vedere Usare e gestire le estensioni con l'interfaccia della riga di comando di Azure.

    • Eseguire az version per trovare la versione e le librerie dipendenti installate. Per eseguire l'aggiornamento alla versione più recente, eseguire az upgrade.

• Azure PowerShell, se si vuole usarlo per importare l'API.

  • Se si sceglie di usare Azure PowerShell in locale:
    • Installare la versione più recente del modulo Az di PowerShell.
    • Connettersi all'account Azure con il cmdlet Connect-AzAccount.
  • Se si sceglie di usare Azure Cloud Shell:
    • Vedere Panoramica di Azure Cloud Shell per altre informazioni.

Aggiungere un'API GraphQL

Portale

1. Nel portale di Azure passare all'istanza di Gestione API.

2. Nel riquadro sinistro selezionare API>API.

3. Selezionare Aggiungi API.

4. In Definisci una nuova API selezionare il riquadro GraphQL .

   

5. Nella finestra di dialogo risultante selezionare Full e quindi immettere i valori nei campi obbligatori, come descritto nella tabella seguente.

   

   Value	Descrizione
   Nome visualizzato	Il nome con cui verrà visualizzata l'API GraphQL.
   Nome	Nome non elaborato dell'API GraphQL. Si popola automaticamente durante la digitazione del nome visualizzato.
   Tipo GraphQL	Selezionare pass-through GraphQL per importare da un endpoint dell'API GraphQL esistente.
   Endpoint dell'API GraphQL	URL di base con il nome dell'endpoint dell'API GraphQL. Ad esempio https://example.com/your-GraphQL-name. È anche possibile usare un endpoint GraphQL SWAPI comune come https://swapi-graphql.azure-api.net/graphql per la dimostrazione.
   Carica schema	Facoltativamente, selezionare per caricare il file di schema per sostituire lo schema recuperato dall'endpoint GraphQL (se disponibile).
   Descrizione	Aggiungere una descrizione dell'API.
   Schema URL	Selezionare uno schema basato sull'endpoint GraphQL. Selezionare una delle opzioni che includono uno schema WebSocket (WS o WSS) se l'API GraphQL include il tipo di sottoscrizione. La selezione predefinita è HTTP(S).
   Suffisso dell'URL dell'API	Aggiungere un suffisso URL per identificare l'API specifica nell'istanza di Gestione API. Deve essere univoco nell'istanza di Gestione API.
   URL di base	Campo non modificabile che visualizza l'URL di base dell'API.
   Tag	Facoltativamente, associare l'API GraphQL ai tag nuovi o esistenti.
   Prodotti	Associare l'API GraphQL a un prodotto per pubblicarlo.
   Assegnare un numero di versione a questa API?	Selezionare la casella di controllo per applicare uno schema di controllo delle versioni all'API GraphQL.

6. Selezionare Crea.

7. Dopo aver creato l'API, esaminare o modificare lo schema nella scheda Schema .

Interfaccia della riga di comando di Azure

Il seguente esempio usa il comando az apim api import per importare un’API pass-through GraphQL dall'URL specificato in un'istanza di Gestione API denominata 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

Dopo aver importato l'API, è possibile aggiornare le impostazioni usando il comando az apim api update , se necessario.

PowerShell

Il seguente esempio usa il cmdlet import-AzApiManagementApi di Azure PowerShell per importare un'API pass-through GraphQL dall'URL specificato a un'istanza di Gestione API denominata 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

Dopo aver importato l'API, è possibile aggiornare le impostazioni usando il cmdlet Set-AzApiManagementApi , se necessario.

Testare l'API GraphQL

1. Passare all'istanza di Gestione API.

2. Nel riquadro sinistro, nella sezione API selezionare API.

3. In Tutte le API, selezionare l'API GraphQL.

4. Selezionare la scheda Test per accedere alla console di test.

5. In Intestazioni:

   1. Selezionare l'intestazione dal menu Nome .
   2. Immettere il valore nella casella Valore .
   3. Aggiungere altre intestazioni selezionando Aggiungi intestazione.
   4. Eliminare le intestazioni usando il pulsante Cestino.

6. Se è stato aggiunto un prodotto all'API GraphQL, aggiungere un ambito di prodotto in Applica ambito prodotto.

7. Nell'editor di query eseguire una delle operazioni seguenti:

   1. Selezionare almeno un campo o un sottocampo dall'elenco nel menu a sinistra dell'editor. I campi e i sottocampi selezionati vengono visualizzati nell'editor query.

   2. Iniziare a digitare nell'editor query per comporre una query.

      

8. In Variabili di query, aggiungere variabili per riutilizzare la stessa query o la stessa mutazione e passare valori diversi.

9. Selezionare Send (Invia).

10. Visualizzare la risposta.

    

11. Ripetere i passaggi precedenti per testare payload diversi.

12. Al termine dei test, uscire dalla console di test.

Testare una sottoscrizione

Se l'API GraphQL supporta una sottoscrizione, è possibile testarla nella console di test.

1. Assicurarsi che l'API consenta uno schema URL WebSocket (WS o WSS) adatto per l'API. È possibile abilitare questa impostazione nella scheda Impostazioni.

2. Configurare una query di sottoscrizione nell'editor di query, quindi selezionare Connetti per stabilire una connessione WebSocket con il servizio back-end.

   

3. Revisionare i dettagli della connessione nel riquadro Sottoscrizione.

   

4. Gli eventi sottoscritti appaiono nel riquadro Sottoscrizione. La connessione WebSocket viene mantenuta fino a quando non la disconnetti o ti connetti a una nuova sottoscrizione WebSocket.

   

Proteggere l'API GraphQL

Proteggere l’API GraphQL applicando sia i criteri di autenticazione e autorizzazione sia un criterio di convalida di GraphQL per la protezione da attacchi specifici per GraphQL.

Contenuti correlati

• Limitazioni relative all'importazione di API
• Importare una specifica OpenAPI
• Importare un'API SOAP
• Importare un'API SOAP e convertirla in REST
• Importare un'API del Servizio app
• Importare un'API dell'app contenitore
• Importare un'API WebSocket
• Importare un'API GraphQL
• Importare uno schema di GraphQL e configurare resolver di campo
• Importare un'API dell'app per le funzioni
• Importare un'API per un'app di logica
• Importare un servizio Service Fabric
• Importare un'API Foundry per intelligenza artificiale di Azure
• Importare un'API di OpenAI di Azure
• Importare un'API LLM
• Importare un'API OData
• Esportare un'API REST come server MCP
• Rendere visibile un server MCP esistente
• Importare un'API dell'agente A2A
• Importare metadati OData SAP
• Importare un'API gRPC
• Modificare un'API