Comece Rápido: Criar um aplicativo de Durable Functions que utiliza o provedor de armazenamento MSSQL

Use a extensão Durable Functions, um recurso do Azure Functions, para gravar funções com estado em um ambiente sem servidor. A Durable Functions gerencia o estado, os pontos de verificação e as reinicializações no seu aplicativo.

O Durable Functions dá suporte a vários provedores de armazenamento, também conhecidos como back-ends, para armazenar o estado de execução da orquestração e da entidade. Neste guia de início rápido, você criará um aplicativo Durable Functions para usar o provedor de armazenamento do Microsoft SQL Server (MSSQL) com o Visual Studio Code.

Este início rápido cria um aplicativo .NET (modelo isolado) para fins de demonstração. O conteúdo fornecido neste artigo se aplica a outros idiomas de maneiras semelhantes.

Pré-requisitos

Para concluir este guia de início rápido, você precisa:

• O Visual Studio Code instalado.

• Extensão do Visual Studio Code do Azure Functions instalada.

• A última versão do Azure Functions Core Tools instalada.

• SDK do .NET 8.0 instalado.

• Docker instalado.

• Uma assinatura do Azure.

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

Criar um projeto do Azure Functions

O Visual Studio Code,criar um projeto localmente no Azure Functions.

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

2. No prompt (>), insira e selecione Azure Functions: Criar Novo Projeto.

   

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

4. Todos os prompts, selecione ou insira os valores a seguir:

   Rápido	Ação	Descrição
   Selecione uma linguagem para o seu projeto de aplicativo de funções	Selecione .NET	Cria um projeto local do C# Functions
   Selecionar um runtime do .NET	Selecione .NET 8.0 Isolado.	Cria um projeto de Funções que dá suporte ao .NET 8 em execução um processo de trabalho isolado e ao Azure Functions Runtime 4.0.
   Selecione um modelo para a primeira função do projeto	Selecione Orquestração de Durable Functions.	Cria uma orquestração de Durable Functions.
   Escolher um tipo de armazenamento durável	Selecione MSSQL.	Seleciona o provedor de armazenamento MSSQL.
   Forneça um nome para a função	Inserir HelloOrchestration.	Um nome para a função de orquestração.
   Forneça um namespace	Inserir Company.Function.	Um namespace da classe gerada.
   Selecione como deseja abrir o projeto	Selecione Abrir na janela atual.	Abre o Visual Studio Code na pasta selecionada.

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

Outro arquivo, HelloOrchestration.cs, contém os blocos de construção básicos de um aplicativo Durable Functions:

Para obter mais informações sobre essas funções, consulte Tipos e recursos da Durable Functions.

Configurar seu banco de dados

Como o back-end do MSSQL foi projetado para portabilidade, você tem várias opções para configurar seu banco de dados de backup. Por exemplo, você pode configurar uma instância do SQL Server local, usar um Bando de Dados SQL do Azure totalmente gerenciado ou usar qualquer outra opção de hospedagem compatível com o SQL Server.

Você também pode fazer um desenvolvimento local offline usando o SQL Server Express no seu computador Windows local ou usar uma imagem do Docker do SQL Server em execução em um contêiner do Docker.

Este início rápido se concentra no uso de uma imagem do Docker do SQL Server.

Configurar sua instância local do SQL Server baseada no Docker

Use os comandos do PowerShell a seguir para configurar um banco de dados local do SQL Server no Docker. Você pode 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 ouvindo na porta 1443. Se a porta 1443 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 seu 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 instalação do banco de dados tiver sido concluída com sucesso, o nome do banco de dados (por exemplo, DurableDB) irá aparecer no resultado da linha de comando:

name

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

tempdb

model

msdb

DurableDB

Resolução de problemas

Se você encontrar "Resposta de erro do daemon: falha no exec do runtime do OCI" ao executar docker exec para criar o banco de dados, é provável que a pasta /opt/mssql-tools/bin/sqlcmd não exista. Abra o Docker Desktop, selecione o contêiner do Docker do SQL Server, selecione Arquivos e procure a pasta mssql-tools. Verifique se essa pasta tem um nome diferente, como /opt/mssql-tools18/bin/sqlcmd. Atualize o comando adequadamente.

No ODBC Driver 18 para SQL Server, a opção de conexão Encrypt é definida como true por padrão. Se você encontrar "error:1416F086:SSL routines:tls_process_server_certificate:certificate verify failed:self signed certificate" ao executar docker exec para realizar operações de banco de dados, acrescente -C, que é equivalente à opção ADO.net TRUSTSERVERCERTIFICATE = true.

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

O back-end do MSSQL precisa de uma cadeia de conexão para acessar seu banco de dados. O que você deve fazer para obter uma cadeia de conexão depende, em grande parte, do seu provedor específico do MSSQL Server.

Se você usar os comandos do Docker mencionados anteriormente sem alterar nenhum parâmetro, sua cadeia de conexão será a seguinte:

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

Em local.settings.json, atribua a cadeia de conexão da instância do SQL Server baseada no Docker a SQLDB_Connection. Essa variável foi adicionada pelo Visual Studio Code quando você escolheu o MSSQL como o 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, que é necessário para executar qualquer aplicativo de funções.

Abra outra janela do terminal na pasta raiz do aplicativo e inicie o aplicativo de funções executando func host start.

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

   

2. Use uma ferramenta de teste HTTP para enviar uma solicitação HTTP POST ao ponto de extremidade da URL.

   A resposta é o resultado inicial da função HTTP. Isso informa que a orquestração do Durable Functions foi iniciada com êxito. Ela ainda não exibe o resultado final da orquestração. A resposta inclui algumas URLs úteis.

3. Copie o valor da URL para statusQueryGetUri, cole-o na barra de endereço do seu 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 a instância de orquestração do status. Você deverá ver que a instância foi concluída e inclui as saídas ou resultados do aplicativo Durable Functions, como nesse 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"
   }
   

Executar seu aplicativo no Azure

Para executar seu aplicativo no Azure, você precisa criar vários recursos. Para uma limpeza conveniente posteriormente, crie todos os recursos no mesmo grupo de recursos.

Criar um banco de dados SQL do Azure

No portal do Azure, você pode criar um banco de dados SQL do Azure. Durante a criação:

• Habilitar os serviços e recursos do Azure para acessar este servidor ( em Rede)
• Defina o valor para Agrupamento do banco de dados (em Configurações adicionais) como Latin1_General_100_BIN2_UTF8.

Criar um aplicativo do Azure Functions e recursos de suporte

1. Abra uma janela do 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 da conta de armazenamento devem conter apenas números de três a 24 caracteres e letras minúsculas.
   • Um plano de aplicativo de funções Premium
   • Um aplicativo de funções

   # 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 do aplicativo, como credenciais nas cadeias de conexão. Você pode escolher entre a 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 ela 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 Banco de Dados SQL do Azure

Armazenamento do Azure

Atribua a função de Proprietário de Dados do Blob de Armazenamento à identidade para ter acesso à 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"

Banco de Dados SQL do Azure

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

   O destinatário é sua identidade, portanto, altere para seu email:

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

   Defina o destinatário como administrador do banco de dados SQL do Azure.

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

2. Conecte-se ao banco de dados SQL criado anteriormente usando ferramentas como o Azure Data Studio ou o SQL Management Server Studio. 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 à sua identidade acesso 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 banco de dados master e conceda à sua identidade acesso dbmanager:

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

Definir configurações de aplicativo necessárias

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

• AzureWebJobsStorage__accountName: nome da conta de 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 você estiver usando a identidade gerenciada atribuída pelo usuário para autenticar no banco de dados SQL, a cadeia de conexão deverá ser semelhante à 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 aplicativos de Consumo Flexível, use uma cadeia de conexão para se autenticar por enquanto. 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 conexão deve ter esse 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"

Implantar o projeto local no Azure e testar

Por fim, na pasta do projeto raiz, implante seu aplicativo no Azure executando:

func azure functionapp publish $functionApp

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

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

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

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

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

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

Após executar um orquestrador simples, você deverá ver pelo menos um resultado, conforme mostrado nesse exemplo:

Próximas etapas

• Hospede um aplicativo Durable Functions usando o back-end MSSQL em Aplicativos de Contêiner do Azure.
• Consulte a documentação do provedor de armazenamento MSSQL para obter mais informações sobre a arquitetura, a configuração e o comportamento da carga de trabalho desse back-end.