Usare riferimenti Configurazione app per servizio app e Funzioni di Azure (anteprima)
Questo argomento illustra come usare i dati di configurazione nell'applicazione servizio app o Funzioni di Azure senza richiedere modifiche al codice. app Azure Configurazione è un servizio per gestire centralmente la configurazione dell'applicazione. Inoltre, è uno strumento di controllo efficace per i valori di configurazione nel tempo o nelle versioni.
Concessione dell'accesso dell'app a Configurazione app
Per iniziare a usare i riferimenti Configurazione app in servizio app, è necessario innanzitutto un archivio Configurazione app e fornire all'app l'autorizzazione per accedere ai valori di chiave di configurazione nell'archivio.
Creare un archivio Configurazione app seguendo la guida introduttiva Configurazione app.
Nota
Configurazione app riferimenti non supportano ancora gli archivi di configurazione con restrizioni di rete.
Creare un'identità gestita per l'applicazione.
Configurazione app riferimenti useranno l'identità assegnata dal sistema dell'app per impostazione predefinita, ma è possibile specificare un'identità assegnata dall'utente.
Abilitare l'identità appena creata per avere il set corretto di autorizzazioni di accesso nell'archivio Configurazione app. Aggiornare le assegnazioni di ruolo per l'archivio. Si assegnerà
App Configuration Data Readeril ruolo a questa identità, con ambito sulla risorsa.
Accedere Configurazione app Store con un'identità assegnata dall'utente
Alcune app potrebbero dover fare riferimento alla configurazione in fase di creazione, quando un'identità assegnata dal sistema non sarebbe ancora disponibile. In questi casi, è possibile creare un'identità assegnata dall'utente e assegnare in anticipo l'accesso all'archivio Configurazione app. Seguire questa procedura per creare un'identità assegnata dall'utente per Configurazione app archivio.
Dopo aver concesso le autorizzazioni all'identità assegnata dall'utente, seguire questa procedura:
Assegnare l'identità all'applicazione, se non è già stato fatto.
Configurare l'app per usare questa identità per Configurazione app operazioni di riferimento impostando la
keyVaultReferenceIdentityproprietà sull'ID risorsa dell'identità assegnata dall'utente. Anche se la proprietà ha keyVault nel nome, l'identità verrà applicata anche ai riferimenti Configurazione app.userAssignedIdentityResourceId=$(az identity show -g MyResourceGroupName -n MyUserAssignedIdentityName --query id -o tsv) appResourceId=$(az webapp show -g MyResourceGroupName -n MyAppName --query id -o tsv) az rest --method PATCH --uri "${appResourceId}?api-version=2021-01-01" --body "{'properties':{'keyVaultReferenceIdentity':'${userAssignedIdentityResourceId}'}}"
Questa configurazione verrà applicata a tutti i riferimenti di questa app.
Concessione dell'accesso dell'app agli insiemi di credenziali delle chiavi a cui si fa riferimento
Oltre a archiviare i valori di configurazione non elaborati, app Azure Configuration ha il proprio formato per l'archiviazione dei riferimenti a Key Vault. Se il valore di un riferimento Configurazione app è un riferimento a Key Vault in Configurazione app Store, l'app dovrà disporre anche dell'autorizzazione per accedere all'insieme di credenziali delle chiavi specificato.
Nota
Il concetto di riferimenti all'insieme di credenziali delle chiavi di configurazione app Azure non deve essere confuso con il concetto di riferimenti servizio app e Funzioni di Azure Key Vault. L'app può usare qualsiasi combinazione di queste, ma esistono alcune importanti differenze da notare. Se l'insieme di credenziali deve essere limitato in rete o è necessario che l'app venga aggiornata periodicamente alle versioni più recenti, è consigliabile usare l'approccio diretto servizio app e Funzioni di Azure anziché usare un riferimento Configurazione app.
Identificare l'identità usata per il riferimento Configurazione app. L'accesso all'insieme di credenziali deve essere concesso alla stessa identità.
Creare un criterio di accesso in Key Vault per tale identità. Abilitare l'autorizzazione per il segreto "Get" in questi criteri. Non configurare l'"applicazione autorizzata" o le impostazioni di
applicationId, poiché questa operazione non è compatibile con un'identità gestita.
Sintassi del riferimento
Un riferimento Configurazione app è nel formato @Microsoft.AppConfiguration({referenceString}), dove {referenceString} viene sostituito da quanto segue:
| Parti stringa di riferimento | Descrizione |
|---|---|
| Endpoint=endpoint; | Endpoint è la parte necessaria della stringa di riferimento. Il valore per Endpoint deve avere l'URL della risorsa Configurazione app. |
| Key=keyName; | La chiave costituisce la parte richiesta della stringa di riferimento. Il valore per Key deve essere il nome della chiave da assegnare all'impostazione App. |
| Label=label | La parte Label è facoltativa nella stringa di riferimento. L'etichetta deve essere il valore di Label per la chiave specificata in Key |
Ad esempio, un riferimento completo con Label sarà simile al seguente:
@Microsoft.AppConfiguration(Endpoint=https://myAppConfigStore.azconfig.io; Key=myAppConfigKey; Label=myKeysLabel)
In alternativa, senza :Label
@Microsoft.AppConfiguration(Endpoint=https://myAppConfigStore.azconfig.io; Key=myAppConfigKey)
Qualsiasi modifica di configurazione all'app che genera un riavvio del sito causa un recupero immediato di tutti i valori chiave di riferimento dall'archivio Configurazione app.
Nota
L'aggiornamento automatico/recupero di questi valori quando i valori chiave sono stati aggiornati in Configurazione app, non è attualmente supportato.
Impostazioni dell'applicazione di origine da Configurazione app
Configurazione app i riferimenti possono essere usati come valori per L'applicazione Impostazioni, consentendo di mantenere i dati di configurazione in Configurazione app anziché nella configurazione del sito. L'applicazione Impostazioni e Configurazione app valori chiave-valore vengono crittografati in modo sicuro inattivi. Se sono necessarie funzionalità di gestione della configurazione centralizzate, i dati di configurazione devono essere inseriti in Configurazione app.
Per usare un riferimento Configurazione app per un'impostazione dell'app, impostare il riferimento come valore dell'impostazione. L'app può fare riferimento al valore di Configurazione tramite la chiave come di consueto. Non sono necessarie modifiche al codice.
Suggerimento
La maggior parte delle impostazioni dell'applicazione che usano riferimenti Configurazione app deve essere contrassegnata come impostazioni dello slot, in quanto devono essere presenti archivi o etichette separati per ogni ambiente.
Considerazioni sul montaggio File di Azure
Le app possono usare l'impostazione dell'applicazione WEBSITE_CONTENTAZUREFILECONNECTIONSTRING per montare File di Azure come file system. Questa impostazione include controlli di convalida aggiuntivi per assicurarsi che l'app possa essere avviata correttamente. La piattaforma si basa sulla condivisione di contenuto all'interno di File di Azure e presuppone un nome predefinito, a meno che non ne venga specificato uno tramite l'impostazione WEBSITE_CONTENTSHARE . Per eventuali richieste che modificano queste impostazioni, la piattaforma tenterà di convalidare se la condivisione di contenuto esiste e tenterà di crearla in caso contrario. Se non riesce a individuare o creare la condivisione contenuto, la richiesta viene bloccata.
Se si usano riferimenti Configurazione app per questa impostazione, questo controllo di convalida avrà esito negativo per impostazione predefinita, perché la connessione stessa non può essere risolta durante l'elaborazione della richiesta in ingresso. Per evitare questo problema, è possibile ignorare la convalida impostando WEBSITE_SKIP_CONTENTSHARE_VALIDATION su "1". Questa impostazione ignora tutti i controlli e la condivisione contenuto non verrà creata automaticamente. Assicurarsi che venga creato in anticipo.
Attenzione
Se si ignora la convalida e la stringa di connessione o la condivisione di contenuto non è valida, l'app non sarà in grado di avviarsi correttamente e gestirà solo errori HTTP 500.
Nell'ambito della creazione del sito, è anche possibile che il tentativo di montaggio della condivisione contenuto non sia riuscito a causa di autorizzazioni di identità gestite non propagate o che l'integrazione della rete virtuale non sia configurata. È possibile posticipare la configurazione File di Azure fino a un secondo momento nel modello di distribuzione per adattarla alla configurazione richiesta. Per altre informazioni, vedere Distribuzione di Azure Resource Manager. servizio app userà un file system predefinito fino a quando non viene configurato File di Azure e i file non vengono copiati in modo da assicurarsi che non si verifichino tentativi di distribuzione durante il periodo provvisorio prima che File di Azure venga montato.
Distribuzione Azure Resource Manager
Durante l'automazione delle distribuzioni di risorse tramite modelli di Azure Resource Manager, potrebbe essere necessario disporre in sequenza le dipendenze in un determinato ordine per usufruire di questa funzionalità. Si noti che è necessario definire le impostazioni dell'applicazione come risorsa propria, anziché usare una siteConfig proprietà nella definizione del sito. Questo avviene perché il sito deve essere definito per primo, in modo che l'identità assegnata dal sistema venga creata insieme al sito e possa essere usata nei criteri di accesso.
Di seguito è riportato un esempio di pseudo-modello per un'app per le funzioni con riferimenti Configurazione app:
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"roleNameGuid": {
"type": "string",
"defaultValue": "[newGuid()]",
"metadata": {
"description": "A new GUID used to identify the role assignment"
}
}
},
"variables": {
"functionAppName": "DemoMBFunc",
"appConfigStoreName": "DemoMBAppConfig",
"resourcesRegion": "West US2",
"appConfigSku": "standard",
"FontNameKey": "FontName",
"FontColorKey": "FontColor",
"myLabel": "Test",
"App Configuration Data Reader": "[concat('/subscriptions/', subscription().subscriptionId, '/providers/Microsoft.Authorization/roleDefinitions/', '516239f1-63e1-4d78-a4de-a74fb236a071')]"
},
"resources": [
{
"type": "Microsoft.Web/sites",
"name": "[variables('functionAppName')]",
"apiVersion": "2021-03-01",
"location": "[variables('resourcesRegion')]",
"identity": {
"type": "SystemAssigned"
},
//...
"resources": [
{
"type": "config",
"name": "appsettings",
"apiVersion": "2021-03-01",
//...
"dependsOn": [
"[resourceId('Microsoft.Web/sites', variables('functionAppName'))]",
"[resourceId('Microsoft.AppConfiguration/configurationStores', variables('appConfigStoreName'))]"
],
"properties": {
"WEBSITE_FONTNAME": "[concat('@Microsoft.AppConfiguration(Endpoint=', reference(resourceId('Microsoft.AppConfiguration/configurationStores', variables('appConfigStoreName'))).endpoint,'; Key=',variables('FontNameKey'),'; Label=',variables('myLabel'), ')')]",
"WEBSITE_FONTCOLOR": "[concat('@Microsoft.AppConfiguration(Endpoint=', reference(resourceId('Microsoft.AppConfiguration/configurationStores', variables('appConfigStoreName'))).endpoint,'; Key=',variables('FontColorKey'),'; Label=',variables('myLabel'), ')')]",
"WEBSITE_ENABLE_SYNC_UPDATE_SITE": "true"
//...
}
},
{
"type": "sourcecontrols",
"name": "web",
"apiVersion": "2021-03-01",
//...
"dependsOn": [
"[resourceId('Microsoft.Web/sites', variables('functionAppName'))]",
"[resourceId('Microsoft.Web/sites/config', variables('functionAppName'), 'appsettings')]"
]
}
]
},
{
"type": "Microsoft.AppConfiguration/configurationStores",
"name": "[variables('appConfigStoreName')]",
"apiVersion": "2019-10-01",
"location": "[variables('resourcesRegion')]",
"sku": {
"name": "[variables('appConfigSku')]"
},
//...
"dependsOn": [
"[resourceId('Microsoft.Web/sites', variables('functionAppName'))]"
],
"properties": {
},
"resources": [
{
"type": "keyValues",
"name": "[variables('FontNameKey')]",
"apiVersion": "2021-10-01-preview",
//...
"dependsOn": [
"[resourceId('Microsoft.AppConfiguration/configurationStores', variables('appConfigStoreName'))]"
],
"properties": {
"value": "Calibri",
"contentType": "application/json"
}
},
{
"type": "keyValues",
"name": "[variables('FontColorKey')]",
"apiVersion": "2021-10-01-preview",
//...
"dependsOn": [
"[resourceId('Microsoft.AppConfiguration/configurationStores', variables('appConfigStoreName'))]"
],
"properties": {
"value": "Blue",
"contentType": "application/json"
}
}
]
},
{
"scope": "[resourceId('Microsoft.AppConfiguration/configurationStores', variables('appConfigStoreName'))]",
"type": "Microsoft.Authorization/roleAssignments",
"apiVersion": "2020-04-01-preview",
"name": "[parameters('roleNameGuid')]",
"properties": {
"roleDefinitionId": "[variables('App Configuration Data Reader')]",
"principalId": "[reference(resourceId('Microsoft.Web/sites/', variables('functionAppName')), '2020-12-01', 'Full').identity.principalId]",
"principalType": "ServicePrincipal"
}
}
]
}
Nota
In questo esempio, la distribuzione del controllo del codice sorgente dipende dalle impostazioni dell'applicazione. Si tratta in genere di un comportamento non sicuro, dato che l'aggiornamento delle impostazioni dell'applicazione ha un comportamento asincrono. Tuttavia, dato che è stata inclusa l'impostazione dell'applicazione WEBSITE_ENABLE_SYNC_UPDATE_SITE, l'aggiornamento è sincrono. Questo significa che la distribuzione del controllo del codice sorgente inizierà solo dopo l'aggiornamento completo delle impostazioni dell'applicazione. Per altre impostazioni dell'app, vedere Variabili di ambiente e impostazioni dell'app in app Azure Servizio.
Risoluzione dei problemi relativi ai riferimenti Configurazione app
Se un riferimento non viene risolto correttamente, verrà invece usato il valore di riferimento. Per le impostazioni dell'applicazione, viene creata una variabile di ambiente il cui valore ha la @Microsoft.AppConfiguration(...) sintassi. Può causare un errore, perché l'applicazione prevedeva invece un valore di configurazione.
In genere, questo errore potrebbe essere dovuto a una configurazione errata dei criteri di accesso Configurazione app. Tuttavia, potrebbe anche essere dovuto a un errore di sintassi nel riferimento o al valore della chiave di configurazione non esistente nell'archivio.