Origen de datos de Azure SQL para una resolución

  • Artículo

SE APLICA A: Desarrollador | Básico | Básico v2 | Estándar | Estándar v2 | Premium

La directiva de resolución sql-data-source configura una solicitud de Transact-SQL (T-SQL) a una base de datos de Azure SQL y una respuesta opcional para resolver los datos de un tipo de objeto y un campo en un esquema de GraphQL. El esquema debe importarse a API Management como una API de GraphQL.

Nota:

Esta directiva está en versión preliminar. Actualmente, la directiva no se admite en el nivel Consumo de API Management.

Nota

Establezca los elementos de la directiva y los elementos secundarios en el orden proporcionado en la instrucción de directiva. Obtenga más información sobre el establecimiento o modificación de directivas de API Management.

Instrucción de la directiva

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

Elementos

Nombre Descripción Obligatorio
información de conexión Especifica la conexión a una base de datos de Azure SQL. Sí
include-fragment Inserta un fragmento de la directiva en la definición de directiva. Si hay varios fragmentos, agregue elementos include-fragment adicionales. No
Solicitud Especifica la solicitud T-SQL de la resolución y los parámetros opcionales. Sí
response De manera opcional, especifica las directivas secundarias para configurar la respuesta de la base de datos de Azure SQL. Si no se especifica, la respuesta se devuelve de Azure SQL como JSON. No

elementos de connection-info

Nota

Excepto donde se indique, cada elemento secundario se puede especificar como máximo una vez. Especificar los elementos en el orden enumerado.

Elemento Descripción Obligatorio
connection-string Especifica la cadena de conexión de Azure SQL. La cadena de conexión usa la autenticación de SQL (nombre de usuario y contraseña) o la autenticación de Microsoft Entra ID si se configura una identidad administrada de API Management. Sí
include-fragment Inserta un fragmento de la directiva en la definición de directiva. Si hay varios fragmentos, agregue elementos include-fragment adicionales. No
authentication-certificate Se autentica mediante un certificado de cliente en la solicitud SQL de la resolución. No

atributos de connection-string

Atributo Descripción Necesario Valor predeterminado
use-managed-identity booleano. Especifica si se debe usar la identidad administrada asignada por el sistema de la instancia de API Management para la conexión a la base de datos de Azure SQL en lugar de un nombre de usuario y contraseña en la cadena de conexión. Se permiten expresiones de directiva.

La identidad debe configurarse para acceder a la base de datos de Azure SQL.		 No false

atributo de la solicitud

Atributo Descripción Necesario Valor predeterminado
single-result booleano. Especifica si se espera que la respuesta a la consulta devuelva una fila como máximo. Se permiten expresiones de directiva. No false

elementos de la solicitud

Nota

Cada elemento secundario se puede especificar como máximo una vez. Especificar los elementos en el orden enumerado.

Elemento Descripción Obligatorio
include-fragment Inserta un fragmento de la directiva en la definición de directiva. No
set-body Establece el cuerpo en la solicitud SQL de la resolución. No
sql-statement Instrucción T-SQL para la solicitud a la base de datos de Azure SQL. La instrucción SQL puede incluir varias subinstrucciones independientes, como UPDATE, DELETE y SELECT, que se ejecutarán en secuencia. Los resultados se devuelven de la subinstrucción final. Sí
parameters Lista de parámetros SQL, en subelementos parameter, para la solicitud. No

atributos de parámetro

Atributo Descripción Necesario Valor predeterminado
name Cadena Nombre del parámetro SQL. Sí N/D
sql-type String. Tipo de datos del parámetro SQL. No N/D

elementos de respuesta

Nota

Cada elemento secundario se puede especificar como máximo una vez. Especificar los elementos en el orden enumerado.

Nombre Descripción Obligatorio
include-fragment Inserta un fragmento de la directiva en la definición de directiva. No
set-body Establece el cuerpo en la respuesta de la resolución. No
publish-event Publica un evento en una o varias suscripciones especificadas en el esquema de GraphQL API. No

Uso

Notas de uso

  • Para configurar y administrar una resolución con esta directiva, consulte Configuración de una resolución de GraphQL.
  • Esta directiva solo se invoca al resolver un único campo en un tipo de operación coincidente en el esquema.

Configuración de la integración de identidad administrada con Azure SQL

Puede configurar una identidad administrada asignada por el sistema de API Management para acceder a Azure SQL en lugar de configurar la autenticación de SQL con el nombre de usuario y la contraseña. Para obtener más contexto, consulte Configuración y administración de la autenticación de Microsoft Entra con Azure SQL.

Requisitos previos

Habilitación del acceso de Microsoft Entra ID

Habilite la autenticación Microsoft Entra para SQL Database asignando un usuario de Microsoft Entra como administrador del servidor.

  1. En el portal, vaya al servidor de Azure SQL.
  2. Seleccione Microsoft Entra ID.
  3. Seleccione Establecer administrador y selecciónese a usted mismo o a un grupo al que pertenece.
  4. Seleccione Guardar.

Asignación de roles

  1. En el portal, vaya al recurso de la base de datos de Azure SQL.

  2. Seleccione Editor de consultas (versión preliminar).

  3. Inicie sesión mediante la autenticación de Azure Active Directory.

  4. Ejecute el siguiente script de SQL. Reemplace <identity-name> por el nombre de la instancia de 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

Ejemplos

Esquema de ejemplo

Los ejemplos de esta sección son solucionadores para el siguiente esquema de GraphQL:

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
}

Resolución de consultas de GraphQL mediante una solicitud T-SQL de resultado único

En el ejemplo siguiente se resuelve una consulta de GraphQL mediante la realización de una solicitud T-SQL de resultado único a una base de datos de Azure SQL de back-end. La cadena de conexión usa la autenticación de SQL con el nombre de usuario y la contraseña, y se proporciona mediante un valor con nombre. La respuesta se devuelve como un único objeto JSON que representa una sola fila.

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

Resolución de consultas de GraphQL con respuesta de consulta de varias filas transformadas

En el ejemplo siguiente se resuelve una consulta de GraphQL mediante una consulta T-SQL en una base de datos de Azure SQL. La conexión a la base de datos usa la identidad administrada asignada por el sistema de la instancia de API Management. La identidad debe configurarse para acceder a la base de datos de Azure SQL.

Se accede al parámetro de consulta mediante la variable de contexto context.GraphQL.Arguments. La respuesta de consulta de varias filas se transforma mediante la directiva set-body con una plantilla líquida.

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

Resolución para la mutación de GraphQL

En el ejemplo siguiente se resuelve una mutación de GraphQL mediante una instrucción INSERT de T-SQL para insertar una fila en una base de datos de Azure SQL. La conexión a la base de datos usa la identidad administrada asignada por el sistema de la instancia de API Management. La identidad debe configurarse para acceder a la base de datos de 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>

Contenido relacionado

Para más información sobre el trabajo con directivas, vea: