Functions untuk digunakan dengan Azure Blueprints

  • Artikel

Penting

Pada 11 Juli 2026, Cetak Biru (Pratinjau) tidak akan digunakan lagi. Migrasikan definisi dan penugasan cetak biru yang ada ke Spesifikasi Templat dan Tumpukan Penyebaran. Artefak cetak biru akan dikonversi ke templat ARM JSON atau file Bicep yang digunakan untuk menentukan tumpukan penyebaran. Untuk mempelajari cara menulis artefak sebagai sumber daya ARM, lihat:

Azure Blueprints menyediakan fungsi membuat definisi cetak biru lebih dinamis. Fungsi ini digunakan dengan definisi cetak biru dan artefak cetak biru. Artefak Azure Resource Manager Template (template ARM) mendukung penggunaan penuh fungsi Resource Manager selain mendapatkan nilai dinamis melalui parameter cetak biru.

Fungsi berikut didukung:

artefak

artifacts(artifactName)

Mengembalikan objek properti yang diisi dengan output artefak cetak biru tersebut.

Catatan

Fungsi artifacts() ini tidak dapat digunakan dari dalam Template ARM. Fungsi ini hanya dapat digunakan dalam definisi cetak biru JSON atau dalam artefak JSON saat mengelola cetak biru dengan Azure PowerShell atau REST API sebagai bagian dari Blueprints-as-code.

Parameter

Parameter Diperlukan Jenis Deskripsi
artifactName Ya string Nama artefak cetak biru.

Nilai yang ditampilkan

Objek properti output. Properti output tergantung pada jenis artefak cetak biru yang direferensikan. Semua jenis mengikuti format:

{
  "outputs": {collectionOfOutputProperties}
}

Artefak penugasan kebijakan

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

Artefak templat ARM

Properti output objek yang ditampilkan didefinisikan dalam templat ARM dan ditampilkan oleh penyebaran.

Artefak penugasan peran

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

Contoh

Artefak template ARM dengan ID myTemplateArtifact yang berisi properti output sampel berikut:

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

Beberapa contoh pengambilan data dari sampel myTemplateArtifact adalah:

Ekspresi Jenis Nilai
[artifacts("myTemplateArtifact").outputs.myArray] Array ["first", "second"]
[artifacts("myTemplateArtifact").outputs.myArray[0]] String "pertama"
[artifacts("myTemplateArtifact").outputs.myString] String "nilai string saya"
[artifacts("myTemplateArtifact").outputs.myObject] Objek { "myproperty": "nilai saya", "anotherProperty": true }
[artifacts("myTemplateArtifact").outputs.myObject.myProperty] String "nilai saya"
[artifacts("myTemplateArtifact").outputs.myObject.anotherProperty] Bool True

concat

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

Menggabungkan beberapa nilai string dan menampilkan string yang digabungkan.

Parameter

Parameter Diperlukan Jenis Deskripsi
string1 Ya string Nilai pertama untuk perangkaian.
argumen tambahan Tidak string Nilai tambahan dalam urutan berurutan untuk perangkaian

Nilai yang ditampilkan

Serangkaian nilai yang digabungkan.

Keterangan

Fungsi Azure Blueprints berbeda dari fungsi template ARM karena hanya berfungsi dengan untai.

Contoh

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

parameter

parameters(parameterName)

Menampilkan nilai parameter cetak biru. Nama parameter yang ditentukan harus didefinisikan dalam definisi cetak biru atau dalam artefak cetak biru.

Parameter

Parameter Diperlukan Jenis Deskripsi
parameterName Ya string Nama parameter yang akan ditampilkan.

Nilai yang ditampilkan

Nilai cetak biru atau parameter artefak cetak biru yang ditentukan.

Keterangan

Fungsi Azure Blueprints berbeda dari fungsi template ARM karena hanya berfungsi dengan parameter cetak biru.

Contoh

Tentukan parameter principalIds dalam definisi cetak biru:

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

