Recursos específicos do banco de dados para o construtor de API de Dados

Artigo
04/13/2024

O Construtor de API de Dados permite que cada banco de dados tenha seus próprios recursos específicos. Este artigo detalha os recursos com suporte para cada banco de dados.

Suporte à versão do banco de dados

Muitos bancos de dados tradicionais exigem que uma versão mínima seja compatível com o DAB (Construtor de API de Dados).

	Versão Mínima com Suporte
SQL Server	2016
MySQL	8
PostgreSQL	11

Por outro lado, os serviços de banco de dados de nuvem do Azure funcionam com o DAB pronto para uso sem a necessidade de uma versão específica.

	Versão Mínima com Suporte
SQL do Azure	n/d
Azure Cosmos DB para NoSQL	n/d
Azure Cosmos DB para PostgreSQL	n/d

SQL do Azure e SQL Server

Há algumas propriedades específicas que são exclusivas do SQL, incluindo SQL do Azure e SQL Server.

SESSION_CONTEXT

SQL do Azure e SQL Server dão suporte ao uso da SESSION_CONTEXT função para acessar a identidade do usuário atual. Esse recurso é útil quando você deseja aplicar o suporte nativo à RLS (segurança em nível de linha) disponível em SQL do Azure e SQL Server.

Para SQL do Azure e SQL Server, o Construtor de API de SESSION_CONTEXT Dados pode aproveitar para enviar metadados especificados pelo usuário para o banco de dados subjacente. Esses metadados estão disponíveis para o Construtor de API de Dados em virtude das declarações presentes no token de acesso. Os dados enviados para o banco de dados podem ser usados para configurar um nível extra de segurança (por exemplo, configurando políticas de segurança) para impedir ainda mais o acesso a dados em operações como SELECT, UPDATE, DELETE. Os SESSION_CONTEXT dados estão disponíveis para o banco de dados durante a conexão de banco de dados até que essa conexão seja fechada. Os mesmos dados também podem ser usados dentro de um procedimento armazenado.

Para obter mais informações sobre como definir SESSION_CONTEXT dados, consulte sp_set_session_context (Transact-SQL).

Configure SESSION_CONTEXT usando a options propriedade da data-source seção no arquivo de configuração. Para obter mais informações, consulte data-source referência de configuração.

{
  ...
  "data-source": {
    "database-type": "mssql",
    "options": {
      "set-session-context": true
    },
    "connection-string": "<connection-string>"
  },
  ...
}

Como alternativa, use o --set-session-context argumento com o dab init comando .

dab init --database-type mssql --set-session-context true

Todas as declarações presentes no token EasyAuth/JWT são enviadas por meio do SESSION_CONTEXT para o banco de dados subjacente. Todas as declarações presentes no token são convertidas em pares chave-valor passados por meio SESSION_CONTEXT de consulta. Essas declarações incluem, mas não se limitam a:

	Descrição
`aud`	Público
`iss`	Emissor
`iat`	Emitido em
`exp`	Hora de expiração
`azp`	Identificador de aplicativo
`azpacr`	Método de autenticação do cliente
`name`	Assunto
`uti`	Identificador de token exclusivo

Para obter mais informações sobre declarações, consulte Microsoft Entra ID referência de declarações de token de acesso.

Essas declarações são convertidas em uma consulta SQL. Este exemplo truncado ilustra como sp_set_session_context é usado neste contexto:

EXEC sp_set_session_context 'aud', '<AudienceID>', @read_only = 1;
EXEC sp_set_session_context 'iss', 'https://login.microsoftonline.com/<TenantID>/v2.0', @read_only = 1;
EXEC sp_set_session_context 'iat', '1637043209', @read_only = 1;
...
EXEC sp_set_session_context 'azp', 'a903e2e6-fd13-4502-8cae-9e09f86b7a6c', @read_only = 1;
EXEC sp_set_session_context 'azpacr', 1, @read_only = 1;
..
EXEC sp_set_session_context 'uti', '_sSP3AwBY0SucuqqJyjEAA', @read_only = 1;
EXEC sp_set_session_context 'ver', '2.0', @read_only = 1;

Em seguida, você pode implementar a RLS (segurança em nível de linha) usando os dados da sessão. Para obter mais informações, confira Implementar a segurança em nível de linha com o contexto de sessão.

Azure Cosmos DB

Há algumas propriedades específicas que são exclusivas de várias APIs no Azure Cosmos DB.

Esquema na API para NoSQL

O Azure Cosmos DB for NoSQL é independente de esquema. Para usar o Construtor de API de Dados com a API para NoSQL, você deve criar um arquivo de esquema GraphQL que inclua as definições de tipo de objeto que representam o modelo de dados do contêiner. O construtor de API de Dados também espera que suas definições e campos de tipo de objeto GraphQL incluam a diretiva authorize de esquema GraphQL quando você deseja impor acesso de leitura mais restritivo do que anonymous.

Por exemplo, esse arquivo de esquema representa um Book item dentro de um contêiner. Este item contém, no mínimo, title as propriedades e Authors .

type Book @model(name:"Book"){
  id: ID
  title: String @authorize(roles:["metadataviewer","authenticated"])
  Authors: [Author]
}

Este esquema de exemplo corresponde à configuração de entidade a seguir no arquivo de configuração do DAB. Para obter mais informações, consulte entities referência de configuração.

{
  ...
  "Book": {
    "source": "Book",
    "permissions": [
      {
        "role": "anonymous",
        "actions": [ "read" ]
      },
      {
        "role": "metadataviewer",
        "actions": [ "read" ]
      }
    ]
  }
  ...
}

A @authorize diretiva com roles:["metadataviewer","authenticated"] restringe o title acesso ao campo somente aos usuários com as funções metadataviewer e authenticated. Para solicitantes autenticados, a função authenticated do sistema é atribuída automaticamente, eliminando a necessidade de um X-MS-API-ROLE cabeçalho.

Se a solicitação autenticada precisar ser executada no contexto de metadataviewer, ela deverá ser acompanhada com um cabeçalho de solicitação do tipo X-MS-API-ROLE definido metadataviewercomo . No entanto, se o acesso anônimo for desejado, você deverá omitir a diretiva autorizada.

A @model diretiva é utilizada para estabelecer uma correlação entre esse tipo de objeto GraphQL e o nome da entidade correspondente na configuração de runtime. A diretiva é formatada como:@model(name:"<Entity_Name>")

Como um exemplo mais profundo, a @authorize diretiva pode ser aplicada na definição de tipo de nível superior. Esse aplicativo restringe o acesso ao tipo e seus campos exclusivamente às funções especificadas dentro da diretiva .

type Series @model(name:"Series") @authorize(roles:["editor","authenticated"]) {
  id: ID
  title: String
  Books: [Book]
}

{
  "Book": {
    "source": "Series",
    "permissions": [
      {
        "role": "authenticated",
        "actions": [ "read" ]
      },
      {
        "role": "editor",
        "actions": [ "*" ]
      }
    ]
  }
}

Consultas entre contêineres na API para NoSQL

não há suporte para operações de GraphQL em contêineres. O mecanismo responde com uma mensagem de erro informando: Adding/updating Relationships is currently not supported in Azure Cosmos DB for NoSQL.

Você pode contornar essa limitação atualizando seu modelo de dados para armazenar entidades dentro do mesmo contêiner em um formato inserido. Para obter mais informações, consulte Modelagem de dados no Azure Cosmos DB for NoSQL.

Compartilhar via