Aggiungere un'API GraphQL sintetica e configurare i sistemi di risoluzione di campi

  • Articolo

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.

Nota

Attualmente, questa funzionalità non è disponibile nelle aree di lavoro.

Contenuto dell'articolo:

  • Importare uno schema GraphQL nell'istanza di Gestione API
  • Configurare un sistema di risoluzione per una query GraphQL usando un endpoint HTTP esistente
  • Testare l'API GraphQL

Per esporre un endpoint GraphQL esistente come API, vedere Importare un'API GraphQL.

Prerequisiti

  • Un'istanza di API Management esistente. Crearne una se non è già stato fatto.
  • File di schema GraphQL valido con l'estensione .graphql.
  • Un endpoint GraphQL back-end è facoltativo per questo scenario.

Passare all'istanza di Gestione API

  1. Nel portale di Azure cercare e selezionare Servizi Gestione API.

    Selezionare Servizi Gestione API

  2. Nella pagina Servizi Gestione API selezionare l'istanza di Gestione API.

    Selezionare l'istanza di Gestione API

Aggiungere uno schema GraphQL

  1. Nel menu di spostamento laterale, nella sezione API selezionare API.

  2. In Definisci una nuova API selezionare l'icona GraphQL.

    Screenshot della selezione dell'icona GraphQL nell'elenco API.

  3. Nella finestra di dialogo, selezionare Completo e completare i campi modulo richiesti.

    Screenshot dei campi per la creazione di API GraphQL.

    Campo Descrzione
    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 GraphQL sintetico da importare da un file di schema GraphQL.
    Eseguire il fallback dell'endpoint GraphQL Facoltativamente, immettere un URL con un nome endpoint dell'API GraphQL. Gestione API passa query GraphQL a questo endpoint quando un sistema di risoluzione personalizzato non è impostato per un campo.
    Descrizione Aggiungere una descrizione dell'API.
    Schema URL Effettuare una selezione in base all'endpoint GraphQL. Selezionare una delle opzioni che includono uno schema WebSocket (WS o WSS) se l'API GraphQL include il tipo di sottoscrizione. Selezione predefinita: HTTP(S).
    Suffisso dell'URL dell'API Aggiungere un suffisso URL per identificare l’API specifica in questa istanza di Gestione API. Deve essere univoco nell'istanza di Gestione API.
    URL di base Campo non modificabile che mostra l'URL di base dell'API
    Tag Associare l'API GraphQL a tag nuovi o esistenti.
    Prodotti Associare l'API GraphQL a un prodotto per pubblicarlo.
    Assegnare un numero di versione a questa API? Selezionare questa opzione per applicare uno schema di controllo delle versioni all'API GraphQL.

  4. Seleziona Crea.

  5. Dopo aver creato l'API, esplorare o modificare lo schema nella scheda Progettazione.

Configurare il sistema di risoluzione

Configurare un sistema di risoluzione per eseguire il mapping di un campo dello schema a un endpoint HTTP esistente. I passaggi generali sono disponibili qui. Per informazioni dettagliate, vedere Configurare un sistema di risoluzione GraphQL.

Si supponga di aver importato lo schema GraphQL di base seguente e di voler configurare un sistema di risoluzione per la query utenti.

type Query {
    users: [User]
}

type User {
    id: String!
    name: String!
}

  1. Nel menu di spostamento laterale, nella sezione API selezionare API> per l'API GraphQL.

  2. Nella scheda Schema esaminare lo schema di un campo del tipo di oggetto in cui si vuole configurare un sistema di risoluzione.

    1. Selezionare un campo, quindi passare il puntatore del mouse sul margine sinistro.

    2. Selezionare + Aggiungi sistema di risoluzione

      Screenshot dell'aggiunta di un resolver GraphQL nel portale.

  3. Nella pagina Crea resolver:

    1. Aggiornare la proprietà Nome se si desidera immettere facoltativamente una descrizione e confermare o aggiornare le selezioni Tipo e Campo.
    2. In Origine dati selezionare API HTTP.

  4. Nell'editor dei criteri del sistema di risoluzione aggiornare l'elemento <http-data-source> con gli elementi figlio dello scenario. Ad esempio, il sistema di risoluzione seguente recupera il campo utenti effettuando una chiamata GET a un'origine dati HTTP esistente.

        <http-data-source>
        <http-request>
            <set-method>GET</set-method>
            <set-url>https://myapi.contoso.com/users</set-url>
        </http-request>
    </http-data-source>

    Screenshot della configurazione dei criteri del resolver nel portale.

  5. Seleziona Crea.

  6. Per risolvere i dati di un altro campo dello schema, ripetere i passaggi precedenti per creare un sistema di risoluzione.

Suggerimento

Quando si modifica un criterio del sistema di risoluzione, selezionare Esegui test per controllare l'output dell'origine dati, che è possibile convalidare in base allo schema. Se si verificano errori, la risposta include informazioni sulla risoluzione dei problemi.

Testare l'API GraphQL

  1. Passare all'istanza di Gestione API.

  2. Nel menu di spostamento laterale, 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 a discesa Nome.
    2. Immettere il valore nel campo Valore.
    3. Aggiungere altre intestazioni selezionando + Aggiungi intestazione.
    4. Eliminare le intestazioni usando l'icona cestino.

  6. Se è stato aggiunto un prodotto all'API GraphQL, applicare l'ambito del prodotto in Applica ambito prodotto.

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

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

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

      Screenshot dell'aggiunta di campi all'editor di query.

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

  9. Selezionare Invia.

  10. Visualizzare la risposta.

    Screenshot della visualizzazione della risposta alla query di test.

  11. Ripetere i passaggi precedenti per testare altri payload.

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

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.

Passaggi successivi

Trasformare e proteggere un'API pubblicata