Fonte de dados do SQL do Azure para um resolvedor

  • Artigo

APLICA-SE A: Desenvolvedor | Básico | Básico v2 | Standard | Standard v2 | Premium

A política de resolvedor sql-data-source configura uma solicitação T-SQL (Transact-SQL) para um banco de dados SQL do Azure e uma resposta opcional para resolver dados para um tipo de objeto e campo em um esquema do GraphQL. O esquema deve ser importado para o Gerenciamento de API como uma API do GraphQL.

Observação

Essa política está em versão prévia. Atualmente, não há suporte para a política na camada de Consumo de Gerenciamento de API.

Observação

Defina os elementos da política e os elementos filho na ordem fornecida na declaração da política. Saiba mais sobre como definir e editar as políticas de Gerenciamento de API.

Declaração de política

<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

Nome Descrição Obrigatório
informações de conexão Especifica a conexão com o banco de dados SQL do Azure. Yes
include-fragment Insere um fragmento de política na definição de política. Se houver vários cabeçalhos, adicione include-fragment elementos adicionais. Não
solicitação Especifica a solicitação T-SQL do resolvedor e parâmetros opcionais. Sim
response Opcionalmente, especifica políticas filho para configurar a resposta do banco de dados SQL do Azure. Se não for especificada, a resposta será retornada de SQL do Azure como JSON. Não

elementos de connection-info

Observação

Exceto quando indicado, cada elemento filho pode ser especificado no máximo uma vez. Especifique elementos na ordem listada.

Elemento Descrição Obrigatório
connection-string Especifica a cadeia de conexão do SQL do Azure. A cadeia de conexão usa autenticação SQL (nome de usuário e senha) ou autenticação do Microsoft Entra se uma identidade gerenciada do Gerenciamento de API estiver configurada. Sim
include-fragment Insere um fragmento de política na definição de política. Se houver vários cabeçalhos, adicione include-fragment elementos adicionais. Não
authentication-certificate Realiza a autenticação usando um certificado do cliente na solicitação SQL do resolvedor. Não

atributos de connection-string

Atributo Descrição Obrigatório Padrão
use-managed-identity Booliano. Especifica se a identidade gerenciada atribuída pelo sistema da instância do Gerenciamento de API deve ser usada para conexão com o banco de dados SQL do Azure no lugar de um nome de usuário e senha na cadeia de conexão. Expressões de política são permitidas.

A identidade deve ser configurada para acessar o banco de dados SQL do Azure.		 Não false

atributo de solicitação

Atributo Descrição Obrigatório Padrão
single-result Booliano. Especifica se a resposta à consulta deve retorna no máximo uma linha. Expressões de política são permitidas. Não false

elementos de solicitação

Observação

Cada elemento filho pode ser especificado no máximo uma vez. Especifique elementos na ordem listada.

Elemento Descrição Obrigatório
include-fragment Insere um fragmento de política na definição de política. Não
set-body Define o corpo na solicitação SQL do resolvedor. Não
sql-statement Uma instrução T-SQL da solicitação para o banco de dados SQL do Azure. A instrução SQL pode incluir vária instruções Sub independentes, como UPDATE, DELETE e SELECT que serão executados em sequência. Os resultados são retornados da instrução Sub final. Sim
parameters Uma lista de parâmetros SQL, em parameter subelementos, para a solicitação. Não

atributos de parâmetro

Atributo Descrição Obrigatório Padrão
name Cadeia de caracteres. O nome do parâmetro SQL. Sim N/D
sql-type Cadeia de caracteres. O tipo de dados do parâmetro SQL. Não N/D

elementos de resposta

Observação

Cada elemento filho pode ser especificado no máximo uma vez. Especifique elementos na ordem listada.

Nome Descrição Obrigatório
include-fragment Insere um fragmento de política na definição de política. Não
set-body Define o corpo na resposta do resolvedor. Não
publish-event Publica um evento em uma ou mais assinaturas especificadas no esquema da API do GraphQL. Não

Uso

Observações de uso

  • Para configurar e gerenciar um resolvedor com essa política, confira Configurar um resolvedor do GraphQL.
  • Essa política é invocada somente ao resolver um único campo em um tipo de operação correspondente no esquema.

Configurar a integração de identidade gerenciada com o SQL do Azure

Você pode configurar uma identidade gerenciada atribuída pelo sistema do Gerenciamento de API para ter acesso ao SQL do Azure em vez de configurar a autenticação do SQL com nome de usuário e senha. Para obter informações em segundo plano, consulte Configurar e gerenciar a autenticação do Microsoft Entra com o SQLdo Azure.

Pré-requisitos

Habilitar o acesso à ID do Microsoft Entra

Habilite a autenticação do Microsoft Entra no Banco de Dados SQL atribuindo um usuário do Microsoft Entra como administrador do servidor.

  1. No portal, acesse o servidor SQL do Azure.
  2. Selecione ID do Microsoft Entra.
  3. Selecione Definir administrador e selecione você mesmo ou um grupo ao qual você pertence.
  4. Selecione Salvar.

Atribuir funções

  1. No portal, acesse o recurso de banco de dados SQL do Azure.

  2. Selecione Editor de consultas (versão prévia).

  3. Faça logon usando a autenticação do Active Directory.

  4. Execute o script SQL a seguir. Substitua <identity-name> pelo nome da sua instância do Gerenciamento de 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

Exemplos

Esquema de exemplo

Os exemplos nesta seção são resolvedores para o seguinte esquema 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
}

Resolvedor para consulta GraphQL usando solicitação T-SQL de resultado único

O exemplo a seguir resolve uma consulta GraphQL fazendo uma solicitação T-SQL de resultado único para um banco de dados SQL do Azure de back-end. A cadeia de conexão usa a autenticação do SQL com nome de usuário e senha e é fornecida usando um valor nomeado. A resposta é retornada como um único objeto JSON que representa uma única linha.

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

Resolvedor para consulta GraphQL com resposta de consulta de várias linhas transformada

O exemplo a seguir resolve uma consulta GraphQL usando uma consulta T-SQL para um banco de dados SQL do Azure. A conexão com o banco de dados usa a identidade gerenciada atribuída pelo sistema da instância do Gerenciamento de API. A identidade deve ser configurada para acessar o banco de dados SQL do Azure.

O parâmetro de consulta é acessado usando a variável de contexto context.GraphQL.Arguments. A resposta da consulta de várias linhas é transformada usando a política set-body com um modelo 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>

Resolvedor para a mutação do GraphQL

O exemplo a seguir resolve uma mutação do GraphQL usando uma instrução T-SQL INSERT para inserir uma linha em um banco de dados SQL do Azure. A conexão com o banco de dados usa a identidade gerenciada atribuída pelo sistema da instância do Gerenciamento de API. A identidade deve ser configurada para acessar o banco de dados SQL do 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>

Conteúdo relacionado

Para obter mais informações sobre como trabalhar com políticas, consulte: