Origine dati SQL di Azure per un sistema di risoluzione

  • Articolo

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

Il sql-data-source criterio resolver 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 Gestione API come API GraphQL.

Nota

Questo criterio è in anteprima. Attualmente, il criterio non è supportato nel livello Consumo di Gestione API.

Nota

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

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 criteri nella definizione dei criteri. Se sono presenti più frammenti, aggiungere altri include-fragment elementi. 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 di 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 il stringa di connessione SQL di Azure. Il stringa di connessione usa l'autenticazione SQL (nome utente e password) o l'autenticazione di Microsoft Entra se è configurata un'identità gestita Gestione API. Sì
include-fragment Inserisce un frammento di criteri nella definizione dei criteri. Se sono presenti più frammenti, aggiungere altri include-fragment elementi. No
authentication-certificate Esegue l'autenticazione usando un certificato client nella richiesta SQL del sistema di risoluzione. No

attributi della stringa di connessione

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

L'identità deve essere configurata per accedere al database SQL di Azure.		 No false

attributo request

Attributo Descrizione Richiesto Valore predefinito
risultato singolo 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 criteri nella definizione dei criteri. No
set-body Imposta il corpo nella richiesta SQL del sistema di risoluzione. No
sql-statement Istruzione T-SQL per la richiesta al database SQL di Azure. L'istruzione SQL può includere più sottostatementi indipendenti, ad esempio UPDATE, DELETE e edizione Standard LECT che verranno eseguiti in sequenza. I risultati vengono restituiti dall'ultima sottostatement. Sì
parameters Elenco di parametri SQL, in parameter sottoelementi, per la richiesta. No

attributi dei parametri

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 di 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 criteri nella definizione dei criteri. No
set-body Imposta il corpo nella risposta del sistema di risoluzione. 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 Gestione API per l'accesso ad Azure SQL anziché configurare l'autenticazione SQL con nome utente e password. Per informazioni generali, vedere Configurare e gestire l'autenticazione di Microsoft Entra con Azure SQL.

Prerequisiti

Abilitare l'accesso a Microsoft Entra ID

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

  1. Nel portale passare 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 passare alla risorsa del database SQL di Azure.

  2. Selezionare Editor di query (anteprima).

  3. Accedere con l'autenticazione di Active Directory.

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

    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. Il stringa di connessione usa l'autenticazione SQL con nome utente e password e viene fornito 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 Gestione API. L'identità deve essere configurata per accedere al database SQL di Azure.

È possibile accedere al parametro di query usando la variabile di context.GraphQL.Arguments contesto. La risposta di query su più righe viene trasformata usando i set-body criteri 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 la mutazione graphQL

L'esempio seguente risolve una mutazione GraphQL usando un'istruzione T-SQL IN edizione Standard RT per inserire una riga di un database SQL di Azure. La connessione al database usa l'identità gestita assegnata dal sistema dell'istanza di Gestione API. L'identità deve essere configurata 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: