Quickstart: Crie uma aplicação Durable Functions que utilize o fornecedor de armazenamento MSSQL

Use Durable Functions, uma funcionalidade do Funções do Azure, para escrever funções com estado num ambiente serverless. Durable Functions gere o estado, os pontos de verificação e os reinícios na sua aplicação.

Durable Functions suporta vários fornecedores de armazenamento , também conhecidos como backends, para armazenar orquestração e estado de execução da entidade. Neste guia de início rápido, cria uma aplicação Durable Functions que utiliza o fornecedor de armazenamento do Microsoft SQL Server (MSSQL) com o Visual Studio Code.

Este quickstart cria uma aplicação .NET (modelo isolado) para fins de demonstração. Os conceitos aplicam-se a outras línguas de forma semelhante.

Pré-requisitos

Para concluir este arranque rápido, necessita de:

• Visual Studio Code instalado.

• Extensão do Funções do Azure para Visual Studio Code instalada.

• A versão mais recente do Funções do Azure Core Tools instalada.

• .NET 8.0 SDK instalado.

• Docker instalado.

• Uma assinatura do Azure.

• Uma ferramenta de teste HTTP que mantém seus dados seguros. Para obter mais informações, consulte Ferramentas de teste HTTP.

Criar um projeto Funções do Azure

No Visual Studio Code, cria um projeto local do Funções do Azure.

1. No menu Exibir, selecione Paleta de comandos (ou selecione Ctrl+Shift+P).

2. No prompt (>), entre e depois selecione Funções do Azure: Criar Novo Projeto.

   

3. Selecione Procurar. Na caixa de diálogo Selecionar pasta, vá para uma pasta a ser usada para seu projeto e escolha Selecionar.

4. Nos prompts, selecione ou insira os seguintes valores:

   Prompt	Action	Descrição
   Selecione um idioma para seu projeto de aplicativo de função	Selecione .NET	Cria um projeto local do C# Functions
   Selecione um runtime .NET	Selecione .NET 8.0 isolado.	Cria um projeto de Functions que suporta o .NET 8 a ser executado num processo de trabalho isolado e no Funções do Azure Runtime 4.0.
   Selecione um modelo para a primeira função do seu projeto	Selecione Orquestração de Funções Duráveis.	Cria uma orquestração Durable Functions.
   Escolha um tipo de armazenamento durável	Selecione MSSQL.	Seleciona o provedor de armazenamento MSSQL.
   Fornecer um nome de função	Digite HelloOrchestration.	Um nome para a função de orquestração.
   Fornecer um namespace	Digite Company.Function.	Um namespace para a classe gerada.
   Selecione como gostaria de abrir o seu projeto	Selecione Abrir na janela atual.	Abre o Visual Studio Code na pasta que selecionaste.

O Visual Studio Code instala o Funções do Azure Core Tools se for necessário para criar o projeto. Ele também cria um projeto de aplicativo de função em uma pasta. Este projeto contém os arquivos de configuração host.json e local.settings.json .

Outro ficheiro, HelloOrchestration.cs, contém os blocos básicos de construção de uma aplicação Durable Functions:

Para obter mais informações sobre estas funções, consulte tipos e funcionalidades do Durable Functions.

Configurar a sua base de dados

Este início rápido utiliza uma imagem Docker SQL Server. Para alternativas (SQL Server Express, Base de Dados SQL do Azure ou uma instância local), consulte a visão geral fornecedores de armazenamento.

Configura a tua instância local de SQL Server baseada no Docker

Use os seguintes comandos do PowerShell para configurar um banco de dados SQL Server local no Docker. Podes instalar o PowerShell no Windows, macOS ou Linux.

# primary parameters
$pw        = "yourStrong(!)Password"
$edition   = "Developer"
$port      = 1433
$tag       = "2019-latest"
$dbname    = "DurableDB"
$collation = "Latin1_General_100_BIN2_UTF8"

# pull the image from the Microsoft container registry
docker pull mcr.microsoft.com/mssql/server:$tag

# run the image and provide some basic setup parameters
docker run --name mssql-server -e 'ACCEPT_EULA=Y' -e "MSSQL_SA_PASSWORD=$pw" -e "MSSQL_PID=$edition" -p ${port}:1433 -d mcr.microsoft.com/mssql/server:$tag

# wait a few seconds for the container to start...

# create the database with strict binary collation
docker exec -it mssql-server /opt/mssql-tools/bin/sqlcmd -S . -U sa -P "$pw" -Q "CREATE DATABASE [$dbname] COLLATE $collation"

# if sqlcmd is in the mssql-tools18 folder
# docker exec -it mssql-server /opt/mssql-tools18/bin/sqlcmd -C -S . -U sa -P "$pw" -Q "CREATE DATABASE [$dbname] COLLATE $collation"

Agora você deve ter um SQL Server local em execução no Docker e escutando na porta 1433. Se a porta 1433 entrar em conflito com outro serviço, execute novamente esses comandos depois de alterar a variável $port para um valor diferente.

Para validar a instalação do banco de dados, consulte o novo banco de dados SQL:

docker exec -it mssql-server /opt/mssql-tools/bin/sqlcmd -S . -U sa -P "$pw" -Q "SELECT name FROM sys.databases"

Se a configuração do banco de dados for concluída com êxito, o nome do seu banco de dados (por exemplo, DurableDB) aparecerá na saída da linha de comando:

name

--------------------------------------------------------------
master

tempdb

model

msdb

DurableDB

Troubleshooting

Se você se deparar com "Error response from daemon: OCI runtime exec failed" ao executar docker exec para criar o banco de dados, é provável que a pasta /opt/mssql-tools/bin/sqlcmd não exista. Abre o Docker Desktop, seleciona o teu contentor SQL Server Docker, seleciona Ficheiros e procura a pasta mssql-tools. Verifique se esta pasta tem um nome diferente, como /opt/mssql-tools18/bin/sqlcmd. Atualize o comando em conformidade.

No ODBC Driver 18 para SQL Server, a opção Criptografar conexão é definida como true por padrão. Se te deparares com "error:1416F086:SSL routines:tls_process_server_certificate:certificate verify failed:self signed certificate" ao executares docker exec para realizar operações de base de dados, adiciona -C, que é equivalente à opção TRUSTSERVERCERTIFICATE = true ADO.net.

Adicionar uma cadeia de conexão SQL ao local.settings.json

O backend MSSQL precisa de uma cadeia de ligação para aceder à tua base de dados. Como obter uma cadeia de ligação depende principalmente do seu fornecedor específico de servidores MSSQL.

Se usar os comandos Docker anteriores sem alterar quaisquer parâmetros, a sua cadeia de ligação é:

Server=localhost,1433;Database=DurableDB;User Id=sa;Password=yourStrong(!)Password;

Em local.settings.json, atribui a cadeia de ligação da instância do servidor SQL baseada em Docker a SQLDB_Connection. Essa variável foi adicionada pelo Visual Studio Code quando você escolheu MSSQL como back-end para seu aplicativo Durable Functions:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true", 
    "SQLDB_Connection": "Server=localhost,1433;Database=DurableDB;User Id=sa;Password=yourStrong(!)Password;",
    "FUNCTIONS_WORKER_RUNTIME": "<dependent on your programming language>"
  }
}

Testar localmente

Abra uma janela de terminal na pasta raiz do aplicativo e execute azurite start. O Azurite é o emulador do Armazenamento do Azure, necessário para executar qualquer aplicação Function.

Abra outra janela de terminal na pasta raiz do seu aplicativo e inicie o aplicativo Função executando func host start.

1. Na janela do terminal, copie o endereço de URL da função acionada por HTTP.

   

2. Utilize uma ferramenta de teste HTTP para enviar uma solicitação HTTP POST para o endpoint URL.

   A resposta é o resultado inicial da função HTTP. Informa que a orquestração das Durable Functions foi iniciada com sucesso. Ainda não exibe o resultado final da orquestração. A resposta inclui alguns URLs úteis.

3. Copie o valor do URL para statusQueryGetUri, cole-o na barra de endereço do navegador e execute a solicitação. Como alternativa, você também pode continuar a usar a ferramenta de teste HTTP para emitir a solicitação GET.

   A solicitação consulta o estado da instância de orquestração. Deves ver que a instância terminou e que inclui as saídas ou resultados da aplicação Durable Functions, tal como neste exemplo:

   {
       "name":"HelloCities",
       "instanceId":"7f99f9474a6641438e5c7169b7ecb3f2",
       "runtimeStatus":"Completed",
       "input":null,
       "customStatus":null,
       "output":"Hello, Tokyo! Hello, London! Hello, Seattle!",
       "createdTime":"2023-01-31T18:48:49Z",
       "lastUpdatedTime":"2023-01-31T18:48:56Z"
   }
   

Execute a sua aplicação no Azure (opcional)

As secções anteriores completaram o guia de início rápido local. As secções seguintes explicam como implementar no Azure, o que requer recursos e configuração adicionais.

Para executar seu aplicativo no Azure, você precisa criar vários recursos. Para facilitar a limpeza mais tarde, cria todos os recursos no mesmo grupo de recursos.

