Azure SQL-datakälla för en lösning

Artikel
03/18/2024

Matchningsprincipen sql-data-source konfigurerar en Transact-SQL-begäran (T-SQL) till en Azure SQL-databas och ett valfritt svar för att matcha data för en objekttyp och ett fält i ett GraphQL-schema. Schemat måste importeras till API Management som ett GraphQL-API.

Kommentar

Den här principen är i förhandsversion. För närvarande stöds inte principen på förbrukningsnivån för API Management.

Kommentar

Ange principens element och underordnade element i den ordning som anges i principbeskrivningen. Läs mer om hur du anger eller redigerar API Management-principer.

Principuttryck

<sql-data-source> 
    <connection-info>
        <connection-string use-managed-identity="true | false">
            Azure SQL connection string
        </connection-string>
        <include-fragment>...include-fragment policy configuration...</include-fragment>
        <authentication-certificate>...authentication-certificate policy configuration...</authentication-certificate>     
    </connection-info>
    <include-fragment>...include-fragment policy configuration...</include-fragment>
    <request single-result="true | false">
        <include-fragment>...include-fragment policy configuration...</include-fragment>
        <set-body>...set-body policy configuration...</set-body>
        <sql-statement>T-SQL query</sql-statement>
        <parameters>
            <parameter sql-type="parameter type" name="Query parameter name in @ notation">
                "Query parameter value or expression"
            </parameter>
            <!-- if there are multiple parameters, then add additional parameter elements -->
        </parameters>
    </request>
    <response>
        <include-fragment>...include-fragment policy configuration...</include-fragment>
        <set-body>...set-body policy configuration...</set-body>
        <publish-event>...publish-event policy configuration...</publish-event>
    </response>
</sql-data-source>

Element

Name	beskrivning	Obligatoriskt
connection-info	Anger anslutning till Azure SQL-databas.	Ja
include-fragment	Infogar ett principfragment i principdefinitionen. Om det finns flera fragment lägger du till ytterligare `include-fragment` element.	Nej
Begäran	Anger matcharens T-SQL-begäran och valfria parametrar.	Ja
Svar	Du kan också ange underordnade principer för att konfigurera svaret från Azure SQL-databasen. Om inget anges returneras svaret från Azure SQL som JSON.	Nej

connection-info-element

Kommentar

Förutom där det anges kan varje underordnat element anges högst en gång. Ange element i den ordning som anges.

Element	Description	Obligatoriskt
connection-string	Anger Azure SQL-anslutningssträng. Anslutningssträng använder antingen SQL-autentisering (användarnamn och lösenord) eller Microsoft Entra-autentisering om en hanterad API Management-identitet har konfigurerats.	Ja
include-fragment	Infogar ett principfragment i principdefinitionen. Om det finns flera fragment lägger du till ytterligare `include-fragment` element.	Nej
authentication-certificate	Autentiserar med hjälp av ett klientcertifikat i matcharens SQL-begäran.	Nej

anslutningssträngsattribut

Attribut	beskrivning	Obligatoriskt	Standardvärde
use-managed-identity	Boolesk. Anger om API Management-instansens systemtilldelade hanterade identitet ska användas för anslutning till Azure SQL-databasen i stället för ett användarnamn och lösenord i anslutningssträng. Principuttryck tillåts. Identiteten måste konfigureras för åtkomst till Azure SQL-databasen.	Nej	`false`

begärandeattribut

Attribut	beskrivning	Obligatoriskt	Standardvärde
single-result	Boolesk. Anger om svaret på frågan förväntas returnera en rad som mest. Principuttryck tillåts.	Nej	`false`

begärandeelement

Kommentar

Varje underordnat element kan anges högst en gång. Ange element i den ordning som anges.

Element	Description	Obligatoriskt
include-fragment	Infogar ett principfragment i principdefinitionen.	Nej
set-body	Anger brödtexten i matcharens SQL-begäran.	Nej
sql-instruktion	En T-SQL-instruktion för begäran till Azure SQL-databasen. SQL-instruktionen kan innehålla flera oberoende underdrifter som UPDATE, DELETE och SELECT som ska köras i följd. Resultaten returneras från den slutliga underdriften.	Ja
parameters	En lista över SQL-parametrar i `parameter` underelement för begäran.	Nej

parameterattribut

Attribut	beskrivning	Obligatoriskt	Standardvärde
name	Sträng. Namnet på SQL-parametern.	Ja	Ej tillämpligt
sql-type	Sträng. Datatypen för SQL-parametern.	Nej	Ej tillämpligt

svarselement

Kommentar

Varje underordnat element kan anges högst en gång. Ange element i den ordning som anges.

Name	beskrivning	Obligatoriskt
include-fragment	Infogar ett principfragment i principdefinitionen.	Nej
set-body	Anger brödtexten i matcharens svar.	Nej
publish-event	Publicerar en händelse till en eller flera prenumerationer som anges i GraphQL API-schemat.	Nej

Användning

Principomfattningar: GraphQL-matchare
Gatewayer: klassisk, v2

Användningsanteckningar

Information om hur du konfigurerar och hanterar en lösning med den här principen finns i Konfigurera en GraphQL-matchare.
Den här principen anropas endast när du löser ett enda fält i en matchande åtgärdstyp i schemat.

Konfigurera integrering av hanterad identitet med Azure SQL

Du kan konfigurera en API Management-systemtilldelad hanterad identitet för åtkomst till Azure SQL i stället för att konfigurera SQL-autentisering med användarnamn och lösenord. Bakgrund finns i Konfigurera och hantera Microsoft Entra-autentisering med Azure SQL.

Förutsättningar

Aktivera en systemtilldelad hanterad identitet i din API Management-instans.

Aktivera Microsoft Entra ID-åtkomst

Aktivera Microsoft Entra-autentisering till SQL Database genom att tilldela en Microsoft Entra-användare som administratör för servern.

I portalen går du till din Azure SQL-server.
Välj Microsoft Entra ID.
Välj Ange administratör och välj dig själv eller en grupp som du tillhör.
Välj Spara.

Tilldela roller

I portalen går du till din Azure SQL-databasresurs.
Välj Frågeredigerare (förhandsversion).
Logga in med Active Directory-autentisering.

Kör följande SQL-skript. Ersätt <identity-name> med namnet på din API Management-instans.

CREATE USER [<identity-name>] FROM EXTERNAL PROVIDER;
ALTER ROLE db_datareader ADD MEMBER [<identity-name>];
ALTER ROLE db_datawriter ADD MEMBER [<identity-name>];
ALTER ROLE db_ddladmin ADD MEMBER [<identity-name>];
GO

Exempel

Exempelschema

Exemplen i det här avsnittet är matchare för följande GraphQL-schema:

type Family {
  id: Int!
  name: String!
}

type Person {
  id: Int!
  name: String!
}

type PersonQueryResult {
  items: [Person]  
}

type Query {
  familyById(familyId: Int!): Family
  familyMembers(familyId: Int!): PersonQueryResult
}

type Mutation {
  createFamily(familyId: Int!, familyName: String!): Family
}

Lösare för GraphQL-fråga med T-SQL-begäran med ett enda resultat

Följande exempel löser en GraphQL-fråga genom att göra en T-SQL-begäran med ett enda resultat till en Azure SQL-databas för serverdelen. Anslutningssträng använder SQL-autentisering med användarnamn och lösenord och tillhandahålls med ett namngivet värde. Svaret returneras som ett enda JSON-objekt som representerar en enskild rad.

<sql-data-source>
    <connection-info>
        <connection-string>
            {{my-connection-string}}
        </connection-string>
    </connection-info>
    <request single-result="true">
        <sql-statement>
            SELECT 
                f.[Id] AS [id]
                f.[Name] AS [name]
            WHERE @familyId = f.[Id] 
        </sql-statement> 
        <parameters> 
            <parameter name="@familyId">       
                @(context.GraphQL.Arguments["id"])
            </parameter> 
        </parameters> 
    </request>
    <response />
