Konfigurera en GraphQL-matchare

Artikel
12/09/2023

GÄLLER FÖR: Alla API Management-nivåer

Konfigurera en matchare för att hämta eller ange data för ett GraphQL-fält i en objekttyp som anges i ett GraphQL-schema. Schemat måste importeras till API Management som ett GraphQL-API.

API Management stöder för närvarande matchare som kan komma åt följande datakällor:

HTTP-baserad datakälla (REST eller SOAP API)
Cosmos DB-databas
Azure SQL-databas

Bra att känna till

En matchare är en resurs som innehåller en principdefinition som bara anropas när en matchande objekttyp och ett fält i schemat körs.
Varje matchare löser data för ett enda fält. Om du vill lösa data för flera fält konfigurerar du en separat lösning för var och en.
Principer med matchareomfattning utvärderas efter alla inbound principer och backend principer i pipelinen för principkörning. De ärver inte principer från andra omfång. Mer information finns i Principer i API Management.
Du kan konfigurera API-omfångsprinciper för ett GraphQL-API, oberoende av principerna med matchningsomfång. Lägg till exempel till en policy för valid-graphql-request i omfånget inbound för att verifiera begäran innan matcharen anropas. Konfigurera API-omfångsprinciper på fliken API-principer för API:et.

Förutsättningar

En befintlig API Management-instans. Skapa en om du inte redan har gjort det.
Importera ett direkt- eller syntetiskt GraphQL-API.

Skapa en lösning

Följande steg skapar en lösning med hjälp av en HTTP-baserad datakälla. De allmänna stegen liknar alla matchare som använder en datakälla som stöds.

I Azure-portalen går du till din API Management-instans.
I den vänstra menyn väljer du API:er och sedan namnet på graphQL-API:et.
På fliken Schema granskar du schemat för ett fält i en objekttyp där du vill konfigurera en matchare.
1. Välj ett fält och hovra sedan pekaren i vänstermarginalen.
2. Välj + Lägg till lösen.
På sidan Skapa lösning :
1. Uppdatera egenskapen Namn om du vill, om du vill, ange en Beskrivning och bekräfta eller uppdatera markeringen Typ och Fält.
2. Välj matcharens datakälla. I det här exemplet väljer du HTTP API.
Uppdatera principen med underordnade element för ditt scenario i Redigeraren för resolver-principerhttp-data-source.
1. Uppdatera det nödvändiga http-request elementet med principer för att omvandla GraphQL-åtgärden till en HTTP-begäran.
2. Du kan också lägga till ett http-response element och lägga till underordnade principer för att transformera HTTP-svaret för matcharen. Om elementet http-response inte anges returneras svaret som en råsträng.
3. Välj Skapa.
Matcharen är kopplad till fältet och visas på fliken Matchare .

Hantera matchare

Lista och hantera matcharna för ett GraphQL-API på fliken Matchare för API:et.

På fliken Matchare :

Kolumnen Länkad anger om matcharen är konfigurerad för ett fält som för närvarande finns i GraphQL-schemat. Om en lösning inte är länkad kan den inte anropas.
I snabbmenyn (...) för en matchare hittar du kommandon för att klona, redigera eller ta bort en matchare. Klona en listad matchare för att snabbt skapa en liknande lösning som riktar sig mot en annan typ och ett annat fält.
Du kan skapa en ny lösning genom att välja + Skapa.

Redigera och testa en lösning

När du redigerar en enskild matchare öppnas sidan Redigera matchare . Du kan:

Uppdatera matchningsprincipen och eventuellt datakällan. Om du ändrar datakällan skrivs den aktuella matchningsprincipen över.
Ändra den typ och det fält som matcharen riktar in sig på.
Testa och felsöka matcharens konfiguration. När du redigerar matchningsprincipen väljer du Kör test för att kontrollera utdata från datakällan, som du kan verifiera mot schemat. Om fel inträffar innehåller svaret felsökningsinformation.

GraphQL-kontext

Kontexten för matcharens begäran och svar (om det anges) skiljer sig från kontexten för den ursprungliga gateway-API-begäran:
- context.GraphQL egenskaperna anges till argumenten (Arguments) och det överordnade objektet (Parent) för den aktuella matchningskörningen.
- Begärandekontexten innehåller argument som skickas i GraphQL-frågan som brödtext.
- Svarskontexten är svaret från det oberoende anropet som görs av matcharen, inte kontexten för det fullständiga svaret för gatewaybegäran. Variabeln context som skickas via pipelinen för begäran och svar utökas med GraphQL-kontexten när den används med en GraphQL-matchare.

Sammanhang. GraphQL.parent

context.GraphQL.parent är inställt på det överordnade objektet för den aktuella matchningskörningen. Överväg följande partiella schema:

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
}

Överväg också en GraphQL-fråga för all information för en specifik blogg:

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

Om du anger en lösning för comments fältet i Blog typen vill du förstå vilket blogg-ID som ska användas. Du kan hämta ID:t för bloggen med hjälp av context.GraphQL.Parent["id"] det som visas i följande lösning:

<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>

Sammanhang. GraphQL.Arguments

Argumenten för en parameteriserad GraphQL-fråga läggs till i context.GraphQL.Arguments. Tänk till exempel på följande två frågor:

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

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

Dessa frågor är två sätt att anropa matcharen getComment . GraphQL skickar följande JSON-nyttolast:

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

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

Du kan definiera matcharen på följande sätt:

<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>

Nästa steg

Fler lösningsexempel finns i: