Distribuire Data API Builder su Servizio app di Azure

Questa guida illustra come distribuire Il generatore di API dati (DAB) in Servizio app di Azure senza compilare o gestire immagini del contenitore. Il servizio app offre il supporto predefinito per TLS, domini personalizzati, scalabilità, monitoraggio e autenticazione Microsoft Entra.

Diagramma che mostra l'architettura complessiva dopo il completamento della distribuzione su Servizio app di Azure.

Tip

Se l'ambiente usa contenitori, vedere Deploy in App contenitore di Azure o Deploy in servizio Azure Kubernetes.

Prerequisiti

Importante

Lo stack predefinito del servizio app .NET contiene il runtime di .NET, ma non contiene l'SDK .NET. Ripristinare DAB e assemblare il pacchetto di distribuzione nel computer di sviluppo o compilazione locale. Non eseguire dotnet tool restore all'avvio di App Service.

Compilare il file di configurazione

Compilare un file di configurazione DAB per connettersi al database esistente.

  1. Creare una directory vuota nel computer locale per archiviare i file di configurazione e gli artefatti di distribuzione.

  2. Inizializzare un nuovo file di configurazione di base usando dab init. Usare la @env() funzione per fare riferimento alla DATABASE_CONNECTION_STRING variabile di ambiente in modo che le credenziali non vengano archiviate nel file di configurazione.

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

    Importante

    Sostituire <database-type> con un tipo di database supportato, ad esempio mssql, postgresql, mysqlo cosmosdb_nosql. Alcuni tipi di database richiedono impostazioni di configurazione aggiuntive per l'inizializzazione.

  3. Aggiungere almeno un'entità di database alla configurazione. Usare il dab add comando per configurare un'entità. Ripetere dab add tutte le volte necessarie per le entità.

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

  4. Aprire ed esaminare il contenuto del file dab-config.json . Verifica che:

    • data-source.connection-string Utilizza @env('DATABASE_CONNECTION_STRING')
    • Le entità e le autorizzazioni sono corrette

    Importante

    Non incorporare stringhe di connessione letterali o segreti in dab-config.json. Usare la @env() funzione in modo che i valori vengano risolti dalle variabili di ambiente in fase di esecuzione.

Aggiungere DAB per la compilazione

Usare un manifesto dello strumento .NET locale per aggiungere la versione DAB nel computer di sviluppo o di compilazione. Il manifesto rende riproducibili le compilazioni, ma non contiene i file binari DAB ripristinati. Questi file binari vengono copiati nel pacchetto di distribuzione più avanti in questa guida.

  1. Creare un manifesto dello strumento locale .NET nella directory del progetto.

    dotnet new tool-manifest

  2. Installare una versione specifica di Generatore API dati come strumento locale. Sostituire <dab-version> con la versione da distribuire, ad esempio 2.0.9.

    dotnet tool install microsoft.dataapibuilder --version "<dab-version>"

  3. Verificare che il manifesto esista in .config/dotnet-tools.json.

  4. Ripristinare lo strumento bloccato nel computer di sviluppo o di compilazione.

    dotnet tool restore

    Note

    L'operazione di ripristino popola la cache del pacchetto NuGet locale. Il pacchetto di distribuzione del servizio app deve includere il payload di runtime ripristinato; la distribuzione solo .config/dotnet-tools.json non è sufficiente.

Testare localmente

Prima di eseguire la distribuzione in Azure, verificare che il runtime venga avviato e che gli endpoint funzionino.

  1. Impostare il stringa di connessione come variabile di ambiente locale.

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

  2. Avviare il runtime DAB in locale.

    dotnet tool run dab start

  3. Testare l'endpoint REST passando all'interfaccia utente di Swagger o effettuando una richiesta a /api/<entity-name>.

  4. Eseguire il test sull'endpoint GraphQL a /graphql.

  5. Arrestare il runtime dopo aver verificato tutti gli endpoint.

Creare le risorse del servizio app

Creare le risorse di Azure necessarie per ospitare DAB nel servizio app.

  1. Creare un nuovo gruppo di risorse. Questo gruppo di risorse viene usato per tutte le nuove risorse in questa guida.

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

    Tip

    Prendere in considerazione la denominazione del gruppo di risorse msdocs-dab-appservice.

  2. Creare un piano di servizio app.

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

    Note

    Questa guida usa il livello B1 (Basic) in Linux.

  3. Creare l'app Web con il runtime .NET 8 e un'identità gestita assegnata dal sistema.

    az webapp create --name "<app-name>" --resource-group "<resource-group-name>" --plan "<plan-name>" --runtime "DOTNETCORE:8.0" --assign-identity "[system]"

    Tip

    Verificare i runtime disponibili per il piano con az webapp list-runtimes --os linux.

Configurare le impostazioni del servizio app

Configurare le variabili di ambiente e il comando di avvio necessari affinché App Service esegua DAB.

  1. Impostare il stringa di connessione del database come impostazione dell'applicazione in App Service.

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

    Tip

    Usare un stringa di connessione che non include segreti. Usare invece le identità gestite e l'autenticazione di Microsoft Entra per gestire l'accesso tra il database e il Servizio App. Per altre informazioni, vedere Servizi di Azure che usano identità gestite.

  2. Configurare l'indirizzo su cui DAB è in ascolto. Porta 8080 è la porta dell'applicazione per lo stack integrato di App Service Linux.

    az webapp config appsettings set --name "<app-name>" --resource-group "<resource-group-name>" --settings ASPNETCORE_URLS="http://0.0.0.0:8080"

  3. Abilita Always On e la registrazione del file system prima della prima distribuzione. Always On è disponibile nel livello B1 usato in questa guida.

    az webapp config set --name "<app-name>" --resource-group "<resource-group-name>" --always-on true

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

  4. Creare uno script di avvio che avvia il payload del runtime DAB incluso nel pacchetto di distribuzione. Creare un file denominato startup.sh nella directory del progetto.

    #!/bin/sh
set -eu
exec dotnet ./dab/Microsoft.DataApiBuilder.dll start --config ./dab-config.json

    Importante

    Assicurarsi di startup.sh usare terminazioni di riga LF (Unix), non CRLF. Gli editor di Windows possono salvare con CRLF per impostazione predefinita, provocando il fallimento dello script nell'host del servizio app Linux.

  5. Impostare il comando di avvio nel servizio app.

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

Configurare l'identità gestita per Azure SQL

Se l'origine dati è Azure SQL, autorizza nel database l'identità gestita assegnata dal sistema dell'app Web. Ignorare questa sezione se si usa un database o un metodo di autenticazione diverso.

  1. Connettiti al database di destinazione in qualità di amministratore Microsoft Entra.

  2. Creare un utente di database indipendente per l'identità dell'app Web e concedere solo le autorizzazioni richieste dalle entità DAB. Nell'esempio seguente sono supportate operazioni di lettura e scrittura.

    CREATE USER [<app-name>] FROM EXTERNAL PROVIDER;
ALTER ROLE [db_datareader] ADD MEMBER [<app-name>];
ALTER ROLE [db_datawriter] ADD MEMBER [<app-name>];

    Note

    La propagazione delle identità in Microsoft Entra può richiedere alcuni minuti dopo la creazione dell'app web. Se CREATE USER non riesce a risolvere immediatamente l'identità, attendere e riprovare.

  3. Imposta DATABASE_CONNECTION_STRING su una stringa di connessione dell'identità gestita di Azure SQL.

    az webapp config appsettings set --name "<app-name>" --resource-group "<resource-group-name>" --settings DATABASE_CONNECTION_STRING="Server=tcp:<sql-server-name>.database.windows.net,1433;Initial Catalog=<database-name>;Authentication=Active Directory Managed Identity;Encrypt=True;TrustServerCertificate=False;"

Distribuzione su App Service

Copiare il runtime DAB ripristinato nella directory dell'applicazione e quindi distribuire la directory usando ZIP deploy.

  1. Creare una directory dell'applicazione contenente la configurazione DAB, lo script di avvio e il payload di runtime ripristinato.

    Negli esempi viene usata la versione 2.0.9DAB . Impostare la versione sulla stessa versione aggiunta in .config/dotnet-tools.json.

    $dabVersion = "2.0.9"
$globalPackages = (dotnet nuget locals global-packages --list) -replace '^global-packages:\s*', ''
$dabPayload = Join-Path $globalPackages "microsoft.dataapibuilder/$dabVersion/tools/net8.0/any"
$appDirectory = Join-Path (Get-Location) "app"

Remove-Item $appDirectory -Recurse -Force -ErrorAction SilentlyContinue
New-Item -ItemType Directory -Path (Join-Path $appDirectory "dab") -Force | Out-Null
Copy-Item dab-config.json, startup.sh -Destination $appDirectory
Copy-Item (Join-Path $dabPayload "*") -Destination (Join-Path $appDirectory "dab") -Recurse

if (-not (Test-Path (Join-Path $appDirectory "dab/Microsoft.DataApiBuilder.dll"))) {
    throw "The restored DAB runtime payload wasn't found."
}

    Importante

    Esegui questi comandi sulla stessa macchina in cui hai ripristinato lo strumento DAB fissato. Se l'ambiente sovrascrive la directory globale dei pacchetti NuGet, dotnet nuget locals ne determina la posizione.

  2. Creare un file ZIP con separatori di ingresso portabili / . La radice dell'archivio deve contenere direttamente dab-config.json, startup.sh e la cartella dab/. Non creare un file ZIP della directory padre app.

    Remove-Item deploy.zip -Force -ErrorAction SilentlyContinue
tar.exe -a -c -f deploy.zip -C $appDirectory dab-config.json startup.sh dab

    Avvertimento

    In Windows Compress-Archive è possibile archiviare voci annidate con \ separatori. La distribuzione ZIP Kudu può rifiutare l'archivio con HTTP 400. Usare uno strumento ZIP che mantenga i separatori / ed esaminare le voci dell'archivio se la distribuzione restituisce HTTP 400 senza dettagli.

  3. Distribuire il pacchetto ZIP nel servizio app.

    az webapp deploy --resource-group "<resource-group-name>" --name "<app-name>" --src-path deploy.zip --type zip --clean true --restart false --timeout 600000

  4. Riavviare l'app Web al termine della distribuzione.

    az webapp restart --resource-group "<resource-group-name>" --name "<app-name>"

Verificare la distribuzione

Dopo la distribuzione, verificare che DAB venga avviato correttamente nel servizio app.

  1. Aprire l'URL del servizio app. La risposta radice include lo stato e la versione di DAB.

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

  2. Testare gli endpoint REST e GraphQL usando gli stessi percorsi di entità testati in locale. L'app distribuita usa lo stesso dab-config.json, quindi il comportamento dell'endpoint deve corrispondere al runtime locale.

    https://<app-name>.azurewebsites.net/api/<entity-name>
https://<app-name>.azurewebsites.net/graphql

    Note

    In modalità di produzione, /health può restituire HTTP 403 quando il client non è autorizzato a visualizzare il report completo sullo stato di integrità. Se gli endpoint dell'entità radice e autorizzata restituiscono correttamente, una risposta 403 da /health non indica un errore di avvio.

  3. Se un endpoint restituisce un errore imprevisto, esaminare o scaricare i log dell'applicazione. La registrazione è stata abilitata prima della distribuzione in questa guida.

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

az webapp log download --name "<app-name>" --resource-group "<resource-group-name>" --log-file appservice-logs.zip

Configurare l'autenticazione (facoltativo)

Proteggere l'endpoint del Servizio App con Microsoft Entra ID per l'uso in produzione.

Per i passaggi dettagliati, vedere Configurare l'autenticazione del servizio app.

Dopo aver abilitato l'autenticazione di App Service, configuri DAB perché consideri attendibili le intestazioni di identità aggiunte da App Service. Eseguire questo comando nel computer di sviluppo, quindi ricompilare e ridistribuire il pacchetto ZIP.

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

Importante

Il provider di autenticazione AppService nelle dab-config.json si fida delle intestazioni inserite dall'autenticazione del Servizio App. Assicurarsi che l'autenticazione del servizio app sia abilitata quando si usa questo provider nell'ambiente di produzione. Per altre informazioni, vedere Easy Auth (Servizio app).

Note

L'autenticazione di App Service protegge l'accesso al tuo endpoint. Le autorizzazioni delle entità DAB regolano comunque le operazioni consentite dal runtime. Per una demo anonima, non fare affidamento sugli header di identità di App Service. Per l'accesso in base al ruolo, abilitare l'autenticazione del servizio app e aggiornare le autorizzazioni dell'entità per usare ruoli autenticati o personalizzati anziché anonymous:*.

Risolvere i problemi di implementazione

Usare i sintomi seguenti per identificare i problemi di distribuzione comuni.

Sintomo Causa e risoluzione
La distribuzione ZIP restituisce HTTP 400 senza dettagli Esaminare i separatori radice e di ingresso ZIP. Ricrea il file ZIP con separatori / e assicurati che contenga direttamente dab-config.json, startup.sh e dab/.
L'app restituisce HTTP 503 e i log contengono No .NET SDKs were found o The application 'tool' does not exist Il comando di avvio sta tentando di eseguire dotnet tool. Ricompilare il pacchetto con il payload DAB ripristinato e richiamare Microsoft.DataApiBuilder.dll direttamente.
L'avvio raggiunge il comando dell'utente, ma la fase di warmup di App Service ha esito negativo Verificare che lo script di avvio usi le terminazioni LF, usare sh startup.sh, verificare i percorsi del payload DAB e controllare l'URL di ascolto e gli errori del database nei log.
DAB viene avviato ma le richieste di database hanno esito negativo Verificare che l'identità gestita dell'app Web esista come utente del database e disponga delle autorizzazioni necessarie per le entità configurate.
/health restituisce HTTP 403 mentre REST o GraphQL funziona DAB è in esecuzione, ma il richiedente non è autorizzato a visualizzare il report completo sullo stato di integrità. Convalida invece l'elemento radice o un endpoint autorizzato dell'entità.
Una distribuzione ZIP più grande restituisce HTTP 502 Controllare la cronologia della distribuzione prima di riprovare. Distribuire in modo sincrono con un timeout esplicito, disabilitare il riavvio implicito e riavviare al termine della distribuzione.

Pulire le risorse

Quando l'app Web e le relative risorse non sono più necessarie, eliminare il gruppo di risorse.

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

Contenuti correlati

  • Last updated on