Azure SQL-gegevensbron voor een resolver

Artikel
04/04/2024

Het sql-data-source resolver-beleid configureert een Transact-SQL-aanvraag (T-SQL) voor een Azure SQL-database en een optioneel antwoord om gegevens voor een objecttype en veld in een GraphQL-schema op te lossen. Het schema moet als GraphQL-API worden geïmporteerd in API Management.

Notitie

Dit beleid is in preview. Het beleid wordt momenteel niet ondersteund in de verbruikslaag van API Management.

Notitie

Stel de elementen en onderliggende elementen van het beleid in de volgorde in die in de beleidsverklaring is opgegeven. Meer informatie over het instellen of bewerken van API Management-beleid.

Beleidsinstructie

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

Elementen

Name	Beschrijving	Vereist
connection-info	Hiermee geeft u verbinding met Azure SQL-database.	Ja
include-fragment	Hiermee voegt u een beleidsfragment in de beleidsdefinitie in. Als er meerdere fragmenten zijn, voegt u extra `include-fragment` elementen toe.	Nee
Verzoek	Hiermee geeft u de T-SQL-aanvraag van de resolver en optionele parameters.	Ja
Reactie	Optioneel geeft u onderliggend beleid op om het antwoord van de Azure SQL-database te configureren. Als dit niet is opgegeven, wordt het antwoord geretourneerd vanuit Azure SQL als JSON.	Nee

verbindings-info-elementen

Notitie

Behalve waar vermeld, kan elk onderliggend element maximaal één keer worden opgegeven. Geef elementen op in de vermelde volgorde.

Element	Beschrijving	Vereist
connection-string	Hiermee geeft u de Azure SQL-verbindingsreeks. De verbindingsreeks maakt gebruik van SQL-verificatie (gebruikersnaam en wachtwoord) of Microsoft Entra-verificatie als een beheerde API Management-identiteit is geconfigureerd.	Ja
include-fragment	Hiermee voegt u een beleidsfragment in de beleidsdefinitie in. Als er meerdere fragmenten zijn, voegt u extra `include-fragment` elementen toe.	Nee
verificatiecertificaat	Verifieert met behulp van een clientcertificaat in de SQL-aanvraag van de resolver.	Nee

verbindingsreekskenmerken

Kenmerk	Beschrijving	Vereist	Standaardinstelling
use-managed-identity	Booleaans. Hiermee geeft u op of de door het systeem toegewezen beheerde identiteit van het API Management-exemplaar moet worden gebruikt voor verbinding met de Azure SQL-database in plaats van een gebruikersnaam en wachtwoord in de verbindingsreeks. Beleidsexpressies zijn toegestaan. De identiteit moet worden geconfigureerd voor toegang tot de Azure SQL-database.	Nee	`false`

aanvraagkenmerk

Kenmerk	Beschrijving	Vereist	Standaardinstelling
enkel resultaat	Booleaans. Hiermee geeft u op of het antwoord op de query naar verwachting één rij retourneert. Beleidsexpressies zijn toegestaan.	Nee	`false`

aanvraagelementen

Notitie

Elk onderliggend element kan maximaal één keer worden opgegeven. Geef elementen op in de vermelde volgorde.

Element	Beschrijving	Vereist
include-fragment	Hiermee voegt u een beleidsfragment in de beleidsdefinitie in.	Nee
set-body	Hiermee stelt u de hoofdtekst in de SQL-aanvraag van de resolver in.	Nee
sql-statement	Een T-SQL-instructie voor de aanvraag naar de Azure SQL-database. De SQL-instructie kan meerdere onafhankelijke substatementen bevatten, zoals UPDATE, DELETE en SELECT, die op volgorde worden uitgevoerd. Resultaten worden geretourneerd vanuit de laatste substatement.	Ja
parameters	Een lijst met SQL-parameters, in `parameter` subelementen, voor de aanvraag.	Nee

parameterkenmerken

Kenmerk	Beschrijving	Vereist	Standaardinstelling
naam	Tekenreeks. De naam van de SQL-parameter.	Ja	N.v.t.
sql-type	Tekenreeks. Het gegevenstype van de SQL-parameter.	Nee	N.v.t.

antwoordelementen

Notitie

Elk onderliggend element kan maximaal één keer worden opgegeven. Geef elementen op in de vermelde volgorde.

Name	Beschrijving	Vereist
include-fragment	Hiermee voegt u een beleidsfragment in de beleidsdefinitie in.	Nee
set-body	Hiermee stelt u de hoofdtekst in het antwoord van de resolver in.	Nee
publish-event	Hiermee publiceert u een gebeurtenis naar een of meer abonnementen die zijn opgegeven in het GraphQL API-schema.	Nee

