Funzioni da usare con Azure Blueprints

Azure Blueprints offre funzioni che rendono più dinamica la definizione di un progetto. Queste funzioni sono destinate all'uso con definizioni di progetto e artefatti del progetto. Un artefatto modello di Azure Resource Manager supporta l'uso completo delle funzioni di Resource Manager oltre a ottenere un valore dinamico tramite un parametro di progetto.

Sono supportate le funzioni seguenti:

• artifacts
• concat
• parameters
• resourceGroup
• resourceGroups
• sottoscrizione

artifacts

artifacts(artifactName)

Restituisce un oggetto di proprietà popolato con gli output degli artefatti del progetto.

Parametri

Valore restituito

Oggetto delle proprietà di output. Le proprietà output proprietà dipendono dal tipo di elemento del progetto a cui si fa riferimento. Tutti i tipi seguono il formato:

{
  "outputs": {collectionOfOutputProperties}
}

Artefatto dell'assegnazione dei criteri

{
    "outputs": {
        "policyAssignmentId": "{resourceId-of-policy-assignment}",
        "policyAssignmentName": "{name-of-policy-assignment}",
        "policyDefinitionId": "{resourceId-of-policy-definition}",
    }
}

Artefatto del modello di Resource Manager

Le proprietà di output dell'oggetto restituito vengono definite all'interno del modello di Resource Manager e restituite dalla distribuzione.

Artefatto dell'assegnazione di ruolo

{
    "outputs": {
        "roleAssignmentId": "{resourceId-of-role-assignment}",
        "roleDefinitionId": "{resourceId-of-role-definition}",
        "principalId": "{principalId-role-is-being-assigned-to}",
    }
}

Esempio

Elemento del modello di Resource Manager con ID myTemplateArtifact contenente la proprietà di output di esempio seguente:

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    ...
    "outputs": {
        "myArray": {
            "type": "array",
            "value": ["first", "second"]
        },
        "myString": {
            "type": "string",
            "value": "my string value"
        },
        "myObject": {
            "type": "object",
            "value": {
                "myProperty": "my value",
                "anotherProperty": true
            }
        }
    }
}

Di seguito sono riportati alcuni esempi di recupero dei dati dal campione myTemplateArtifact:

concat

concat(string1, string2, string3, ...)

Combina più valori stringa e restituisce la stringa concatenata.

Parametri

Valore restituito

Stringa di valori concatenati.

Osservazioni

La funzione Azure Blueprints è diversa dalla funzione del modello di Resource Manager in quanto funziona solo con le stringhe.

Esempio

concat(parameters('organizationName'), '-vm')

parametri

parameters(parameterName)

Restituisce un valore del parametro del progetto. Il nome del parametro specificato deve essere definito nel progetto o negli artefatti del progetto.

Parametri

Valore restituito

Il valore del parametro di progetto o dell'artefatto del progetto specificato.

Osservazioni

La funzione Azure Blueprints è diversa dalla funzione del modello di Resource Manager in quanto funziona solo con i parametri del progetto.

Esempio

Definire il parametro principalIds nella definizione del progetto:

{
    "type": "Microsoft.Blueprint/blueprints",
    "properties": {
        ...
        "parameters": {
            "principalIds": {
                "type": "array",
                "metadata": {
                    "displayName": "Principal IDs",
                    "description": "This is a blueprint parameter that any artifact can reference. We'll display these descriptions for you in the info bubble. Supply principal IDs for the users,groups, or service principals for the Azure role assignment.",
                    "strongType": "PrincipalId"
                }
            }
        },
        ...
    }
}

Usare quindi principalIds come argomento per parameters() in un artefatto del progetto:

{
    "type": "Microsoft.Blueprint/blueprints/artifacts",
    "kind": "roleAssignment",
    ...
    "properties": {
        "roleDefinitionId": "/providers/Microsoft.Authorization/roleDefinitions/8e3af657-a8ff-443c-a75c-2fe8c4bcb635",
        "principalIds": "[parameters('principalIds')]",
        ...
    }
}

resourceGroup

resourceGroup()

Restituisce un oggetto che rappresenta il gruppo di risorse corrente.

Valore restituito

L'oggetto restituito è nel formato seguente:

{
  "name": "{resourceGroupName}",
  "location": "{resourceGroupLocation}",
}

Osservazioni

La funzione Azure Blueprints è diversa dalla funzione del modello di Resource Manager. Non è possibile usare la funzione resourceGroup() in un artefatto a livello di sottoscrizione o nella definizione del progetto. Può essere usata solo negli artefatti del progetto che fanno parte di un artefatto del gruppo di risorse.

Un utilizzo comune della funzione resourceGroup() consiste nel creare risorse nello stesso percorso dell'artefatto del gruppo di risorse.

Esempio

Per usare il percorso del gruppo di risorse, impostato nella definizione del progetto o durante l'assegnazione, come percorso di un altro artefatto, dichiarare un oggetto segnaposto del gruppo di risorse nella definizione del progetto. In questo esempio NetworkingPlaceholder è il nome del segnaposto del gruppo di risorse.

{
    "type": "Microsoft.Blueprint/blueprints",
    "properties": {
        ...
        "resourceGroups": {
            "NetworkingPlaceholder": {
                "location": "eastus"
            }
        }
    }
}

Usare quindi la funzione resourceGroup() nel contesto di un artefatto del progetto del progetto che fa riferimento a un oggetto segnaposto del gruppo di risorse. In questo esempio, l'elemento del modello viene distribuito all'interno del gruppo di risorse NetworkingPlaceholder e fornisce al modello il parametro resourceLocation popolato dinamicamente con il percorso del gruppo di risorse NetworkingPlaceholder. Il percorso del gruppo di risorse NetworkingPlaceholder può essere stato definito in modo statico nella definizione del progetto o in modo dinamico durante l'assegnazione. In entrambi i casi, l'artefatto del modello fornisce tale dato come parametro e lo usa per distribuire le risorse nel percorso corretto.

{
  "type": "Microsoft.Blueprint/blueprints/artifacts",
  "kind": "template",
  "properties": {
      "template": {
        ...
      },
      "resourceGroup": "NetworkingPlaceholder",
      ...
      "parameters": {
        "resourceLocation": {
          "value": "[resourceGroup().location]"
        }
      }
  }
}

resourceGroups

resourceGroups(placeholderName)

Restituisce un oggetto che rappresenta l'artefatto del gruppo di risorse specificato. A differenza di resourceGroup(), che richiede il contesto dell'artefatto, questa funzione viene usata per ottenere le proprietà di un segnaposto del gruppo di risorse specifico quando non si trova nel contesto di tale gruppo di risorse.

Parametri

Valore restituito

L'oggetto restituito è nel formato seguente:

{
  "name": "{resourceGroupName}",
  "location": "{resourceGroupLocation}",
}

Esempio

Per usare il percorso del gruppo di risorse, impostato nella definizione del progetto o durante l'assegnazione, come percorso di un altro artefatto, dichiarare un oggetto segnaposto del gruppo di risorse nella definizione del progetto. In questo esempio NetworkingPlaceholder è il nome del segnaposto del gruppo di risorse.

{
    "type": "Microsoft.Blueprint/blueprints",
    "properties": {
        ...
        "resourceGroups": {
            "NetworkingPlaceholder": {
                "location": "eastus"
            }
        }
    }
}

Usare quindi la funzione resourceGroups() dal contesto dell'artefatto di un progetto per ottenere un riferimento a un oggetto segnaposto del gruppo di risorse. In questo esempio, l'elemento del modello viene distribuito all'esterno del gruppo di risorse NetworkingPlaceholder e fornisce al modello il parametro artifactLocation popolato dinamicamente con il percorso del gruppo di risorse NetworkingPlaceholder. Il percorso del gruppo di risorse NetworkingPlaceholder può essere stato definito in modo statico nella definizione del progetto o in modo dinamico durante l'assegnazione. In entrambi i casi, l'artefatto del modello fornisce tale dato come parametro e lo usa per distribuire le risorse nel percorso corretto.

{
  "kind": "template",
  "properties": {
      "template": {
          ...
      },
      ...
      "parameters": {
        "artifactLocation": {
          "value": "[resourceGroups('NetworkingPlaceholder').location]"
        }
      }
  },
  "type": "Microsoft.Blueprint/blueprints/artifacts",
  "name": "myTemplate"
}

sottoscrizione

subscription()

Restituisce i dettagli sulla sottoscrizione per l'assegnazione del progetto corrente.

Valore restituito

L'oggetto restituito è nel formato seguente:

{
    "id": "/subscriptions/{subscriptionId}",
    "subscriptionId": "{subscriptionId}",
    "tenantId": "{tenantId}",
    "displayName": "{name-of-subscription}"
}

Esempio

Usare il nome visualizzato della sottoscrizione e la funzione concat() per creare una convenzione di denominazione passata come parametro resourceName all'artefatto del modello.

{
  "kind": "template",
  "properties": {
      "template": {
          ...
      },
      ...
      "parameters": {
        "resourceName": {
          "value": "[concat(subscription().displayName, '-vm')]"
        }
      }
  },
  "type": "Microsoft.Blueprint/blueprints/artifacts",
  "name": "myTemplate"
}

Passaggi successivi

• Informazioni sul ciclo di vita del progetto.
• Informazioni su come usare parametri statici e dinamici.
• Informazioni su come personalizzare l'ordine di sequenziazione del progetto.
• Informazioni su come usare in modo ottimale il blocco delle risorse del progetto.
• Informazioni su come aggiornare assegnazioni esistenti.
• Risolvere i problemi durante l'assegnazione di un progetto con la risoluzione generale dei problemi.