Compartilhar via

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

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 uma versão mínima para serem compatíveis com o DAB (Construtor de API de Dados).

Versão Mínima Suportada
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 Suportada
Azure SQL n/a
Azure Cosmos DB para NoSQL n/a
Azure Cosmos DB para PostgreSQL n/a

SQL do Azure e SQL Server

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

SESSION_CONTEXT

O SQL do Azure e o 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 para RLS (segurança em nível de linha) disponível no SQL do Azure e no SQL Server.

Para o SQL do Azure e o SQL Server, o Construtor de API de Dados pode aproveitar SESSION_CONTEXT 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 dados SESSION_CONTEXT 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 a 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 banco de dados subjacente. Todas as declarações presentes no token são traduzidas em pares chave-valor passados por meio de SESSION_CONTEXT consulta. Essas declarações incluem, mas não se limitam a:

Description
aud Audience
iss Issuer
iat Issued at
exp Expiration time
azp Application identifier
azpacr Método de autenticação do cliente
name Subject
uti Identificador de token exclusivo

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

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, consulte implementar a segurança em nível de linha com contexto de sessão.

Azure Cosmos DB

Há algumas propriedades específicas que são exclusivas para 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 e Authors propriedades.

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

Este esquema de exemplo corresponde à seguinte configuração de entidade no arquivo de configuração do DAB. Para obter mais informações, consulte entities a 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 como metadataviewer. 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 do 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 a modelagem de dados no Azure Cosmos DB para NoSQL.

  • Last updated on