Importera ett GraphQL-schema och konfigurera fältmatchare

  • Artikel
  • 4 minuter för att läsa

GraphQL är ett frågespråk med öppen källkod och branschstandard för API:er. Till skillnad från slutpunktsbaserade API:er (eller REST-format) som utformats för åtgärder över resurser stöder GraphQL-API:er en bredare uppsättning användningsfall och fokuserar på datatyper, scheman och frågor.

Med API Management för att exponera graphQL-API:er kan du:

  • Lägga till ett GraphQL-slutpunkt eller GraphQL-schema som ett API via Azure-portalen, Azure CLI eller andra Azure-verktyg.
  • (Förhandsversion) Utöka eller utforma ett GraphQL API med hjälp av information från REST- eller SOAP-API:er, med http-matchare för fält som definierats i ett GraphQL-schema.
  • Skydda GraphQL-API:er genom att tillämpa både befintliga principer för åtkomstkontroll och en GraphQL-valideringsprincip för att skydda och skydda mot GraphQL-specifika attacker.
  • Utforska schemat och kör testfrågor mot GraphQL-API:erna i Azure- och utvecklarportalerna.

Anteckning

  • Ett enda GraphQL-API i API Management kan mappas till en enda GraphQL-serverdelsslutpunkt.
  • Ett GraphQL-API kräver ett GraphQL-schema, antingen från en befintlig GraphQL-slutpunkt eller uppladdat av dig.
  • API Management stöder åtgärdstyper för frågor, mutationer och prenumerationer i GraphQL-scheman.
  • Prenumerationer stöds inte på tjänstnivån Förbrukning.
  • En prenumeration måste implementeras med hjälp av WebSocket-protokollet graphql-ws. Frågor och mutationer stöds inte via WebSocket.

Viktigt

Konfiguration av matchare för GraphQL-frågor är för närvarande i förhandsversion. Den här funktionen är inte tillgänglig på förbrukningstjänstnivån eller i gatewayen med egen värd.

I den här artikeln ska du:

  • Importera ett GraphQL-schema till din API Management-instans
  • Konfigurera en matchare för en GraphQL-fråga med hjälp av en befintlig HTTP-slutpunkter
  • Testa GraphQL-API:et

Om du vill exponera en befintlig GraphQL-slutpunkt som ett API läser du Importera ett GraphQL-API.

Förutsättningar

  • En befintlig API Management instans. Skapa en om du inte redan har gjort det.
  • En giltig GraphQL-schemafil med .graphql tillägget .
  • En GraphQL-slutpunkt för serverdelen är valfri för det här scenariot.

Gå till API Management-instansen

  1. I Azure Portal söker du efter och väljer API Management tjänster.

    Välj API Management tjänster

  2. På sidan API Management tjänster väljer du din API Management-instans.

    Välj din API Management-instans

Lägga till ett GraphQL-schema

  1. I sidonavigeringsmenyn går du till avsnittet API:er och väljer API:er.

  2. Under Definiera ett nytt API väljer du ikonen Syntetisk GraphQL .

    Skärmbild av att välja ikonen Syntetisk GraphQL i listan över API:er.

  3. I dialogrutan väljer du Fullständig och fyller i de obligatoriska formulärfälten.

    Skärmbild av fält för att skapa ett GraphQL-API.

    Fält Beskrivning
    Visningsnamn Namnet som GraphQL-API:et ska visas med.
    Namn Rånamn för GraphQL-API:et. Fylls i automatiskt när du skriver visningsnamnet.
    Återställningspunkt för GraphQL-slutpunkt I det här scenariot kan du ange en URL med ett GraphQL API-slutpunktsnamn. API Management skickar GraphQL-frågor till den här slutpunkten när en anpassad matchare inte har angetts för ett fält.
    Ladda upp schemafil Välj att bläddra och ladda upp en giltig GraphQL-schemafil med .graphql tillägget .
    Beskrivning Lägg till en beskrivning av ditt API.
    URL-schema Välj HTTP, HTTPS eller Båda. Standardval: Båda.
    API URL-suffix Lägg till ett URL-suffix för att identifiera det här specifika API:et i den här API Management-instansen. Det måste vara unikt i den här API Management instansen.
    Grundläggande URL Ett fält som inte kan redigeras visar din API-bas-URL
    Taggar Associera GraphQL-API:et med nya eller befintliga taggar.
    Produkter Associera GraphQL-API:et med en produkt för att publicera det.
    Gateways Associera GraphQL-API:et med befintliga gatewayer. Standardalternativ för gateway: Hanterad.
    Vilken är versionen för det här API:et? Välj att tillämpa ett versionsschema på GraphQL-API:et.

  4. Välj Skapa.

  5. När API:et har skapats bläddrar du i schemat på fliken Design i avsnittet Klientdel .

