Configurare un resolver GraphQL

Articolo
05/07/2024

SI APPLICA A: Tutti i livelli di Gestione API

Configurare un resolver per recuperare o impostare i dati di un campo GraphQL in un tipo di oggetto specificato in uno schema GraphQL. Lo schema deve essere importato in Gestione API come API GraphQL.

Gestione API supporta attualmente i resolver che possono accedere alle origini dati seguenti:

Origine dati basata su HTTP (API REST o SOAP)
Database Cosmos DB
Database SQL di Azure

Informazioni utili

Un resolver è una risorsa contenente una definizione di criterio che viene richiamata solo quando viene eseguito un tipo di oggetto e un campo corrispondenti nello schema.
Ogni resolver risolve i dati per un singolo campo. Per risolvere i dati di più campi, configurare un resolver separato per ognuno di essi.
I criteri con ambito resolver vengono valutati dopo tutti i criteri inbound e backend nella pipeline di esecuzione del criterio. In questo modo, non ereditano criteri da altri ambiti. Per altre informazioni, vedere Criteri in Gestione API.
È possibile configurare criteri con ambito API per un'API GraphQL, indipendentemente dai criteri con ambito resolver. Ad esempio, aggiungere un criterio validate-graphql-request all'ambito inbound per convalidare la richiesta prima che venga richiamato il resolver. Configurare i criteri con ambito API nella scheda Criteri API per l'API.
Per supportare i tipi di interfaccia e unione nei resolver GraphQL, la risposta back-end deve contenere già il __typename campo o essere modificata usando i criteri set-body per includere __typename.

Prerequisiti

Un'istanza di Gestione API esistente. Crearne una se non è già stato fatto.
Importare un'API GraphQL pass-through o sintetica.

Creare un resolver

I passaggi seguenti consentono di creare un resolver tramite un'origine dati basata su HTTP. I passaggi generali sono simili per qualsiasi resolver che usi un'origine dati supportata.

Nel portale di Azure accedere all'istanza di Gestione API.
Nel menu a sinistra, selezionare API e quindi il nome dell'API GraphQL.
Nella scheda Schema, esaminare lo schema di un campo del tipo di oggetto in cui si vuole configurare un resolver.
1. Selezionare un campo, quindi passare il puntatore del mouse sul margine sinistro.
2. Selezionare + Aggiungi resolver.
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. Selezionare Origine dati del resolver. Per questo esempio, selezionare API HTTP.
Nell'editor Criterio del resolver, aggiornare il criterio http-data-source con gli elementi figlio dello scenario.
1. Aggiornare l'elemento http-request obbligatorio con i criteri per trasformare l'operazione GraphQL in una richiesta HTTP.
2. Facoltativamente, aggiungere un elemento http-response e criteri figlio per trasformare la risposta HTTP del resolver. Se l'elemento http-response non viene specificato, la risposta viene restituita come stringa non elaborata.
3. Seleziona Crea.
Il resolver è collegato al campo e viene visualizzato nella scheda Resolver.

Gestire i resolver

Elencare e gestire i resolver per un'API GraphQL nella scheda Resolver dell'API.

Nella scheda Resolver:

La colonna Collegato indica se il resolver è configurato per un campo attualmente incluso nello schema GraphQL. Se un resolver non è collegato, non può essere richiamato.
Nel menu di scelta rapida (...) di un resolver, trovare i comandi per Clonare, Modificare o Eliminare un resolver. Clonare un resolver dell'elenco per creare rapidamente un resolver simile destinato a un tipo e a un campo diversi.
È possibile creare un nuovo resolver selezionando + Crea.

Modificare e testare un resolver

Quando si modifica un singolo resolver, si apre la pagina Modifica resolver. È possibile:

Aggiornare il criterio del resolver e, facoltativamente, l'origine dati. La modifica dell'origine dati sovrascrive il criterio del resolver corrente.
Modificare il tipo e il campo di destinazione del resolver.
Testare ed eseguire il debug della configurazione del resolver. Quando si modifica il criterio del resolver, 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.

Contesto GraphQL

Il contesto per la richiesta e la risposta del resolver, se specificato, è diverso dal contesto per la richiesta API del gateway originale:
- Le proprietà context.GraphQL vengono impostate sugli argomenti (Arguments) e sull'oggetto padre (Parent) per l'esecuzione corrente del resolver.
- Il contesto della richiesta contiene argomenti passati nella query GraphQL come corpo.
- Il contesto di risposta è la risposta della chiamata indipendente effettuata dal resolver, non il contesto della risposta completa alla richiesta del gateway. La variabile context passata attraverso la pipeline di richiesta e risposta viene aumentata con il contesto GraphQL quando viene usata con un resolver GraphQL.

context.GraphQL.parent

La context.GraphQL.parent è impostata sull'oggetto padre per l'esecuzione del resolver corrente. Si consideri lo schema parziale seguente:

type Comment {
    id: ID!
    owner: string!
    content: string!
}

type Blog {
    id: ID!
    title: string!
    content: string!
    comments: [Comment]!
    comment(id: ID!): Comment
}

type Query {
    getBlog(): [Blog]!
    getBlog(id: ID!): Blog
}

Si consideri anche una query GraphQL per ottenere tutte le informazioni di un blog specifico:

query {
    getBlog(id: 1) {
        title
        content
        comments {
            id
            owner
            content
        }
    }
}

Se si imposta un resolver per il campo comments nel tipo Blog, è necessario comprendere quale ID blog usare. È possibile ottenere l'ID del blog usando context.GraphQL.Parent["id"] come illustrato nel resolver seguente:

<http-data-source>
    <http-request>
        <set-method>GET</set-method>
        <set-url>@($"https://data.contoso.com/api/blog/{context.GraphQL.Parent["id"]}")
        </set-url>
    </http-request>
</http-data-source>

context.GraphQL.Arguments

Gli argomenti di una query GraphQL parametrizzata vengono aggiunti a context.GraphQL.Arguments. Si considerino ad esempio le due query seguenti:

query($id: Int) {
    getComment(id: $id) {
        content
    }
}

query {
    getComment(id: 2) {
        content
    }
}

Queste query sono due modi per chiamare il resolver getComment. GraphQL invia il payload JSON seguente:

{
    "query": "query($id: Int) { getComment(id: $id) { content } }",
    "variables": { "id": 2 }
}

{
    "query": "query { getComment(id: 2) { content } }"
}

È possibile definire il resolver come segue:

<http-data-source>
    <http-request>
        <set-method>GET</set-method>
        <set-url>@($"https://data.contoso.com/api/comment/{context.GraphQL.Arguments["id"]}")</set-url>
    </http-request>
</http-data-source>

Passaggi successivi

Per altri esempi di resolver, vedere:

Condividi tramite