Fonctions à utiliser avec Azure Blueprints

Azure Blueprints fournit des fonctions rendant la définition d’un blueprint plus dynamique. Ces fonctions sont destinées à être utilisées avec les définitions de plans et les artefacts de plans. Un artefact Azure Resource Manager Template (template ARM) permet l’utilisation complète des fonctions Resource Manager en plus d’obtenir une valeur dynamique via un paramètre blueprint.

Les fonctions suivantes sont prises en charge :

• Artefacts
• concat
• Paramètres
• resourceGroup
• resourceGroups
• subscription

artifacts

artifacts(artifactName)

Retourne un objet de propriétés rempli de ces artefacts de blueprint.

Parameters

Valeur renvoyée

Un objet de propriétés de sortie. Les propriétés des sorties dépendent du type d’artefact de plan référencé. Tous les types suivent le format :

{
  "outputs": {collectionOfOutputProperties}
}

Artefact d’attribution de politique

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

Artefact du modèle ARM

Les propriétés de sortie de l’objet retourné sont définies dans le modèle ARM et retournées par le déploiement.

Artefact d’attribution de rôle

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

Exemple

Un artefact de modèle ARM avec l’ID myTemplateArtifact contenant la propriété de sortie d’exemple suivante :

{
    "$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
            }
        }
    }
}

Voici quelques exemples de récupération de données à partir de l’exemple myTemplateArtifact :

concat

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

Combine plusieurs valeurs de chaîne et retourne la chaîne concaténée.

Parameters

Valeur renvoyée

Une chaîne de valeurs concaténées.

Remarks

La fonction Azure Blueprints diffère de la fonction modèle ARM en ce qu’elle ne fonctionne qu’avec des chaînes de caractères.

Exemple

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

parameters

parameters(parameterName)

Retourne une valeur de paramètre blueprint. Le nom du paramètre spécifié doit être défini dans la définition du plan ou dans les artefacts du plan.

Parameters

Valeur renvoyée

La valeur du paramètre de blueprint ou d’artefact de blueprint spécifié.

Remarks

La fonction Azure Blueprints diffère de la fonction modèle ARM en ce qu’elle ne fonctionne qu’avec les paramètres du blueprint.

Exemple

Définissez les principaux Ids des paramètres dans la définition du blueprint :

{
    "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"
                }
            }
        },
        ...
    }
}

Ensuite, utilisez principalIds comme argument dans parameters() un artefact de blueprint :

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

groupe de ressources

resourceGroup()

Retourne un objet qui représente le groupe de ressources courant.

Valeur renvoyée

L’objet retourné est dans le format suivant :

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

Remarks

La fonction Azure Blueprints diffère de la fonction modèle ARM. La resourceGroup() fonction ne peut pas être utilisée dans un artefact de niveau d’abonnement ni dans la définition du blueprint. Il ne peut être utilisé que dans les artefacts de plans faisant partie d’un artefact de groupe de ressources.

Une utilisation courante de la resourceGroup() fonction est de créer des ressources au même emplacement que l’artefact du groupe de ressources.

Exemple

Pour utiliser l’emplacement du groupe de ressources, défini soit dans la définition du blueprint, soit lors de l’affectation, comme emplacement pour un autre artefact, déclarez un objet de placement de groupe de ressources dans votre définition de blueprint. Dans cet exemple, NetworkingPlaceholder est le nom du placeholder du groupe de ressources.

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

Ensuite, utilisez la resourceGroup() fonction dans le contexte d’un artefact de blueprint qui cible un objet de placement de groupe de ressources. Dans cet exemple, l’artefact du modèle est déployé dans le groupe de ressources NetworkingPlaceholder et fournit dynamiquement le paramètre resourceLocation avec la localisation du groupe de ressources NetworkingPlaceholder au modèle. L’emplacement du groupe de ressources NetworkingPlaceholder aurait pu être défini statiquement sur la définition du blueprint ou dynamiquement lors de l’affectation. Dans tous les cas, l’artefact du modèle reçoit cette information comme paramètre et l’utilise pour déployer les ressources au bon emplacement.

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

resourceGroups

resourceGroups(placeholderName)

Retourne un objet qui représente l’artefact du groupe de ressources spécifié. Contrairement à , qui nécessite le contexte de l’artefact, cette fonction est utilisée pour obtenir les propriétés d’un groupe de ressources spécifique comme resourceGroup()placeholder lorsqu’elle n’est pas dans le contexte de ce groupe.

Parameters

Valeur renvoyée

L’objet retourné est dans le format suivant :

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

Exemple

Pour utiliser l’emplacement du groupe de ressources, défini soit dans la définition du blueprint, soit lors de l’affectation, comme emplacement pour un autre artefact, déclarez un objet de placement de groupe de ressources dans votre définition de blueprint. Dans cet exemple, NetworkingPlaceholder est le nom du placeholder du groupe de ressources.

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

Ensuite, utilisez la resourceGroups() fonction du contexte de n’importe quel artefact de blueprint pour obtenir une référence à l’objet de placement du groupe de ressources. Dans cet exemple, l’artefact du modèle est déployé en dehors du groupe de ressources NetworkingPlaceholder et fournit dynamiquement l’artefactLocation du paramètre avec la localisation du groupe de ressources NetworkingPlaceholder au modèle. L’emplacement du groupe de ressources NetworkingPlaceholder aurait pu être défini statiquement sur la définition du blueprint ou dynamiquement lors de l’affectation. Dans tous les cas, l’artefact du modèle reçoit cette information comme paramètre et l’utilise pour déployer les ressources au bon emplacement.

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

Abonnement

subscription()

Retour des détails concernant l’abonnement pour l’assignation actuelle du blueprint.

Valeur renvoyée

L’objet retourné est dans le format suivant :

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

Exemple

Utilisez le nom d’affichage de l’abonnement et la concat() fonction pour créer une convention de nommage passée comme paramètre resourceName à l’artefact du modèle.

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

Étapes suivantes

• Découvrez le cycle de vie du blueprint.
• Découvrez comment utiliser des paramètres statiques et dynamiques.
• Apprendre à personnaliser l’ordre de séquencement des blueprints.
• Découvrez comment utiliser le verrouillage des ressources blueprint.
• Découvrez comment mettre à jour les affectations existantes.
• Résoudre les problèmes durant l’affectation d’un blueprint en suivant les étapes de dépannage général.