Konfigurera matchare

Konfigurera principen set-graphql-resolver för att mappa ett fält i schemat till en befintlig HTTP-slutpunkt.

Anta att du importerade följande grundläggande GraphQL-schema och ville konfigurera en matchare för användarfrågan .

type Query {
    users: [User]
}

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

  1. I sidonavigeringsmenyn går du till avsnittet API:er och väljer API:er> för ditt GraphQL-API.

  2. På fliken Design i GraphQL API väljer du Alla åtgärder.

  3. I avsnittet Serverdelsbearbetning väljer du + Lägg till princip.

  4. set-graphql-resolver Konfigurera principen för att lösa användarfrågan med hjälp av en HTTP-datakälla.

    Följande set-graphql-resolver princip hämtar till exempel fältet användare med hjälp av ett GET anrop på en befintlig HTTP-datakälla.

    <set-graphql-resolver parent-type="Query" field="users">
    <http-data-source>
        <http-request>
            <set-method>GET</set-method>
            <set-url>https://myapi.contoso.com/users</set-url>
        </http-request>
    </http-data-source>
</set-graphql-resolver>

  5. Om du vill lösa data för andra fält i schemat upprepar du föregående steg.

  6. Välj Spara.

Testa GraphQL-API:et

  1. Gå till din API Management-instans.

  2. I sidonavigeringsmenyn går du till avsnittet API:er och väljer API:er.

  3. Under Alla API:er väljer du ditt GraphQL-API.

  4. Välj fliken Test för att komma åt testkonsolen.

  5. Under Rubriker:

    1. Välj rubriken i den nedrullningsbara menyn Namn .
    2. Ange värdet i fältet Värde .
    3. Lägg till fler rubriker genom att välja + Lägg till rubrik.
    4. Ta bort rubriker med hjälp av papperskorgsikonen.

  6. Om du har lagt till en produkt i GraphQL-API:et tillämpar du produktomfånget under Tillämpa produktomfång.

  7. Under Frågeredigeraren:

    1. Välj minst ett fält eller underfält i listan på sidomenyn. De fält och underfält som du väljer visas i frågeredigeraren.

    2. Börja skriva i frågeredigeraren för att skapa en fråga.

      Skärmbild av att lägga till fält i frågeredigeraren.

  8. Under Frågevariabler lägger du till variabler för att återanvända samma fråga eller mutation och skicka olika värden.

  9. Välj Skicka.

  10. Visa svaret.

    Skärmbild av att visa testfrågesvaret.

  11. Upprepa föregående steg för att testa olika nyttolaster.

  12. När testningen är klar avslutar du testkonsolen.

Anteckning

Du kan testa en prenumeration i testkonsolen:

  • Konfigurera en prenumerationsfråga i frågeredigeraren och välj sedan Anslut för att upprätta en WebSocket-anslutning till serverdelstjänsten.
  • Granska anslutningsinformationen i fönstret Prenumeration .
  • WebSocket-anslutningen upprätthålls tills du kopplar från den eller ansluter till en ny WebSocket-prenumeration.

Nästa steg

Omvandla och skydda ett publicerat API