</sql-data-source>

Lösning för GraphQL-fråga med transformerat frågesvar med flera rader

I följande exempel löses en GraphQL-fråga med hjälp av en T-SQL-fråga till en Azure SQL-databas. Anslutningen till databasen använder API Management-instansens systemtilldelade hanterade identitet. Identiteten måste konfigureras för åtkomst till Azure SQL-databasen.

Frågeparametern används med hjälp av context.GraphQL.Arguments kontextvariabeln. Frågesvaret set-body med flera rader transformeras med hjälp av principen med en flytande mall.

<sql-data-source> 
    <connection-info>
        <connection-string use-managed-identity="true">
            Server=tcp:{your_server_name}.database.windows.net,1433;Initial Catalog={your_database_name}; 
        </connection-string>
    </connection-info> 
    <request> 
        <sql-statement> 
            SELECT 
                p.[Id] AS [Id] 
                p.[FirstName] AS [FirstName] 
                p.[LastName] AS [LastName] 
            FROM [Person] p 
            JOIN [Family] f ON p.[FamilyId] = f.[Id] 
            WHERE @familyId = f.[Id] 
        </sql-statement> 
        <parameters> 
            <parameter name="@familyId">       
                @(context.GraphQL.Arguments["id"])
            </parameter> 
        </parameters> 
    </request> 
    <response> 
        <set-body template="liquid"> 
            { 
                "items": [ 
                    {% JSONArray For person in body.items %} 
                        "id": "{{ person.id }}" 
                        "name": "{{ person.firstName }} + "" "" + {{body.lastName}}" 
                    {% endJSONArrayFor %} 
                ] 
            } 
        </set-body> 
  </response> 
</sql-data-source>

Lösning för GraphQL-mutation

I följande exempel matchas en GraphQL-mutation med hjälp av en T-SQL INSERT-instruktion för att infoga en rad i en Azure SQL-databas. Anslutningen till databasen använder API Management-instansens systemtilldelade hanterade identitet. Identiteten måste konfigureras för åtkomst till Azure SQL-databasen.

<sql-data-source> 
    <connection-info>
        <connection-string use-managed-identity="true">
            Server=tcp:{your_server_name}.database.windows.net,1433;Initial Catalog={your_database_name};</connection-string>
    </connection-info> 
    <request single-result="true"> 
        <sql-statement> 
                INSERT INTO [dbo].[Family]
                       ([Id]
                       ,[Name])
                VALUES
                       (@familyId
                       , @familyName)

                SELECT
                    f.[Id] AS [id],
                    f.[Name] AS [name]
                FROM [Family] f
                WHERE @familyId = f.[Id]
        </sql-statement> 
        <parameters> 
            <parameter name="@familyId">       
                @(context.GraphQL.Arguments["id"])
            </parameter>
            <parameter name="@familyName">       
                @(context.GraphQL.Arguments["name"])
            </parameter> 
        </parameters> 
    </request>    
</sql-data-source>

GraphQL-matchare

Mer information om hur du arbetar med principer finns i:

Självstudie: Transformera och skydda ditt API
Principreferens för en fullständig lista över principinstruktioner och deras inställningar
Principuttryck
Ange eller redigera principer
Återanvända principkonfigurationer
Lagringsplats för principfragment
Skapa principer med Hjälp av Microsoft Copilot för Azure

Azure SQL-datakälla för en lösning

Principuttryck

Element

connection-info-element

anslutningssträngsattribut

begärandeattribut

begärandeelement

parameterattribut

svarselement

Användning

Användningsanteckningar

Konfigurera integrering av hanterad identitet med Azure SQL

Förutsättningar

Aktivera Microsoft Entra ID-åtkomst

Tilldela roller

Exempel

Exempelschema

Lösare för GraphQL-fråga med T-SQL-begäran med ett enda resultat

Lösning för GraphQL-fråga med transformerat frågesvar med flera rader

Lösning för GraphQL-mutation

Relaterade principer

Relaterat innehåll

Ytterligare resurser