Gebruik

Beleidsbereiken: GraphQL-resolver
Gateways: klassiek, v2

Gebruiksnotities

Als u een resolver met dit beleid wilt configureren en beheren, raadpleegt u Een GraphQL-resolver configureren.
Dit beleid wordt alleen aangeroepen bij het omzetten van één veld in een overeenkomend bewerkingstype in het schema.

Integratie van beheerde identiteiten configureren met Azure SQL

U kunt een door het API Management-systeem toegewezen beheerde identiteit configureren voor toegang tot Azure SQL in plaats van SQL-verificatie te configureren met gebruikersnaam en wachtwoord. Zie Microsoft Entra-verificatie configureren en beheren met Azure SQL voor achtergrond.

Vereisten

Schakel een door het systeem toegewezen beheerde identiteit in uw API Management-exemplaar in.

Toegang tot Microsoft Entra-id inschakelen

Schakel Microsoft Entra-verificatie in voor SQL Database door een Microsoft Entra-gebruiker toe te wijzen als beheerder van de server.

Ga in de portal naar uw Azure SQL-server.
Selecteer Microsoft Entra ID.
Selecteer Beheerder instellen en selecteer uzelf of een groep waartoe u behoort.
Selecteer Opslaan.

Rollen toewijzen

Ga in de portal naar uw Azure SQL-databaseresource.
Selecteer Query-editor (preview).
Meld u aan met Active Directory-verificatie.

Voer het volgende SQL-script uit. Vervang door <identity-name> de naam van uw API Management-exemplaar.

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

Voorbeelden

Voorbeeldschema

De voorbeelden in deze sectie zijn resolvers voor het volgende 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
}

Resolver voor GraphQL-query met behulp van T-SQL-aanvraag met één resultaat

In het volgende voorbeeld wordt een GraphQL-query omgezet door een T-SQL-aanvraag met één resultaat te maken voor een Back-end Azure SQL-database. De verbindingsreeks maakt gebruik van SQL-verificatie met gebruikersnaam en wachtwoord en wordt geleverd met behulp van een benoemde waarde. Het antwoord wordt geretourneerd als één JSON-object dat één rij vertegenwoordigt.

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

Resolver voor GraphQL-query met getransformeerde queryreacties met meerdere rijen

In het volgende voorbeeld wordt een GraphQL-query omgezet met behulp van een T-SQL-query naar een Azure SQL-database. De verbinding met de database maakt gebruik van de door het systeem toegewezen beheerde identiteit van het API Management-exemplaar. De identiteit moet worden geconfigureerd voor toegang tot de Azure SQL-database.

De queryparameter wordt geopend met behulp van de context.GraphQL.Arguments contextvariabele. Het queryantwoord met meerdere rijen wordt getransformeerd met behulp van het set-body beleid met een liquide sjabloon.

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

Resolver voor GraphQL mutatie

In het volgende voorbeeld wordt een GraphQL-mutatie opgelost met behulp van een T-SQL INSERT-instructie om een rij in een Azure SQL-database in te voegen. De verbinding met de database maakt gebruik van de door het systeem toegewezen beheerde identiteit van het API Management-exemplaar. De identiteit moet worden geconfigureerd voor toegang tot de Azure SQL-database.

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

Zie voor meer informatie over het werken met beleid:

Zelfstudie: Uw API transformeren en beveiligen
Beleidsreferentie voor een volledige lijst met beleidsinstructies en hun instellingen
Beleidsexpressies
Beleid instellen of bewerken
Beleidsconfiguraties opnieuw gebruiken
Beleidsfragmentenopslagplaats
Beleid ontwerpen met Behulp van Microsoft Copilot voor Azure

Azure SQL-gegevensbron voor een resolver

Beleidsinstructie

Elementen

verbindings-info-elementen

verbindingsreekskenmerken

aanvraagkenmerk

aanvraagelementen

parameterkenmerken

antwoordelementen

Gebruik

Gebruiksnotities

Integratie van beheerde identiteiten configureren met Azure SQL

Vereisten

Toegang tot Microsoft Entra-id inschakelen

Rollen toewijzen

Voorbeelden

Voorbeeldschema

Resolver voor GraphQL-query met behulp van T-SQL-aanvraag met één resultaat

Resolver voor GraphQL-query met getransformeerde queryreacties met meerdere rijen

Resolver voor GraphQL mutatie

Gerelateerd beleid

Gerelateerde inhoud

Aanvullende resources