Criar uma Base de Dados SQL do Azure

No portal Azure, pode criar uma base de dados SQL do Azure. Durante a criação:

• Permita que os serviços e recursos do Azure acedam a este servidor (em Networking)
• Defina o valor para Agrupamento de banco de dados (em Configurações adicionais) como Latin1_General_100_BIN2_UTF8.

Crie uma aplicação Funções do Azure e recursos de suporte

1. Abra uma janela de terminal e entre no Azure:

   az login
   

2. Crie os seguintes recursos no mesmo grupo de recursos e região que o banco de dados SQL:

   • Uma conta de armazenamento de uso geral, que é usada para armazenar dados importantes do aplicativo, como o próprio código do aplicativo. Os nomes das contas de armazenamento devem conter de três a 24 caracteres, números e letras minúsculas apenas.
   • Plano premium de aplicação funcional
   • Um aplicativo de função

   # Variables
   location=<REGION>
   resourceGroup=<RESOURCE_GROUP_NAME>
   storage=<STORAGE_NAME>
   planName=<PREMIUM_PLAN_NAME>
   functionApp=<APP_NAME>
   skuStorage="Standard_LRS"
   skuPlan="EP1"
   functionsVersion="4"
   
   # Create an Azure storage account
   echo "Creating $storage"
   az storage account create --name $storage --location "$location" --resource-group $resourceGroup --sku $skuStorage --allow-blob-public-access false
   
   # Create a premium plan
   echo "Creating $premiumPlan"
   az functionapp plan create --name $planName --resource-group $resourceGroup --location "$location" --sku $skuPlan
   
   # Create a function app hosted in the premium plan
   echo "Creating $functionApp"
   az functionapp create --name $functionApp --storage-account $storage --plan $planName --resource-group $resourceGroup --functions-version $functionsVersion
   

Criar uma identidade gerenciada do Azure

As identidades gerenciadas tornam seu aplicativo mais seguro, eliminando segredos de seu aplicativo, como credenciais nas cadeias de conexão. Você pode escolher entre identidade gerenciada atribuída pelo sistema e atribuída pelo usuário. Este início rápido demonstra a configuração da identidade gerenciada atribuída pelo usuário, que é a opção recomendada, pois não está vinculada ao ciclo de vida do aplicativo.

Os comandos a seguir criam o recurso de identidade e o atribuem ao aplicativo:

# Variables
subscription=<SUBSCRIPTION_ID>
identity=<IDENTITY_NAME>

# Create a managed identity resource
echo "Creating $identity"
az identity create -g $resourceGroup -n $identity --location "$location"

# Construct the identity resource ID 
resourceId="/subscriptions/$subscription/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$identity"

# Assign the identity to the Azure Functions app
echo "Assigning $identity to app"
az functionapp identity assign -g $resourceGroup -n $functionApp --identities "$resourceId"

# Get the identity's ClientId and PrincipalId (also called ObjectId) for a later step. 
clientId=$(az identity show --name $identity --resource-group $resourceGroup --query 'clientId' --output tsv)

principalId=$(az identity show --name $identity --resource-group $resourceGroup --query 'principalId' --output tsv)

Conceder acesso ao Armazenamento do Azure e ao Base de Dados SQL do Azure

Armazenamento do Azure

Atribua a função Proprietário de Dados de Blob de Armazenamento para acessar a conta de armazenamento.

# Set the scope of the access
scope="/subscriptions/$subscription/resourceGroups/$resourceGroup/providers/Microsoft.Storage/storageAccounts/$storage"

# Assign the role
echo "Assign Storage Blob Data Owner role to identity"
az role assignment create --assignee "$clientId" --role "Storage Blob Data Owner" --scope "$scope"

Base de Dados SQL do Azure

A identidade gerida necessita de duas concessões: db_owner na base de dados da sua aplicação (para criar e gerir esquemas do hub de tarefas) e dbmanager na master base de dados (para permitir operações ao nível da base de dados durante o arranque).

1. Comece definindo sua identidade de desenvolvedor como administrador do banco de dados.

   O cessionário é a sua identidade, por isso mude para o seu e-mail:

   assignee=$(az ad user show --id "someone@example.com" --query "id" --output tsv)
   

   Configure o responsável como administrador da base de dados do SQL do Azure.

   az sql server ad-admin create --resource-group $resourceGroup --server-name <SQL_SERVER_NAME> --display-name ADMIN --object-id "$assignee"
   

