Quickstart: Een Durable Functions-app maken die gebruikmaakt van de MSSQL-opslagprovider

Gebruik Durable Functions, een functie van Azure Functions, om stateful functies te schrijven in een serverloze omgeving. Durable Functions beheert de status, controlepunten en start deze opnieuw in uw toepassing.

Durable Functions ondersteunt verschillende opslagproviders, ook wel back-ends genoemd, voor het opslaan van indeling en runtimestatus van entiteiten. In deze quickstart maakt u een Durable Functions-app voor het gebruik van de Microsoft SQL Server-opslagprovider (MSSQL) met behulp van Visual Studio Code.

In deze quickstart maakt u een .NET-app (geïsoleerd model) voor demonstratiedoeleinden. Inhoud die in dit artikel wordt verstrekt, is op vergelijkbare wijze van toepassing op andere talen.

Vereisten

U hebt het volgende nodig om deze quickstart te voltooien:

• Visual Studio Code geïnstalleerd.

• Azure Functions Visual Studio Code-extensie geïnstalleerd.

• De nieuwste versie van Azure Functions Core Tools geïnstalleerd.

• .NET 8.0 SDK geïnstalleerd.

• Docker geïnstalleerd.

• Een Azure-abonnement.

• Een HTTP-testprogramma waarmee uw gegevens veilig blijven. Zie HTTP-testhulpprogramma's voor meer informatie.

Maak een Azure Functions-project aan

Maak in Visual Studio Code een lokaal Azure Functions-project.

1. Selecteer in het menu Beeld het opdrachtpalet (of selecteer Ctrl+Shift+P).

2. Voer bij de prompt (>) Azure Functions in en selecteer vervolgens Azure Functions: Nieuw project maken.

   

3. Kies Bladeren. Ga in het dialoogvenster Map selecteren naar een map die u voor uw project wilt gebruiken en kies Selecteren.

4. Selecteer of voer de volgende waarden in bij de prompts:

   Snel	Handeling	Beschrijving
   Selecteer een taal voor uw functie-app-project	.NET selecteren	Hiermee maakt u een lokaal C#Functions-project
   Een .NET-runtime selecteren	Selecteer .NET 8.0 geïsoleerd.	Hiermee maakt u een Functions-project dat ondersteuning biedt voor .NET 8 die wordt uitgevoerd in een geïsoleerd werkproces en de Azure Functions Runtime 4.0.
   Selecteer een sjabloon voor de eerste functie van uw project	Selecteer Durable Functions Orchestration.	Hiermee maakt u een Durable Functions-indeling.
   Een duurzaam opslagtype kiezen	Selecteer MSSQL.	Hiermee selecteert u de MSSQL-opslagprovider.
   Geef een functienaam op	Voer HelloOrchestration in.	Een naam voor de indelingsfunctie.
   Geef een naamruimte op	Voer Company.Function in.	Een naamruimte voor de gegenereerde klasse.
   Selecteer hoe u uw project wilt openen	Selecteer Openen in het huidige venster.	Hiermee opent u Visual Studio Code in de map die u hebt geselecteerd.

Visual Studio Code installeert Azure Functions Core Tools als het nodig is om het project te maken. Er wordt ook een functie-app-project gemaakt in een map. Dit project bevat de configuratiebestanden host.json en local.settings.json.

Een ander bestand, HelloOrchestration.cs, bevat de basisbouwstenen van een Durable Functions-app:

Zie Durable Functions-typen en -functies voor meer informatie over deze functies.

Uw database instellen

Omdat de MSSQL-back-end is ontworpen voor draagbaarheid, hebt u verschillende opties om uw back-updatabase in te stellen. U kunt bijvoorbeeld een on-premises SQL Server-exemplaar instellen, een volledig beheerd exemplaar van Azure SQL Database gebruiken of een andere hostoptie gebruiken die compatibel is met SQL Server.

U kunt ook lokaal, offline ontwikkelen met behulp van SQL Server Express op uw lokale Windows-computer of een SQL Server Docker-installatiekopie gebruiken die wordt uitgevoerd in een Docker-container.

Deze quickstart is gericht op het gebruik van een SQL Server Docker-installatiekopieën.

Uw lokale SQL Server-exemplaar op basis van Docker instellen

Gebruik de volgende PowerShell-opdrachten om een lokale SQL Server-database in Docker in te stellen. U kunt PowerShell installeren in Windows, macOS of 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"

U moet nu een lokale SQL Server hebben die wordt uitgevoerd op Docker en luistert op poort 1443. Als de poort 1443 conflicteert met een andere service, voert u deze opdrachten opnieuw uit nadat u de variabele $port hebt gewijzigd in een andere waarde.

Als u de installatie van uw database wilt valideren, voert u een query uit op uw nieuwe SQL-database:

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

Als de installatie van de database is voltooid, wordt de naam van uw database (bijvoorbeeld DurableDB) weergegeven in de opdrachtregeluitvoer:

name

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

tempdb

model

msdb

DurableDB

Probleemoplossingsproces

Als u 'Foutreactie van daemon: OCI Runtime exec is mislukt' tegenkomt bij het uitvoeren docker exec om de database te maken , bestaat de map /opt/mssql-tools/bin/sqlcmd waarschijnlijk niet. Open Docker Desktop, selecteer uw SQL Server Docker-container, selecteer Bestanden en blader naar de map mssql-tools. Controleer of deze map een andere naam heeft, zoals /opt/mssql-tools18/bin/sqlcmd. Werk de opdracht dienovereenkomstig bij.

In ODBC-stuurprogramma 18 voor SQL Server is de optie Verbinding versleutelen standaard ingesteld op true. Als u 'error:1416F086:SSL routines:tls_process_server_certificate:certificate verify failed:self signed certificate' tegenkomt bij het uitvoeren van docker exec om databasebewerkingen uit te voeren, voeg -C toe, wat gelijk is aan de optie ADO.net TRUSTSERVERCERTIFICATE = true.

SQL-verbindingsreeks toevoegen aan local.settings.json

De MSSQL-back-end heeft een verbindingsreeks nodig voor toegang tot uw database. Het verkrijgen van een verbindingsreeks is voornamelijk afhankelijk van uw specifieke MSSQL-serverprovider.

Als u de voorgaande Docker-opdrachten gebruikt zonder parameters te wijzigen, is het verbindingsreeks:

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

Wijs in local.settings.jsonde verbindingsreeks van het op Docker gebaseerde SQL Server-exemplaar toe aan SQLDB_Connection. Deze variabele is door Visual Studio Code toegevoegd toen u MSSQL als back-end voor uw Durable Functions-app hebt gekozen:

{
  "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>"
  }
}

Lokaal testen

Open een terminalvenster in de hoofdmap van je app en voer azurite start uit. Azurite is de Azure Storage-emulator, die nodig is voor het uitvoeren van een functie-app.

Open een ander terminalvenster in de hoofdmap van uw app en start de functie-app door uit te voeren func host start.

1. Kopieer in het terminalvenster het URL-eindpunt van uw door HTTP geactiveerde functie.

   

2. Gebruik een HTTP-testhulpprogramma om een HTTP POST-aanvraag naar het URL-eindpunt te verzenden.

   Het antwoord is het eerste resultaat van de HTTP-functie. Het laat u weten dat de Durable Functions-orkestratie succesvol is gestart. Het eindresultaat van de indeling wordt nog niet weergegeven. De reactie bevat enkele nuttige URL's.

3. Kopieer de URL-waarde voor statusQueryGetUri, plak deze in de adresbalk van uw browser en voer de aanvraag uit. U kunt ook het HTTP-testhulpprogramma blijven gebruiken om de GET-aanvraag uit te geven.

   De aanvraag voert een query uit op het indelingsexemplaar voor de status. U ziet dat het exemplaar is voltooid en dat het de uitvoer of resultaten van de Durable Functions-app bevat, zoals in dit voorbeeld:

   {
       "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"
   }
   

Uw app uitvoeren in Azure

Als u uw app in Azure wilt uitvoeren, moet u verschillende resources maken. Maak alle middelen in dezelfde resourcegroep aan om later gemakkelijk op te ruimen.

Een Azure SQL-database maken

In Azure Portal kunt u een Azure SQL-database maken. Tijdens het maken:

• Azure-services en -resources toegang geven tot deze server (onder Netwerken)
• Stel de waarde voor databasesortering (onder Aanvullende instellingen) in op Latin1_General_100_BIN2_UTF8.

Een Azure Functions-app en ondersteunende resources maken

1. Open een terminalvenster en meld u aan bij Azure:

   az login
   

