Implementar o construtor de Data API no Serviço de Aplicações do Azure

Este guia mostra-lhe como implementar o Data API Builder (DAB) para o Serviço de Aplicações do Azure usando um modelo de implementação baseado em código, sem ter de construir ou gerir imagens de contentores. O App Service oferece suporte incorporado para TLS, domínios personalizados, escalabilidade, monitorização e autenticação Microsoft Entra.

Diagrama da arquitetura geral após a implementação no Serviço de Aplicações do Azure estar concluída.

Tip

Se o seu ambiente usar contentores, em vez disso, implemente nos Azure Container Apps ou no Azure Kubernetes Service.

Pré-requisitos

Criar o arquivo de configuração

Constrói um ficheiro de configuração DAB para ligar à tua base de dados existente.

  1. Crie um diretório vazio na sua máquina local para armazenar o ficheiro de configuração e os artefactos de implementação.

  2. Inicialize um novo arquivo de configuração base usando dab inito . Use a @env() função para referenciar a DATABASE_CONNECTION_STRING variável de ambiente para que as credenciais não fiquem armazenadas no ficheiro de configuração.

    dab init --database-type "<database-type>" --connection-string "@env('DATABASE_CONNECTION_STRING')"

    Importante

    Substitua <database-type> por um tipo de base de dados suportado, como mssql, postgresql, mysql, ou cosmosdb_nosql. Alguns tipos de bases de dados exigem definições de configuração adicionais na inicialização.

  3. Adicione pelo menos uma entidade de banco de dados à configuração. Use o dab add comando para configurar uma entidade. Repete dab add quantas vezes precisares para as tuas entidades.

    dab add "<entity-name>" --source "<schema>.<table>" --permissions "anonymous:*"

  4. Abra e revise o conteúdo do arquivo dab-config.json . Verifique que:

    • data-source.connection-string usa @env('DATABASE_CONNECTION_STRING')
    • As tuas entidades e permissões estão corretas

    Importante

    Não incorpore cadeias de ligação literais ou segredos em dab-config.json. Use a @env() função para que os valores sejam resolvidos a partir das variáveis de ambiente em tempo de execução.

Criar um manifesto local de ferramentas

Use um manifesto local de ferramenta .NET para que o pacote de implementação inclua o DAB como dependência do projeto. Esta abordagem evita depender de uma ferramenta instalada globalmente dentro do App Service.

  1. Crie um manifesto local de ferramenta .NET no diretório do seu projeto.

    dotnet new tool-manifest

  2. Instale o Data API Builder como uma ferramenta local.

    dotnet tool install microsoft.dataapibuilder --prerelease

  3. Verifique se o manifesto existe em .config/dotnet-tools.json.

    Observação

    O --prerelease flag instala a versão mais recente de pré-lançamento do Data API builder. Remova a flag e instale em vez disso a versão estável mais recente.

Testar localmente

Antes de implementares no Azure, confirma que o runtime começa e que os teus endpoints funcionam.

  1. Defina a cadeia de ligação como uma variável local de ambiente.

    $env:DATABASE_CONNECTION_STRING = "<your-connection-string>"

  2. Inicia o runtime do DAB localmente.

    dab start

  3. Teste o endpoint REST navegando até à interface Swagger ou fazendo um pedido para /api/<entity-name>.

  4. Teste o endpoint GraphQL em /graphql.

  5. Pare o tempo de execução depois de verificar todos os endpoints.

Recursos para criar o Serviço de Aplicação

Crie os recursos do Azure necessários para alojar o DAB no App Service.

  1. Criar um novo grupo de recursos. Utiliza este grupo de recursos para todos os novos recursos neste guia.

    az group create \
  --name <resource-group-name> \
  --location <location>

    Tip

    Considere nomear o grupo de recursos msdocs-dab-appservice.

  2. Crie um plano do Serviço de Aplicativo.

    az appservice plan create \
  --name <plan-name> \
  --resource-group <resource-group-name> \
  --sku B1 \
  --is-linux

    Observação

    Este guia utiliza o nível B1 (Basic) no Linux.

  3. Crie a aplicação web com o runtime .NET 8.

    az webapp create \
  --name <app-name> \
  --resource-group <resource-group-name> \
  --plan <plan-name> \
  --runtime "DOTNETCORE:8.0"

    Tip

    Valide os tempos de execução disponíveis para o seu plano com az webapp list-runtimes --os linux.

