Conectando-se a um banco de dados com aplicativos Web estáticos do Azure (versão prévia)

Importante

Aviso de desativação: conexões de banco de dados para aplicativos web estáticos serão desativadas em 30 de novembro de 2025. Migre agora para evitar interrupções.

O recurso de conexão de banco de dados dos Aplicativos Web Estáticos do Azure permite que você acesse um banco de dados do seu aplicativo Web estático sem escrever código personalizado do lado do servidor.

Depois de criar uma conexão entre seu aplicativo Web e o banco de dados, você poderá manipular dados com suporte total para operações CRUD, autorização interna e relações.

Com base no construtor de API de Dados, os Aplicativos Web Estáticos do Azure usam solicitações REST e GraphQL e as convertem em consultas de banco de dados.

Os recursos compatíveis com conexões de banco de dados incluem:

Característica	Description
Segurança integrada	Integração interna com o modelo de segurança de autenticação e autorização dos Aplicativos Web Estáticos do Azure. A mesma segurança baseada em função usada para proteger rotas está disponível para endpoints de API.
Operações completas baseadas em CRUD	Consulte os tutoriais do Azure Cosmos DB, sql do Azure, MySQL ou PostgreSQL para obter um exemplo sobre como manipular dados em seu aplicativo.
Dá suporte a SQL e NoSQL	Você pode usar bancos de dados relacionais e de documentos como o banco de dados do aplicativo.
Arquitetura sem servidor	As conexões são dimensionadas de 0 a 1 trabalhador (durante a visualização).
Relações de banco de dados	Com suporte apenas por meio do endpoint GraphQL.
Suporte à CLI	Desenvolva localmente com a CLI de Aplicativos Web Estáticos. Use a opção --data-api-location para lidar com solicitações para APIs de dados em desenvolvimento assim como elas são tratadas na nuvem.

Bancos de dados com suporte

A tabela a seguir mostra o suporte para diferentes bancos de dados relacionais e NoSQL.

Nome	Tipo	Description	REST	GraphQL
Azure Cosmos DB	Standard	Plataforma de banco de dados distribuída globalmente para bancos de dados noSQL e relacionais de qualquer escala. Além da configuração padrão, um gql arquivo de esquema é necessário para pontos de extremidade do GraphQL.		✔
SQL Azure	Standard	Família de produtos gerenciados, seguros e inteligentes que usam o mecanismo de banco de dados do SQL Server na nuvem do Azure.	✔	✔
Banco de Dados do Azure para MySQL	Flex	Serviço de banco de dados relacional na nuvem da Microsoft com base no MySQL Community Edition	✔	✔
Banco de Dados do Azure para PostgreSQL	Flex	Serviço de banco de dados PostgreSQL totalmente gerenciado que trata tarefas críticas com desempenho previsível e escalabilidade dinâmica.	✔	✔
Banco de Dados do Azure para PostgreSQL (único)	Solteiro	Banco de dados PostgreSQL totalmente gerenciado.	✔	✔

Você pode usar os seguintes tipos de conexão para acesso ao banco de dados:

• Cadeia de conexão
• Identidade gerenciada atribuída ao usuário
• Identidade Gerenciada atribuída pelo sistema

Local do ponto de extremidade

O acesso aos terminais de dados está disponível fora do caminho /data-api.

A tabela a seguir mostra como as solicitações são roteadas para diferentes partes de uma aplicação web estática.

Caminho	Description
example.com/api/*	Funções de API
example.com/data-api/*	Endpoints de conexão de banco de dados que oferecem suporte a solicitações REST e GraphQL.
example.com/*	Conteúdo estático

Ao configurar conexões de banco de dados em seu site, você pode configurar o sufixo REST ou GraphQL da rota /data-api/*. O /data-api prefixo é uma convenção de Aplicativos Web Estáticos e não pode ser alterado.

Configuração

Há duas etapas para configurar uma conexão de banco de dados em Aplicativos Web Estáticos. Você precisa conectar seu banco de dados ao seu aplicativo Web estático no portal do Azure e atualizar o arquivo de configuração de conexões de banco de dados.

Consulte a configuração de conexão de banco de dados nos Aplicativos Web Estáticos do Azure para obter mais detalhes.

Desenvolvimento local

A CLI de SWA (Aplicativos Web Estáticos do Azure) inclui suporte para trabalhar com conexões de banco de dados durante o desenvolvimento local.

A CLI ativa o endpoint local /data-api e redireciona as solicitações da porta 4280 para a porta apropriada para acesso ao banco de dados.

Este é um comando de exemplo que inicia a CLI da SWA com uma conexão de banco de dados:

swa start ./src --data-api-location swa-db-connections

Esse comando inicia a CLI da SWA no diretório src . A --data-api-location opção informa à CLI que uma pasta chamada swa-db-connections contém o arquivo staticwebapp.database.config.json .

Observação

No desenvolvimento, se você usar uma cadeia de conexão para autenticar, use a função env() para ler uma cadeia de conexão de uma variável de ambiente. A cadeia de caracteres passada para a env função deve estar cercada por aspas.

Segurança baseada em função

Ao definir uma entidade no arquivo staticwebapp.database.config.json , você pode especificar uma lista de funções necessárias para acessar um ponto de extremidade de entidade.

O fragmento de configuração a seguir requer a função de administrador para acessar todas as ações (create, read, , updatedelete) na entidade orders.

{
...
"entities": { 
  "Orders": { 
    "source": "dbo.Orders", 
    "permissions": [ 
      { 
        "actions": ["*"], 
        "role": "admin" 
      }
    ]
 }
}
...
}

Quando você faz chamadas para um ponto de extremidade que requer uma função, as seguintes condições são necessárias:

1. O usuário atual deve ser autenticado.

2. O usuário atual deve ser um membro da função necessária.

3. A solicitação REST ou GraphQL deve incluir um cabeçalho com a chave X-MS-API-ROLE e um valor do nome da função que corresponde ao que está listado nas regras de configuração de entidade.

   Por exemplo, o snippet a seguir mostra como passar a função de administrador em um cabeçalho de solicitação.

   {
     method: "POST",
     headers: { 
       "Content-Type": "application/json",
       "X-MS-API-ROLE": "admin"
     },
     body: JSON.stringify(requestPayload)
   }
   

Constraints

• Os bancos de dados devem ser acessíveis pela infraestrutura do Azure.
• Durante a versão prévia pública, as conexões de banco de dados são dimensionadas de 0 a 1 trabalhador de banco de dados.

Próximas etapas

Configurar seu banco de dados