Kemudian gunakan principalIds sebagai argumen untuk parameters() dalam artefak cetak biru:

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

resourceGroup

resourceGroup()

Menampilkan objek yang mewakili grup sumber daya saat ini.

Nilai kembali

Objek yang ditampilkan dalam format berikut:

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

Keterangan

Fungsi Azure Blueprints berbeda dari fungsi templat ARM. Fungsi resourceGroup() tidak dapat digunakan dalam artefak tingkat langganan atau definisi cetak biru. Ini hanya dapat digunakan dalam artefak cetak biru yang merupakan bagian dari artefak grup sumber daya.

Penggunaan umum fungsi resourceGroup() adalah untuk membuat sumber daya di lokasi yang sama dengan artefak grup sumber daya.

Contoh

Untuk menggunakan lokasi grup sumber daya, atur definisi cetak biru atau selama penugasan, sebagai lokasi artefak lain, deklarasikan objek tempat penampung grup sumber daya dalam definisi cetak biru Anda. Dalam contoh ini, NetworkingPlaceholder adalah nama tempat penampung grup sumber daya.

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

Kemudian gunakan fungsi resourceGroup() dalam konteks artefak cetak biru yang menargetkan objek tempat penampung grup sumber daya. Dalam contoh ini, artefak template digunakan ke dalam grup sumber daya NetworkingPlaceholder dan menyediakan parameter resourceLocation dinamis diisi dengan lokasi grup sumber daya NetworkingPlaceholder ke template. Lokasi grup sumber daya NetworkingPlaceholder dapat didefinisikan secara statis pada definisi cetak biru atau didefinisikan secara dinamis selama penugasan. Dalam kedua kasus, artefak template disediakan informasi itu sebagai parameter dan menggunakannya untuk menyebarkan sumber daya ke lokasi yang benar.

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

resourceGroups

resourceGroups(placeholderName)

Menampilkan objek yang menunjukkan artefak grup sumber daya yang ditentukan. Tidak seperti resourceGroup(), yang membutuhkan konteks artefak, fungsi ini digunakan untuk mendapatkan properti tempat penampung grup sumber daya tertentu ketika tidak dalam konteks grup sumber daya tersebut.

Parameter

Parameter Diperlukan Jenis Deskripsi
placeholderName Ya string Nama tempat penampung artefak grup sumber daya untuk ditampilkan.

Nilai yang ditampilkan

Objek yang ditampilkan dalam format berikut:

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

Contoh

Untuk menggunakan lokasi grup sumber daya, atur definisi cetak biru atau selama penugasan, sebagai lokasi artefak lain, deklarasikan objek tempat penampung grup sumber daya dalam definisi cetak biru Anda. Dalam contoh ini, NetworkingPlaceholder adalah nama tempat penampung grup sumber daya.

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

Kemudian gunakan fungsi resourceGroups() dari konteks artefak cetak biru apa pun untuk mendapatkan referensi ke objek tempat penampung grup sumber daya. Dalam contoh ini, artefak template digunakan di luar grup sumber daya NetworkingPlaceholder dan menyediakan parameter artifactLocation yang secara dinamis diisi dengan lokasi grup sumber daya NetworkingPlaceholder ke template. Lokasi grup sumber daya NetworkingPlaceholder dapat didefinisikan secara statis pada definisi cetak biru atau didefinisikan secara dinamis selama penugasan. Dalam kedua kasus, artefak template disediakan informasi itu sebagai parameter dan menggunakannya untuk menyebarkan sumber daya ke lokasi yang benar.

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

langganan

subscription()

Menampilkan detail tentang langganan untuk penetapan cetak biru saat ini.

Nilai yang ditampilkan

Objek yang ditampilkan dalam format berikut:

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

Contoh

Gunakan nama tampilan langganan dan fungsi concat() untuk membuat konvensi penamaan yang diteruskan sebagai resourceName parameter ke artefak template.

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

Langkah berikutnya