2. Liga-te à base de dados SQL criada anteriormente usando ferramentas como SQL Management Server Studio ou Visual Studio Code. Ou você pode executar o seguinte comando SQLCMD para se conectar:

   sqlcmd -S <SQL_SERVER_NAME>.database.windows.net -d <DATABASE_NAME> -U <someone@example.com> -P "ACCOUNT_PASSWORD" -G -l 30
   

   Conceda acesso à sua identidade db_owner executando a seguinte consulta no banco de dados. O IDENTITY_OBJECT_ID é o PrincipalId da etapa de criação de identidade.

   CREATE USER "<IDENTITY_NAME>" FROM EXTERNAL PROVIDER With OBJECT_ID='<IDENTITY_OBJECT_ID>'
   ALTER ROLE db_owner ADD MEMBER "<IDENTITY_NAME>";
   GO
   

3. Conecte-se ao master banco de dados e conceda à sua identidade dbmanager acesso:

   CREATE USER "<IDENTITY_NAME>" FROM EXTERNAL PROVIDER With OBJECT_ID='<IDENTITY_OBJECT_ID>'
   ALTER ROLE dbmanager ADD MEMBER "<IDENTITY_NAME>";
   GO
   

Definir as configurações necessárias do aplicativo

Você precisa adicionar as seguintes configurações do aplicativo ao seu aplicativo:

• AzureWebJobsStorage__accountName: nome da conta do Armazenamento do Azure
• AzureWebJobsStorage__clientId: ClientId da identidade gerenciada
• AzureWebJobsStorage__credential: Tipo de credencial, que é managedidentity
• SQLDB_Connection: Cadeia de conexão do banco de dados SQL

Se estiver a usar uma identidade gerida atribuída pelo utilizador para autenticar na base de dados SQL, a cadeia de ligação deve ser a seguinte:

dbserver=<SQL_SERVER_NAME>
sqlDB=<SQL_DB_NAME>
clientId=<IDENTITY_CLIENT_ID>

sqlconnstr="Server=tcp:$dbserver.database.windows.net,1433;Initial Catalog=$sqlDB;Persist Security Info=False;User ID=$clientId;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Authentication='Active Directory Managed Identity';"

Para aplicações Flex Consumption, usa uma cadeia de ligação para autenticar por agora. Você pode encontrá-lo acessando o recurso do banco de dados SQL no portal do Azure, navegando até a guia Configurações e clicando em Cadeias de conexão:

A cadeia de ligação deve ter este formato:

dbserver=<SQL_SERVER_NAME>
sqlDB=<SQL_DB_NAME>
username=<DB_USER_LOGIN>
password=<DB_USER_PASSWORD>

sqlconnstr="Server=tcp:$dbserver.database.windows.net,1433;Initial Catalog=$sqlDB;Persist Security Info=False;User ID=$username;Password=$password;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"

Execute o seguinte comando para definir as configurações:

az functionapp config appsettings set --name $functionApp --resource-group $resourceGroup --settings AzureWebJobsStorage__accountName="$storage" AzureWebJobsStorage__clientId="$clientId" AzureWebJobsStorage__credential="managedidentity" SQLDB_Connection=$sqlconnstr

Exclua a configuração existente AzureWebJobsStorage :

az functionapp config appsettings delete --name $functionApp --resource-group $resourceGroup --setting-names "AzureWebJobsStorage"

Implementar o projeto local no Azure e testar

Por fim, na pasta do projeto raiz, implemente a sua aplicação no Azure executando:

func azure functionapp publish $functionApp

Após a conclusão da implantação, execute o seguinte para obter a URL de gatilho HTTP:

az functionapp function list --resource-group $resourceGroup --name $functionApp  --query '[].{Function:name, URL:invokeUrlTemplate}' --output json

Teste exatamente como fez durante o desenvolvimento local com uma ferramenta de teste HTTP.

Você também pode validar se o back-end MSSQL está configurado corretamente consultando o banco de dados para obter dados do hub de tarefas.

Por exemplo, você pode consultar suas instâncias de orquestração no painel de visão geral do banco de dados SQL. Selecione Editor do Power Query, autentique e execute a seguinte consulta:

SELECT TOP 5 InstanceID, RuntimeStatus, CreatedTime, CompletedTime FROM dt.Instances

Depois de executar um orquestrador simples, você verá pelo menos um resultado, conforme mostrado neste exemplo:

Passos seguintes

• Aloja uma aplicação Durable Functions usando o backend MSSQL em Azure Container Apps
• Arquitetura e configuração do fornecedor de armazenamento MSSQL
• Padrões e conceitos de funções duráveis
• Diagnóstico e monitorização
• Sobre o fornecedor de armazenamento Durable Task Scheduler