2. Maak de volgende resources in dezelfde resourcegroep en regio als uw SQL-database:

   • Een opslagaccount voor algemeen gebruik, dat wordt gebruikt voor het opslaan van belangrijke app-gegevens, zoals de toepassingscode zelf. Namen van opslagaccounts mogen alleen uit drie tot 24 tekens bestaan.
   • Een premium-functie-app-abonnement
   • Een functie-app

   # 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
   

Een door Azure beheerde identiteit maken

Beheerde identiteiten maken uw app veiliger door geheimen uit uw app te elimineren, zoals referenties in de verbindingsreeksen. U kunt kiezen tussen door het systeem toegewezen en door de gebruiker toegewezen beheerde identiteit. In deze quickstart ziet u hoe u een door de gebruiker toegewezen beheerde identiteit instelt. Dit is de aanbevolen optie omdat deze niet is gekoppeld aan de levenscyclus van de app.

Met de volgende opdrachten maakt u de identiteitsresource en wijst u deze toe aan de app:

# 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)

Toegang verlenen tot Azure Storage en Azure SQL Database

Azure-opslag

Wijs de rol Storage Blob Data Owner toe voor toegang tot het opslagaccount.

# 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"

Azure SQL Database

1. Begin met het instellen van uw ontwikkelaarsidentiteit als de beheerder van de database.

   De toegewezen gebruiker vertegenwoordigt jouw identiteit, dus wijzig naar jouw e-mail:

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

   Toegewezen gebruiker instellen als beheerder van de Azure SQL-database:

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

2. Maak verbinding met de SQL-database die u eerder hebt gemaakt met behulp van hulpprogramma's zoals Azure Data Studio of SQL Management Server Studio. U kunt ook de volgende SQLCMD-opdracht uitvoeren om verbinding te maken:

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

   Geef uw identiteit als db_owner toegang door de volgende query op de database uit te voeren. Dit IDENTITY_OBJECT_ID is de PrincipalId van de stap waarin de identiteit wordt gecreëerd.

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

3. Maak verbinding met de master database en verleen uw identiteit dbmanager toegang.

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

Vereiste app-instellingen instellen

U moet de volgende app-instellingen toevoegen aan uw app:

• AzureWebJobsStorage__accountName: Azure Storage-accountnaam
• AzureWebJobsStorage__clientId: ClientId van de beheerde identiteit
• AzureWebJobsStorage__credential: Referentietype, dat een managedidentity is
• SQLDB_Connection: SQL Database-verbindingsreeks

Als u een door de gebruiker toegewezen beheerde identiteit gebruikt om te verifiëren bij de SQL-database, moet de verbindingsreeks er als volgt uitzien:

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';"

Gebruik voor Flex Consumption-apps een verbindingsreeks om voorlopig te verifiëren. U vindt deze door naar de SQL-databaseresource in Azure Portal te gaan, naar het tabblad Instellingen te gaan en vervolgens op Verbindingsreeksen te klikken:

De verbindingsreeks moet deze indeling hebben:

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;"

Voer de volgende opdracht uit om de instellingen in te stellen:

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

Verwijder de bestaande AzureWebJobsStorage instelling:

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

Het lokale project implementeren in Azure en testen

Implementeer ten slotte uw app in uw hoofdprojectmap in Azure door het volgende uit te voeren:

func azure functionapp publish $functionApp

Nadat de implementatie is voltooid, voert u het volgende uit om de HTTP-trigger-URL op te halen:

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

Test net als tijdens de lokale ontwikkeling met een HTTP-testhulpprogramma.

U kunt ook controleren of de MSSQL-back-end correct is geconfigureerd door een query uit te voeren op de database voor taakhubgegevens.

U kunt bijvoorbeeld query's uitvoeren op uw indelingsexemplaren in het overzichtsvenster van uw SQL-database. Selecteer Power Query-editor, verifieer en voer vervolgens de volgende query uit:

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

Nadat u een eenvoudige orchestrator hebt uitgevoerd, ziet u ten minste één resultaat, zoals wordt weergegeven in dit voorbeeld:

Volgende stappen

• Host een Durable Functions-app met behulp van de MSSQL-back-end in Azure Container Apps.
• Zie de documentatie van de MSSQL-opslagprovider voor meer informatie over de architectuur, configuratie en workload van deze back-end.