Fonte de dados SQL do Azure para um resolvedor

  • Artigo

APLICA-SE A: Developer | Básico | Básico v2 | Padrão | Padrão v2 | Prémio

A sql-data-source política de resolvedor configura uma solicitação Transact-SQL (T-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 GraphQL. O esquema deve ser importado para o Gerenciamento de API como uma API GraphQL.

Nota

Esta política está em pré-visualização. Atualmente, a política não é suportada na camada Consumo do Gerenciamento de API.

Nota

Defina os elementos da política e os elementos filho na ordem fornecida na declaração de política. Saiba mais sobre como definir ou editar 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
connection-info Especifica a conexão com o banco de dados SQL do Azure. Sim
incluir-fragmento Insere um fragmento de política na definição de política. Se houver vários fragmentos, adicione elementos adicionais include-fragment . Não
solicitar Especifica a solicitação T-SQL do resolvedor e os parâmetros opcionais. Sim
resposta Opcionalmente, especifica políticas filho para configurar a resposta do banco de dados SQL do Azure. Se não for especificado, a resposta será retornada do SQL do Azure como JSON. Não

elementos connection-info

Nota

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

Elemento Description Obrigatório
connection-string Especifica a cadeia de conexão 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
incluir-fragmento Insere um fragmento de política na definição de política. Se houver vários fragmentos, adicione elementos adicionais include-fragment . Não
certificado-autenticação Autentica usando um certificado de cliente na solicitação SQL do resolvedor. Não

atributos de cadeia de conexão

Atributo Description Necessário Predefinição
identidade gerenciada por uso Booleano. Especifica se a identidade gerenciada atribuída pelo sistema da instância de 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. São permitidas expressões de política.

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

atributo request

Atributo Description Necessário Predefinição
resultado único Booleano. Especifica se a resposta à consulta deve retornar no máximo uma linha. São permitidas expressões de política. Não false

Solicitar elementos

Nota

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

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

atributos de parâmetro

Atributo Description Necessário Predefinição
nome String. O nome do parâmetro SQL. Sim N/A
tipo sql String. O tipo de dados do parâmetro SQL. No N/A

elementos de resposta

Nota

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

Nome Descrição Obrigatório
incluir-fragmento Insere um fragmento de política na definição de política. Não
corpo-conjunto Define o corpo na resposta do resolvedor. Não
publicar-evento Publica um evento para uma ou mais assinaturas especificadas no esquema da API GraphQL. Não

Utilização

Notas de utilização

  • Para configurar e gerenciar um resolvedor com essa política, consulte Configurar um resolvedor 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 de Gerenciamento de API para acesso ao SQL do Azure em vez de configurar a autenticação SQL com nome de usuário e senha. Para obter plano de fundo, consulte Configurar e gerenciar a autenticação do Microsoft Entra com o Azure SQL.

Pré-requisitos

Habilitar o acesso ao Microsoft Entra ID

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

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

Atribuir funções

  1. No portal, vá para o recurso do banco de dados SQL do Azure.

  2. Selecione Editor de consultas (pré-visualização).

  3. Faça login usando a autenticação do Ative Directory.

  4. Execute o seguinte script SQL. Substitua <identity-name> pelo nome da sua instância de 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 autenticação SQL com nome de usuário e senha e é fornecida usando um valor nomeado. A resposta é retornada como um único objeto JSON representando 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 ao sistema da instância de Gerenciamento de API. A identidade deve ser configurada para acessar o banco de dados SQL do Azure.

O parâmetro query é acessado usando a variável de context.GraphQL.Arguments contexto. A resposta de consulta de várias linhas é transformada usando a set-body política com um modelo líquido.

<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 mutação GraphQL

O exemplo a seguir resolve uma mutação 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 ao sistema da instância de 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údos relacionados

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