Funktionen zur Verwendung mit Azure Blueprints

Azure Blueprints bietet Funktionen, die eine Blueprint-Definition dynamischer machen. Diese Funktionen sind für die Verwendung mit Blaupausendefinitionen und Bauplan-Artefakten. Ein Artefakt der Azure Resource Manager Template (ARM-Vorlage) unterstützt zusätzlich die volle Nutzung von Resource Manager-Funktionen sowie das Erhalten eines dynamischen Werts durch einen Blueprint-Parameter.

Die folgenden Funktionen werden unterstützt:

• artefakte
• concat
• parameters
• resourceGroup
• resource-Gruppen
• subscription

artifacts

artifacts(artifactName)

Gibt ein Objekt mit Eigenschaften zurück, die mit diesen Blueprint-Artefakten gefüllt sind.

Parameter

Zurückgegebener Wert

Ein Objekt mit Ausgabeeigenschaften. Die Eigenschaften der Ausgaben hängen vom Typ des verwendeten Blaupauseartefakts ab. Alle Typen folgen dem Format:

{
  "outputs": {collectionOfOutputProperties}
}

Artefakt der Richtlinienzuweisung

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

ARTEFAKT der ARM-Vorlage

Die Ausgabeeigenschaften des zurückgegebenen Objekts werden innerhalb der ARM-Vorlage definiert und von der Bereitstellung zurückgegeben.

Artefakt zur Rollenzuweisung

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

Example

Ein ARM-Template-Artefakt mit der ID myTemplateArtifact enthält folgende Beispielausgabe-Eigenschaft:

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

Einige Beispiele für das Abrufen von Daten aus der myTemplateArtifact-Probe sind:

concat

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

Kombiniert mehrere Zeichenkettenwerte und gibt die verkettete Zeichenkette zurück.

Parameter

Zurückgegebener Wert

Eine Kette von verketteten Werten.

Hinweise

Die Azure Blueprints-Funktion unterscheidet sich von der ARM-Template-Funktion dadurch, dass sie nur mit Strings funktioniert.

Example

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

parameters

parameters(parameterName)

Gibt einen Blueprint-Parameter zurück. Der angegebene Parametername muss in der Blueprint-Definition oder in Blueprint-Artefakten definiert sein.

Parameter

Zurückgegebener Wert

Der Wert des angegebenen Blueprint- oder Blueprint-Artefakt-Parameters.

Hinweise

Die Azure Blueprints-Funktion unterscheidet sich von der ARM-Vorlagenfunktion dadurch, dass sie nur mit Blueprint-Parametern funktioniert.

Example

Definieren Sie Parameter principalIds in der Blueprint-Definition:

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

Dann verwenden Sie principalIds als Argument für parameters() ein Bauplan-Artefakt:

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

Ressourcengruppe

resourceGroup()

Gibt ein Objekt zurück, das die aktuelle Ressourcengruppe repräsentiert.

Zurückgegebener Wert

Das zurückgegebene Objekt liegt im folgenden Format vor:

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

Hinweise

Die Azure Blueprints-Funktion unterscheidet sich von der ARM-Vorlagenfunktion. Die resourceGroup() Funktion kann nicht in einem Abonnement-Artefakt oder der Blueprint-Definition verwendet werden. Es kann nur in Bauplan-Artefakten verwendet werden, die Teil eines Ressourcengruppen-Artefakts sind.

Eine gängige Verwendung der resourceGroup() Funktion ist es, Ressourcen am selben Ort wie das Artefakt der Ressourcengruppe zu erstellen.

Example

Um den Standort der Ressourcengruppe, entweder in der Blueprint-Definition oder während der Zuweisung, als Standort für ein anderes Artefakt zu verwenden, deklarieren Sie in Ihrer Blueprint-Definition ein Ressourcengruppen-Platzhalterobjekt. In diesem Beispiel ist NetworkingPlaceholder der Name des Ressourcengruppen-Platzhalters.

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

Dann verwenden Sie die resourceGroup() Funktion im Kontext eines Blueprint-Artefakts, das auf ein Ressourcengruppen-Platzhalterobjekt abzielt. In diesem Beispiel wird das Vorlagenartefakt in der NetworkingPlaceholder-Ressourcengruppe bereitgestellt und stellt dem Parameter resourceLocation dynamisch mit dem Standort der NetworkingPlaceholder-Ressourcengruppe zur Vorlage bereit. Der Standort der NetworkingPlaceholder-Ressourcengruppe könnte statisch auf der Blueprint-Definition definiert oder dynamisch während der Zuweisung definiert worden sein. In beiden Fällen erhält das Template-Artefakt diese Information als Parameter und nutzt sie, um die Ressourcen an den richtigen Ort zu bringen.

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

resourceGroups

resourceGroups(placeholderName)

Gibt ein Objekt zurück, das das angegebene Ressourcengruppen-Artefakt darstellt. Im Gegensatz zu resourceGroup(), der den Kontext des Artefakts benötigt, wird diese Funktion verwendet, um die Eigenschaften einer bestimmten Ressourcengruppen-Platzhalterfunktion zu erhalten, wenn sie sich nicht im Kontext dieser Ressourcengruppe befindet.

Parameter

Zurückgegebener Wert

Das zurückgegebene Objekt liegt im folgenden Format vor:

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

Example

Um den Standort der Ressourcengruppe, entweder in der Blueprint-Definition oder während der Zuweisung, als Standort für ein anderes Artefakt zu verwenden, deklarieren Sie in Ihrer Blueprint-Definition ein Ressourcengruppen-Platzhalterobjekt. In diesem Beispiel ist NetworkingPlaceholder der Name des Ressourcengruppen-Platzhalters.

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

Dann verwenden Sie die resourceGroups() Funktion aus dem Kontext eines beliebigen Blueprint-Artefakts, um eine Referenz auf das Ressourcengruppen-Platzhalterobjekt zu erhalten. In diesem Beispiel wird das Vorlagenartefakt außerhalb der NetworkingPlaceholder-Ressourcengruppe bereitgestellt und stellt dem Parameter artifactLocation, der dynamisch mit dem Standort der NetworkingPlaceholder-Ressourcengruppe ausgefüllt wird, zur Vorlage bereit. Der Standort der NetworkingPlaceholder-Ressourcengruppe könnte statisch auf der Blueprint-Definition definiert oder dynamisch während der Zuweisung definiert worden sein. In beiden Fällen erhält das Template-Artefakt diese Information als Parameter und nutzt sie, um die Ressourcen an den richtigen Ort zu bringen.

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

subscription

subscription()

Gibt Details zum Abonnement für die aktuelle Blueprint-Zuweisung zurück.

Zurückgegebener Wert

Das zurückgegebene Objekt liegt im folgenden Format vor:

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

Example

Verwenden Sie den Anzeigenamen des Abonnements und die Funktion, concat() um eine Namenskonvention zu erstellen, die als Parameter resourceName an das Vorlagenartefakt weitergegeben wird.

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

Nächste Schritte

• Erfahren Sie mehr über den Blueprint-Lebenszyklus.
• Verstehen, wie man statische und dynamische Parameter verwendet.
• Hier erfahren Sie, wie Sie die Reihenfolge der Blueprint-Sequenzierung anpassen.
• Erfahren Sie, wie Sie die Sperrung von Blueprintressourcen verwenden.
• Lernen Sie, wie Sie vorhandene Zuweisungen aktualisieren.
• Beheben Sie Probleme bei der Zuweisung eines Entwurfsplans mithilfe der allgemeinen Problembehandlung.