Funzioni da usare con Azure Blueprints

  • Articolo

Importante

Il 11 luglio 2026 Blueprints (anteprima) sarà deprecato. Eseguire la migrazione delle definizioni e delle assegnazioni di progetto esistenti a specifiche di modello e stack di distribuzione. Gli artefatti del progetto devono essere convertiti in modelli JSON ARM o file Bicep usati per definire gli stack di distribuzione. Per informazioni su come creare un artefatto come risorsa arm, vedere:

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

artifacts(artifactName)

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

Nota

La artifacts() funzione non può essere usata dall'interno di un modello di Resource Manager. La funzione può essere usata solo nel codice JSON della definizione di progetto o nell'artefatto JSON quando si gestisce il progetto con Azure PowerShell o l'API REST come parte di Blueprints come codice.

Parametri

Parametro Obbligatoria Tipo Descrizione
artifactName Sì string Nome di un artefatto del progetto.

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:

Expression Type valore
[artifacts("myTemplateArtifact").outputs.myArray] Array ["first", "second"]
[artifacts("myTemplateArtifact").outputs.myArray[0]] string "first"
[artifacts("myTemplateArtifact").outputs.myString] string "my string value"
[artifacts("myTemplateArtifact").outputs.myObject] Oggetto { "myproperty": "my value", "anotherProperty": true }
[artifacts("myTemplateArtifact").outputs.myObject.myProperty] string "my value"
[artifacts("myTemplateArtifact").outputs.myObject.anotherProperty] Bool True

concat

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

Combina più valori stringa e restituisce la stringa concatenata.

Parametri

Parametro Obbligatoria Tipo Descrizione
string1 Sì string Il primo valore per la concatenazione.
argomenti aggiuntivi No string Altri valori in ordine sequenziale per la concatenazione

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

Parametro Obbligatoria Tipo Descrizione
parameterName Sì string Nome del parametro da restituire.

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

Parametro Obbligatoria Tipo Descrizione
placeholderName Sì string Nome del segnaposto dell'artefatto del gruppo di risorse da restituire.

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