Condividi tramite

Origine dati di Azure SQL per un resolver

  • Articolo

SI APPLICA A: Sviluppatore | Basic | Basic v2 | Standard | Standard v2 | Premium | Premium v2

Il criterio resolver sql-data-source configura una richiesta Transact-SQL (T-SQL) a un database SQL di Azure e una risposta facoltativa per risolvere i dati per un tipo di oggetto e un campo in uno schema GraphQL. Lo schema deve essere importato in API Management come API GraphQL.

Nota

Questo criterio è in anteprima. Attualmente, i criteri non sono supportati nel livello a consumo di API Management.

Nota

Impostare gli elementi e gli elementi figlio del criterio nell'ordine specificato nell'istruzione del criterio. Altre informazioni su come impostare o modificare i criteri di API Management.

Istruzione del criterio

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

Elementi

Nome Descrizione Richiesto
connection-info Specifica la connessione al database SQL di Azure. Sì
include-fragment Inserisce un frammento di criterio nella definizione del criterio. Se sono presenti più frammenti, aggiungere altri elementi include-fragment. No
request Specifica la richiesta T-SQL del sistema di risoluzione e i parametri facoltativi. Sì
risposta Facoltativamente, specifica i criteri figlio per configurare la risposta dal database SQL di Azure. Se non specificato, la risposta viene restituita da Azure SQL come JSON. No

elementi connection-info

Nota

Tranne dove indicato, ogni elemento figlio può essere specificato al massimo una volta. Specificare gli elementi nell'ordine elencato.

Elemento Descrizione Richiesto
connection-string Specifica la stringa di connessione SQL di Azure. La stringa di connessione usa l'autenticazione SQL (nome utente e password) o l'autenticazione di Microsoft Entra se è configurata un'identità gestita di API Management. Sì
include-fragment Inserisce un frammento di criterio nella definizione del criterio. Se sono presenti più frammenti, aggiungere altri elementi include-fragment. No
authentication-certificate Esegue l'autenticazione usando un certificato client nella richiesta SQL del resolver. No

attributi connection-string

Attributo Descrizione Richiesto Valore predefinito
use-managed-identity Booleano. Specifica se usare l'identità gestita assegnata dal sistema dell'istanza di API Management per la connessione al database SQL di Azure al posto di un nome utente e password nella stringa di connessione. Le espressioni di criteri sono consentite.

È necessario configurare l'entità per accedere al database SQL di Azure.		 No false

attributo della richiesta

Attributo Descrizione Richiesto Valore predefinito
single-result Booleano. Specifica se la risposta alla query deve restituire al massimo una riga. Le espressioni di criteri sono consentite. No false

elementi della richiesta

Nota

Ogni elemento figlio può essere specificato al massimo una volta. Specificare gli elementi nell'ordine elencato.

Elemento Descrizione Richiesto
include-fragment Inserisce un frammento di criterio nella definizione del criterio. No
set-body Imposta il corpo nella richiesta SQL del resolver. No
sql-statement Istruzione T-SQL per la richiesta al database SQL di Azure. L'istruzione SQL può includere più sotto-istruzioni indipendenti, ad esempio UPDATE, DELETE e SELECT che verranno eseguite in sequenza. I risultati vengono restituiti dall'ultima sotto-istruzione. Sì
parameters Elenco di parametri SQL, in sotto-elementi parameter, per la richiesta. No

attributi del parametro

Attributo Descrizione Richiesto Valore predefinito
name String. Nome del parametro SQL. Sì N/D
sql-type String. Tipo di dati del parametro SQL. No N/D

elementi della risposta

Nota

Ogni elemento figlio può essere specificato al massimo una volta. Specificare gli elementi nell'ordine elencato.

Nome Descrizione Richiesto
include-fragment Inserisce un frammento di criterio nella definizione del criterio. No
set-body Imposta il corpo nella risposta del resolver. No
publish-event Pubblica un evento in una o più sottoscrizioni specificate nello schema dell'API GraphQL. No

Utilizzo

Note sull'utilizzo

  • Per configurare e gestire un resolver con questo criterio, vedere Configurare un resolver GraphQL.
  • Questo criterio viene richiamato solo quando si risolve un singolo campo in un tipo di operazione corrispondente nello schema.

Configurare l'integrazione dell'identità gestita con Azure SQL

È possibile configurare un'identità gestita assegnata dal sistema di API Management per l'accesso ad Azure SQL anziché configurare l'autenticazione SQL con nome utente e password. Per le informazioni di riferimento, vedere a Configurare e gestire l'autenticazione di Microsoft Entra con Azure SQL.

Prerequisiti

  • Abilitare un'identità gestita assegnata dal sistema nell'istanza di API Management.

Abilita accesso Microsoft Entra ID

Abilitare l'autenticazione di Microsoft Entra nel database SQL assegnando un utente di Microsoft Entra come amministratore del server.

  1. Nel portale andare al server SQL di Azure.
  2. Selezionare Microsoft Entra ID.
  3. Selezionare Imposta amministratore e selezionare se stessi o un gruppo a cui si appartiene.
  4. Seleziona Salva.

Assegnazione di ruoli

  1. Nel portale andare alla risorsa del database SQL di Azure.

  2. Selezionare Editor di query (anteprima).

  3. Accedere con l'autenticazione Active Directory.

  4. Eseguire lo script SQL seguente. Sostituire <identity-name> con il nome dell'istanza di API Management.

    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

Esempi

Schema di esempio

Gli esempi in questa sezione sono resolver per lo schema GraphQL seguente:

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 per la query GraphQL usando una richiesta T-SQL a risultato singolo

L'esempio seguente risolve una query GraphQL effettuando una richiesta T-SQL a risultato singolo a un database SQL di Azure back-end. La stringa di connessione usa l'autenticazione SQL con nome utente e password e viene fornita usando un valore denominato. La risposta viene restituita come singolo oggetto JSON che rappresenta una singola riga.

<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 per la query GraphQL con risposta di query a più righe trasformata

L'esempio seguente risolve una query GraphQL usando una query T-SQL in un database SQL di Azure. La connessione al database usa l'identità gestita assegnata dal sistema dell'istanza di API Management. È necessario configurare l'entità per accedere al database SQL di Azure.

È possibile accedere al parametro di query usando la variabile di contesto context.GraphQL.Arguments. La risposta di query su più righe viene trasformata usando i criteri set-body con un modello Liquid.

<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 per una mutazione GraphQL

L'esempio seguente risolve una mutazione GraphQL usando un'istruzione T-SQL INSERT per inserire una riga di un database SQL di Azure. La connessione al database usa l'identità gestita assegnata dal sistema dell'istanza di API Management. È necessario configurare l'entità per accedere al database SQL di Azure.

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

Contenuto correlato

Per ulteriori informazioni sull'utilizzo dei criteri, vedere: