Guida introduttiva: Creare un archivio di configurazione app Azure usando un modello di Resource Manager

Articolo
04/07/2024

Questa guida di avvio rapido descrive come:

Distribuire un archivio di Configurazione app di Azure con un modello di Azure Resource Manager.
Creare coppie chiave-valore in un archivio di Configurazione app con un modello di Resource Manager.
Leggere le coppie chiave-valore in un archivio di Configurazione app da un modello di Resource Manager.

Suggerimento

I flag di funzionalità e i riferimenti a Key Vault sono tipi speciali di valori chiave. Vedere i passaggi successivi per esempi di creazione usando il modello di Resource Manager.

Un modello di Azure Resource Manager è un file JSON (JavaScript Object Notation) che definisce l'infrastruttura e la configurazione per il progetto. Il modello utilizza la sintassi dichiarativa. Si descrive la distribuzione prevista senza scrivere la sequenza di comandi di programmazione per creare la distribuzione.

Se l'ambiente soddisfa i prerequisiti e si ha familiarità con l'uso dei modelli di Resource Manager, selezionare il pulsante Distribuisci in Azure. Il modello verrà aperto nel portale di Azure.

Prerequisiti

Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.

Autorizzazione

La gestione app Azure risorsa di configurazione all'interno di un modello di Resource Manager richiede un ruolo di Azure Resource Manager, ad esempio collaboratore o proprietario. L'accesso ai dati di configurazione app Azure (valori chiave, snapshot) richiede il ruolo di Azure Resource Manager e app Azure ruolo del piano dati di configurazione in modalità di autenticazione ARM pass-through.

Rivedere il modello

Il modello usato in questo avvio rapido proviene dai modelli di avvio rapido di Azure. Crea un nuovo archivio di Configurazione app con due coppie chiave-valore al suo interno. Usa quindi la funzione reference per restituire i valori delle due risorse chiave-valore. La lettura del valore della chiave in questo modo ne consente l'uso in altre parti del modello.

La guida di avvio rapido usa l'elemento copy per creare più istanze di una risorsa chiave-valore. Per altre informazioni sull'elemento copy, vedere Iterazione delle risorse nei modelli di Azure Resource Manager.

Importante

Questo modello richiede la versione del provider di risorse di Configurazione app 2020-07-01-preview o successiva. Questa versione usa la funzione reference per leggere le coppie chiave-valore. La funzione listKeyValue usata per la lettura di coppie chiave-valore nella versione precedente non è disponibile a partire dalla versione 2020-07-01-preview.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "metadata": {
    "_generator": {
      "name": "bicep",
      "version": "0.5.6.12127",
      "templateHash": "2173262573838896712"
    }
  },
  "parameters": {
    "configStoreName": {
      "type": "string",
      "metadata": {
        "description": "Specifies the name of the App Configuration store."
      }
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]",
      "metadata": {
        "description": "Specifies the Azure location where the app configuration store should be created."
      }
    },
    "keyValueNames": {
      "type": "array",
      "defaultValue": [
        "myKey",
        "myKey$myLabel"
      ],
      "metadata": {
        "description": "Specifies the names of the key-value resources. The name is a combination of key and label with $ as delimiter. The label is optional."
      }
    },
    "keyValueValues": {
      "type": "array",
      "defaultValue": [
        "Key-value without label",
        "Key-value with label"
      ],
      "metadata": {
        "description": "Specifies the values of the key-value resources. It's optional"
      }
    },
    "contentType": {
      "type": "string",
      "defaultValue": "the-content-type",
      "metadata": {
        "description": "Specifies the content type of the key-value resources. For feature flag, the value should be application/vnd.microsoft.appconfig.ff+json;charset=utf-8. For Key Value reference, the value should be application/vnd.microsoft.appconfig.keyvaultref+json;charset=utf-8. Otherwise, it's optional."
      }
    },
    "tags": {
      "type": "object",
      "defaultValue": {
        "tag1": "tag-value-1",
        "tag2": "tag-value-2"
      },
      "metadata": {
        "description": "Adds tags for the key-value resources. It's optional"
      }
    }
  },
  "resources": [
    {
      "type": "Microsoft.AppConfiguration/configurationStores",
      "apiVersion": "2021-10-01-preview",
      "name": "[parameters('configStoreName')]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "standard"
      }
    },
    {
      "copy": {
        "name": "configStoreKeyValue",
        "count": "[length(parameters('keyValueNames'))]"
      },
      "type": "Microsoft.AppConfiguration/configurationStores/keyValues",
      "apiVersion": "2021-10-01-preview",
      "name": "[format('{0}/{1}', parameters('configStoreName'), parameters('keyValueNames')[copyIndex()])]",
      "properties": {
        "value": "[parameters('keyValueValues')[copyIndex()]]",
        "contentType": "[parameters('contentType')]",
        "tags": "[parameters('tags')]"
      },
      "dependsOn": [
        "[resourceId('Microsoft.AppConfiguration/configurationStores', parameters('configStoreName'))]"
      ]
    }
  ],
  "outputs": {
    "reference_key_value_value": {
      "type": "string",
      "value": "[reference(resourceId('Microsoft.AppConfiguration/configurationStores/keyValues', parameters('configStoreName'), parameters('keyValueNames')[0])).value]"
    },
    "reference_key_value_object": {
      "type": "object",
      "value": "[reference(resourceId('Microsoft.AppConfiguration/configurationStores/keyValues', parameters('configStoreName'), parameters('keyValueNames')[1]), '2021-10-01-preview', 'full')]"
    }
  }
}

Nel modello sono definite due risorse di Azure:

Microsoft.AppConfiguration/configurationStores: crea un archivio di Configurazione app.
Microsoft.AppConfiguration/configurationStores/keyValues: crea una coppia chiave-valore all'interno dell'archivio di Configurazione app.

Suggerimento

Il nome della risorsa keyValues è una combinazione di chiave ed etichetta. La chiave e l'etichetta sono unite dal delimitatore $. L'etichetta è facoltativa. Nell'esempio precedente la risorsa keyValues denominata myKey crea una coppia chiave-valore senza etichetta.

La codifica percentuale, nota anche come codifica URL, consente di includere nelle chiavi o nelle etichette caratteri non consentiti nei nomi delle risorse del modello di Resource Manager. Neanche % è un carattere consentito, quindi al suo posto viene usato ~. Per codificare correttamente un nome, seguire questa procedura:

Applicare la codifica URL
Sostituire ~ con ~7E
Sostituire % con ~

Ad esempio, per creare una coppia chiave-valore con il nome della chiave AppName:DbEndpoint e il nome dell'etichetta Test, il nome della risorsa dovrà essere AppName~3ADbEndpoint$Test.

Nota

Configurazione app consente l'accesso ai dati di coppie chiave-valore tramite un collegamento privato dalla rete virtuale. Per impostazione predefinita, quando la funzionalità è abilitata, tutte le richieste per i dati di Configurazione app sulla rete pubblica vengono negate. Poiché il modello di Resource Manager viene eseguito all'esterno della rete virtuale, l'accesso ai dati da un modello di questo tipo non è consentito. Per consentire l'accesso ai dati da un modello di Resource Manager quando si usa un collegamento privato, è possibile abilitare l'accesso alla rete pubblica usando il comando dell'interfaccia della riga di comando di Azure seguente. È importante considerare le implicazioni che l'abilitazione dell'accesso alla rete pubblica ha sulla sicurezza in questo scenario.

az appconfig update -g MyResourceGroup -n MyAppConfiguration --enable-public-network true

Distribuire il modello

Selezionare l'immagine seguente per accedere ad Azure e aprire un modello. Il modello crea un archivio di Configurazione app con due coppie chiave-valore al suo interno.

È anche possibile distribuire il modello con il cmdlet di PowerShell seguente. Le coppie chiave-valore saranno incluse nell'output della console di PowerShell.

$projectName = Read-Host -Prompt "Enter a project name that is used for generating resource names"
$location = Read-Host -Prompt "Enter the location (i.e. centralus)"
$templateUri = "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.appconfiguration/app-configuration-store-kv/azuredeploy.json"

$resourceGroupName = "${projectName}rg"

New-AzResourceGroup -Name $resourceGroupName -Location "$location"
New-AzResourceGroupDeployment -ResourceGroupName $resourceGroupName -TemplateUri $templateUri

Read-Host -Prompt "Press [ENTER] to continue ..."

Esaminare le risorse distribuite

Accedere al portale di Azure.
Nella casella di ricerca del portale di Azure digitare Configurazione app. Selezionare Configurazione app nell'elenco.
Selezionare la risorsa di Configurazione app appena creata.
In Operazioni fare clic su Esplora configurazioni.
Verificare che esistano due coppie chiave-valore.

Pulire le risorse

Quando non sono più necessari, eliminare il gruppo di risorse, l'archivio di Configurazione app e tutte le risorse correlate. Se si prevede di usare l'archivio di Configurazione app in futuro, è possibile evitare di eliminarlo. Se non si intende continuare a usare l'archivio, eliminare tutte le risorse create con questa guida di avvio rapido eseguendo il cmdlet seguente:

$resourceGroupName = Read-Host -Prompt "Enter the Resource Group name"
Remove-AzResourceGroup -Name $resourceGroupName
Write-Host "Press [ENTER] to continue..."

Passaggi successivi

Per informazioni sull'aggiunta del flag di funzionalità e del riferimento di Key Vault a un archivio Configurazione app, vedere gli esempi di modelli di Resource Manager seguenti.