Configurar as definições do Serviço de Aplicação

Configure as variáveis de ambiente e o comando de arranque que o App Service precisa para executar o DAB.

  1. Configure o fornecedor de autenticação para o App Service. Esta configuração instrui o DAB a confiar na autenticação integrada do App Service (Easy Auth) para obter informações de identidade.

    dab configure --runtime.host.authentication.provider AppService

  2. Defina a cadeia de ligação da base de dados como uma definição da aplicação no App Service.

    az webapp config appsettings set \
  --name <app-name> \
  --resource-group <resource-group-name> \
  --settings DATABASE_CONNECTION_STRING="<your-connection-string>"

    Tip

    Usa uma cadeia de ligação que não inclua segredos. Em vez disso, utilize identidades geridas e autenticação Microsoft Entra para gerir o acesso entre a sua base de dados e o Serviço de Aplicações. Para obter mais informações, consulte Serviços do Azure que usam identidades gerenciadas.

  3. Crie um script de arranque que restaure o manifesto local da ferramenta e inicie o DAB. Crie um ficheiro nomeado startup.sh no diretório do seu projeto.

    #!/bin/sh
dotnet tool restore
dotnet tool run dab start

    Importante

    Assegure que startup.sh utiliza terminações de linha LF (Unix), e não CRLF. Os editores do Windows podem guardar com CRLF por defeito, o que faz com que o script falhe no host do Serviço de Aplicações Linux.

  4. Define o comando de arranque no App Service.

    az webapp config set \
  --name <app-name> \
  --resource-group <resource-group-name> \
  --startup-file "startup.sh"

Implantar no Serviço de Aplicações

Empacota os ficheiros do teu projeto e implementa-os no App Service usando o deploy ZIP.

  1. Crie um pacote de deployment que contenha os ficheiros do seu projeto. No mínimo, incluir:

    • dab-config.json
    • .config/dotnet-tools.json
    • startup.sh
    Compress-Archive -Path dab-config.json, .config, startup.sh -DestinationPath deploy.zip -Force

    Importante

    O ZIP deve conter ficheiros ao nível raiz. Não compactes a pasta pai que contém os ficheiros. A raiz do arquivo deve incluir dab-config.json, .config/, e startup.sh diretamente.

  2. Implemente o pacote ZIP para o App Service.

    az webapp deploy \
  --resource-group <resource-group-name> \
  --name <app-name> \
  --src-path deploy.zip \
  --type zip

Verificar a implantação

Após a implementação, confirme que o DAB inicia com sucesso no App Service.

  1. Abra o URL do Serviço de Aplicações.

    https://<app-name>.azurewebsites.net

  2. Verifica o endpoint de saúde.

    https://<app-name>.azurewebsites.net/health

  3. Teste os endpoints REST e GraphQL usando os mesmos caminhos das entidades que testou localmente. A aplicação implementada usa o mesmo dab-config.json, por isso o comportamento do endpoint deve corresponder ao seu runtime local.

  4. Se algum endpoint devolver um erro inesperado, ative o registo de aplicações e reveja os logs.

    az webapp log config \
  --name <app-name> \
  --resource-group <resource-group-name> \
  --application-logging filesystem \
  --level information

az webapp log tail \
  --name <app-name> \
  --resource-group <resource-group-name>

Configurar autenticação (opcional)

Proteja o seu endpoint de Serviço de Aplicações com o Microsoft Entra ID para uso em produção.

Para passos detalhados, consulte Configurar autenticação de Serviços de Aplicações.

Importante

O fornecedor de autenticação AppService em dab-config.json confia nos cabeçalhos injetados pela autenticação do Serviço de Aplicações. Certifique-se de que a autenticação de Serviços de Aplicações está ativada ao usar este fornecedor em produção. Para mais informações, consulte Autenticação Fácil (Serviço de Aplicação).

Observação

A autenticação por Serviço de Aplicações protege a entrada no seu endpoint. As permissões das entidades DAB continuam a governar quais operações o tempo de execução permite. Se quiser acesso baseado em funções, atualize as permissões da sua entidade para usar funções específicas em vez de anonymous:*.

Limpeza de recursos

Quando já não precisar da aplicação de exemplo ou dos respetivos recursos, remova a implementação correspondente e todos os recursos.

az group delete \
  --name <resource-group-name> \
  --yes \
  --no-wait

Conteúdo relacionado

  • Last updated on