Funcionalidades específicas da base de dados para o Construtor de API de Dados

O construtor de API de Dados permite que cada base de dados tenha as suas próprias funcionalidades específicas. Este artigo detalha as funcionalidades suportadas para cada base de dados.

Suporte da versão da base de dados

Muitas bases de dados tradicionais requerem uma versão mínima para serem compatíveis com o Construtor de API de Dados (DAB).

Por outro lado, os serviços de base de dados cloud do Azure funcionam com o DAB fora da caixa sem necessidade de uma versão específica.

SQL do Azure e SQL Server

Existem 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 suportam a utilização da SESSION_CONTEXT função para aceder à identidade do utilizador atual. Esta funcionalidade é útil quando pretende aplicar o suporte nativo para segurança ao nível da linha (RLS) disponível no SQL do Azure e SQL Server.

Para SQL do Azure e SQL Server, o Construtor de API de Dados pode tirar partido do SESSION_CONTEXT para enviar metadados especificados pelo utilizador para a base de dados subjacente. Esses metadados estão disponíveis para o construtor de API de Dados em virtude das afirmações presentes no token de acesso. Os dados enviados para a base de dados podem ser utilizados para configurar um nível adicional de segurança (por exemplo, ao configurar 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 a base de dados durante a ligação da base de dados até que essa ligação seja fechada. Os mesmos dados também podem ser utilizados dentro de um procedimento armazenado.

Para obter mais informações sobre a definição SESSION_CONTEXT de dados, veja sp_set_session_context (Transact-SQL).

Configure SESSION_CONTEXT com a options propriedade da data-source secção no ficheiro de configuração. Para obter mais informações, veja data-source Referência de configuração.

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

Em alternativa, utilize o --set-session-context argumento com o dab init comando .

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

Todas as afirmações presentes no token EasyAuth/JWT são enviadas através da SESSION_CONTEXT para a base de dados subjacente. Todas as afirmações presentes no token são traduzidas em pares chave-valor transmitidos através SESSION_CONTEXT da consulta. Estas afirmações incluem, mas não se limitam a:

Para obter mais informações sobre afirmações, veja Microsoft Entra ID referência de afirmações de tokens de acesso.

Estas afirmações são traduzidas numa consulta SQL. Este exemplo truncado ilustra como sp_set_session_context é utilizado 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, pode implementar a segurança ao nível da linha (RLS) com os dados de sessão. Para obter mais informações, veja Implementar a segurança ao nível da linha com o contexto de sessão.

Azure Cosmos DB

Existem 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 para NoSQL é agnóstico ao esquema. Para utilizar o Construtor de API de Dados com a API para NoSQL, tem de criar um ficheiro de esquema GraphQL que inclua as definições de tipo de objeto que representam o modelo de dados do contentor. O construtor de API de Dados também espera que as definições e os campos do tipo de objeto GraphQL incluam a diretiva authorize de esquema do GraphQL quando pretender impor um acesso de leitura mais restritivo do que anonymous.

Por exemplo, este ficheiro de esquema representa um Book item dentro de um contentor. 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 ficheiro de configuração da DAB. Para obter mais informações, veja 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 apenas a utilizadores com as funções metadataviewer e authenticated. Para os requerentes autenticados, a função de sistema authenticated é atribuída automaticamente, eliminando a necessidade de um X-MS-API-ROLE cabeçalho.

Se o pedido autenticado precisar de ser executado no contexto de metadataviewer, deve ser acompanhado com um cabeçalho de pedido do tipo X-MS-API-ROLE definido como metadataviewer. No entanto, se o acesso anónimo for pretendido, tem de omitir a diretiva autorizada.

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

Como exemplo mais aprofundado, a @authorize diretiva pode ser aplicada na definição de tipo de nível superior. Esta aplicação restringe o acesso ao tipo e aos respetivos campos exclusivamente às funções especificadas na 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 contentores na API para NoSQL

As operações do GraphQL em contentores não são suportadas. O motor responde com uma mensagem de erro a indicar: Adding/updating Relationships is currently not supported in Azure Cosmos DB for NoSQL.

Pode contornar esta limitação ao atualizar o modelo de dados para armazenar entidades no mesmo contentor num formato incorporado. Para obter mais informações, veja Modelação de dados no Azure Cosmos DB para NoSQL.