Source de données Azure SQL pour un résolveur

  • Article

S’APPLIQUE À : Développeur | Essentiel | Essentiel v2 | Standard | Standard v2 | Premium

La stratégie du résolveur sql-data-source configure une requête Transact-SQL (T-SQL) sur une base de données Azure SQL et une réponse facultative pour résoudre les données d’un type d’objet et d’un champ dans un schéma GraphQL. Le schéma doit être importé dans Gestion des API en tant qu’API GraphQL.

Notes

Cette stratégie est en préversion. Actuellement, la stratégie n’est pas prise en charge dans le niveau Consommation de Gestion des API.

Notes

Définissez les éléments enfants et de stratégie dans l’ordre fourni dans l’instruction de stratégie. En savoir plus sur comment définir ou modifier des stratégies du service Gestion des API.

Instruction de la stratégie

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

Éléments

Nom Description Obligatoire
informations de connexion Spécifie une connexion à une base de données Azure SQL. Oui
include-fragment Insère un fragment de stratégie dans la définition de la stratégie. S’il existe plusieurs fragments, ajoutez les éléments include-fragment supplémentaires. Non
requête Spécifie la requête T-SQL du résolveur et les paramètres facultatifs. Oui
response Spécifie éventuellement des stratégies enfants pour configurer la réponse à partir de la base de données Azure SQL. Si elle n’est pas spécifiée, la réponse est retournée à partir d’Azure SQL au format JSON. Non

Éléments connection-info

Notes

Sauf mention contraire, chaque élément enfant ne peut être spécifié qu’une fois. Indiquez les éléments dans l’ordre indiqué.

Élément Description Obligatoire
connection-string Spécifie la chaîne de connexion à Azure SQL. La chaîne de connexion utilise l’authentification SQL (nom d’utilisateur et mot de passe) ou l’authentification Microsoft Entra en cas de configuration d’une identité managée Gestion des API. Oui
include-fragment Insère un fragment de stratégie dans la définition de la stratégie. S’il existe plusieurs fragments, ajoutez les éléments include-fragment supplémentaires. Non
authentication-certificate S’authentifie à l’aide d’un certificat client dans la requête SQL du résolveur. Non

Attributs connection-string

Attribut Description Obligatoire Default
use-managed-identity Propriété booléenne. Spécifie s’il faut utiliser l’identité managée affectée par le système de l’instance Gestion des API pour la connexion à une base de données Azure SQL au lieu d’un nom d’utilisateur et d’un mot de passe dans la chaîne de connexion. Les expressions de stratégie sont autorisées.

L’identité doit être configurée pour accéder à la base de données Azure SQL.		 Non false

attribut de la requête

Attribut Description Obligatoire Default
single-result Propriété booléenne. Spécifie si la réponse à la requête est censée retourner une ligne au maximum. Les expressions de stratégie sont autorisées. Non false

Éléments de la requête

Notes

Chaque élément enfant ne peut être spécifié qu’une fois. Indiquez les éléments dans l’ordre indiqué.

Élément Description Obligatoire
include-fragment Insère un fragment de stratégie dans la définition de la stratégie. Non
set-body Définit le corps dans la requête SQL du résolveur. Non
sql-statement Instruction T-SQL pour la requête à la base de données Azure SQL. L’instruction SQL peut inclure plusieurs sous-états indépendants, tels que UPDATE, DELETE et SELECT, qui seront exécutés dans l’ordre. Les résultats sont retournés à partir du sous-état final. Oui
parameters Liste des paramètres SQL, en des sous-éléments parameter, pour la requête. Non

attributs de paramètre

Attribut Description Obligatoire Default
name Chaîne. Nom du paramètre SQL. Oui N/A
sql-type Chaîne. Le type de données du paramètre SQL. Non N/A

response elements

Notes

Chaque élément enfant ne peut être spécifié qu’une fois. Indiquez les éléments dans l’ordre indiqué.

Nom Description Obligatoire
include-fragment Insère un fragment de stratégie dans la définition de la stratégie. Non
set-body Définit le corps dans la réponse du résolveur. Non
publish-event Publie un événement dans un ou plusieurs abonnements spécifiés dans le schéma de l’API GraphQL. Non

Usage

Notes d’utilisation

  • Pour configurer et gérer un résolveur avec cette stratégie, voir Configurer un résolveur GraphQL.
  • Cette stratégie est appelée uniquement lors de la résolution d’un champ unique dans un type d’opération correspondant dans le schéma.

Configurer l’intégration des identités managées avec Azure SQL

Vous pouvez configurer une identité managée affectée par le système de Gestion des API pour l’accès à Azure SQL au lieu de configurer l’authentification SQL avec un nom d’utilisateur et un mot de passe. Pour obtenir plus de contexte, consultez Configurer et gérer l’authentification Microsoft Entra avec Azure SQL.

Prérequis

  • Activez uneidentité managée affectée par le système dans votre instance Gestion des API.

Activer l’accès Microsoft Entra ID

Activez l’authentification Microsoft Entra pour SQL Database en attribuant un utilisateur Microsoft Entra comme administrateur du serveur.

  1. Dans le portail, accédez à votre serveur Azure SQL.
  2. Sélectionnez Microsoft Entra ID.
  3. Sélectionnez Définir l’administrateur, puis vous-même ou un groupe auquel vous appartenez.
  4. Sélectionnez Enregistrer.

Attribuer des rôles

  1. Dans le portail, accédez à votre ressource de base de données Azure SQL.

  2. Sélectionnez Éditeur de requête (préversion).

  3. Connectez-vous en utilisant l’authentification Active Directory.

  4. Exécutez le script T-SQL suivant. Remplacez la valeur <identity-name> par le nom de votre instance Gestion des 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

Exemples

Exemple de schéma

Les exemples de cette section sont des résolveurs pour le schéma GraphQL suivant :

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
}

Résolveur pour une requête GraphQL en utilisant une requête T-SQL à résultat unique

L’exemple suivant résout une requête GraphQL en effectuant une requête T-SQL à résultat unique sur une base de données Azure SQL back-end. La chaîne de connexion utilise l’authentification SQL avec un nom d’utilisateur et un mot de passe et est fournie en tirant parti d’une valeur nommée. La réponse est retournée sous forme d’objet JSON unique représentant une seule ligne.

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

Résolveur pour une requête GraphQL avec une réponse de requête multiligne transformée

L’exemple suivant résout une requête GraphQL en utilisant une requête SQL dans une base de données Azure SQL. La connexion à la base de données utilise l’identité managée affectée par le système de l’instance Gestion des API. L’identité doit être configurée pour accéder à la base de données Azure SQL.

Le paramètre de requête est accessible en tirant parti de la variable de contexte context.GraphQL.Arguments. La réponse de requête à plusieurs lignes est transformée en tirant parti de la stratégie set-body avec un modèle liquide.

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

Résolveur de la mutation GraphQL

L’exemple suivant résout une mutation GraphQL en utilisant une instruction T-SQL INSERT pour insérer une ligne d’une base de données Azure SQL. La connexion à la base de données utilise l’identité managée affectée par le système de l’instance Gestion des API. L’identité doit être configurée pour accéder à la base de données Azure SQL.

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

Contenu connexe

Pour plus d’informations sur l’utilisation des stratégies, consultez :