Membuat cetak biru dinamis melalui parameter

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:

• Kebijakan
• RBAC
• Penyebaran

Cetak biru yang sepenuhnya ditentukan dengan berbagai artefak seperti grup sumber daya, templat Azure Resource Manager (templat ARM), kebijakan, atau penetapan peran, menawarkan pembuatan cepat dan pembuatan objek yang konsisten dalam Azure. Untuk memungkinkan penggunaan fleksibel pola dan kontainer desain yang dapat digunakan kembali ini, Azure Blueprints mendukung parameter. Parameter ini menciptakan fleksibilitas, baik selama definisi maupun penugasan, untuk mengubah properti pada artefak yang digunakan oleh cetak biru.

Contoh sederhananya adalah artefak grup sumber daya. Saat grup sumber daya dibuat, grup memiliki dua nilai yang diperlukan yang harus disediakan: nama dan lokasi. Saat menambahkan grup sumber daya ke cetak biru Anda, jika parameter tidak ada, Anda akan menentukan nama dan lokasi tersebut untuk setiap penggunaan cetak biru. Pengulangan ini akan menyebabkan setiap penggunaan cetak biru untuk membuat artefak dalam kelompok sumber daya yang sama. Sumber daya di dalam grup sumber daya itu akan menjadi diduplikasi dan menyebabkan konflik.

Catatan

Ini bukan masalah untuk dua cetak biru yang berbeda untuk menyertakan grup sumber daya dengan nama yang sama. Jika grup sumber daya yang disertakan dalam cetak biru sudah ada, cetak biru terus membuat artefak terkait dalam grup sumber daya tersebut. Ini dapat menyebabkan konflik karena dua sumber daya dengan nama dan tipe sumber daya yang sama tidak dapat berada dalam langganan.

Solusi untuk masalah ini adalah parameter. Azure Blueprints memungkinkan Anda menentukan nilai untuk setiap properti artefak selama penugasan langganan. Parameter memungkinkan untuk menggunakan kembali cetak biru yang membuat grup sumber daya dan sumber daya lain dalam satu langganan tanpa mengalami konflik.

Parameter cetak biru

Melalui REST API, parameter dapat dibuat pada cetak biru itu sendiri. Parameter ini berbeda dari parameter pada masing-masing artefak yang didukung. Ketika parameter dibuat pada cetak biru, parameter tersebut dapat digunakan oleh artefak dalam cetak biru itu. Contohnya mungkin berupa awalan untuk penamaan grup sumber daya. Artefak dapat menggunakan parameter cetak biru untuk membuat parameter "sebagian besar dinamis". Karena parameter juga dapat ditentukan selama penugasan, pola ini memungkinkan konsistensi yang dapat mematuhi aturan penamaan. Untuk langkah-langkah, lihat menyiapkan parameter statik - parameter tingkat cetak biru.

Menggunakan parameter secureString dan secureObject

Meskipun artefak template ARM mendukung parameter tipe secureString dan secureObject, Azure Blueprints mengharuskan masing-masing untuk terhubung dengan Azure Key Vault. Langkah keamanan ini mencegah praktik menyimpan rahasia yang tidak aman bersama dengan Blueprint dan mendorong pekerjaan dengan pola yang aman. Azure Blueprints mendukung langkah keamanan ini, mendeteksi dimasukkannya parameter aman dalam artefak template ARM. Layanan kemudian meminta selama penugasan untuk properti Key Vault berikut per parameter aman yang terdeteksi:

• ID sumber daya Key Vault
• Nama rahasia Key Vault
• Versi rahasia Key Vault

Jika penetapan cetak biru menggunakan identitas terkelola yang ditetapkan sistem, Key Vault yang direferensikan harus ada dalam langganan yang sama dengan yang ditetapkan oleh definisi cetak biru.

Jika penetapan cetak biru menggunakan identitas terkelola yang ditetapkan pengguna, Key Vault yang direferensikan mungkin ada dalam langganan terpusat. Identitas terkelola harus diberikan hak yang sesuai pada Key Vault sebelum penetapan cetak biru.

Penting

Dalam kedua kasus, Key Vault harus Mengaktifkan akses ke Azure Resource Manager untuk penyebaran templat yang dikonfigurasi pada halaman Kebijakan akses. Untuk petunjuk arah tentang cara mengaktifkan fitur ini, lihat Key Vault - Aktifkan penyebaran templat.

Untuk informasi selengkapnya tentang Azure Key Vault, lihat Gambaran Umum Key Vault.

Jenis parameter

Parameter statik

Nilai parameter yang ditentukan dalam definisi cetak biru disebut parameter statik, karena setiap penggunaan cetak biru akan menyebarkan artefak menggunakan nilai statik tersebut. Dalam contoh grup sumber daya, meskipun tidak masuk akal untuk nama grup sumber daya, mungkin masuk akal untuk lokasi tersebut. Kemudian, setiap penugasan cetak biru akan membuat grup sumber daya, apa pun namanya selama penugasan, di lokasi yang sama. Fleksibilitas ini memungkinkan Anda untuk selektif dalam apa yang Anda definisikan sebagai diperlukan vs apa yang dapat diubah selama penugasan.

Mengatur parameter statik di portal

1. Pilih Semua layanan di panel sebelah kiri. Cari dan pilih Cetak Biru.

2. Pilih Definisi Cetak Biru dari halaman di sebelah kiri.

3. Pilih cetak biru yang sudah ada lalu pilih Edit cetak biru ATAU pilih + Buat cetak biru dan lengkapi informasi pada tab Dasar.

4. Pilih Berikutnya: Artefak ATAU pilih tab Artefak.

5. Artefak ditambahkan ke cetak biru yang memiliki opsi parameter menampilkan parameter X dari Y yang diisi di kolom Parameter. Pilih baris artefak untuk mengedit parameter artefak.

   

6. Halaman Edit Artefak menampilkan opsi nilai yang sesuai dengan artefak yang dipilih. Setiap parameter pada artefak memiliki judul, kotak nilai, dan kotak centang. Atur kotak ke tidak dicentang untuk menjadikannya parameter statik. Dalam contoh berikut, hanya Lokasi yang merupakan parameter statik karena tidak dicentang dan Nama Grup Sumber Daya dicentang.

   

Mengatur parameter statik dari REST API

Di setiap URI REST API, ada variabel yang digunakan yang perlu Anda ganti dengan nilai Anda sendiri:

• {YourMG} - Ganti dengan nama grup manajemen Anda
• {subscriptionId} - Mengganti dengan ID Langganan Anda

Parameter tingkat cetak biru

Saat membuat cetak biru melalui REST API, Anda dapat membuat parameter cetak biru. Untuk melakukannya, gunakan format isi dan URI REST API berikut:

• URI REST API

  PUT https://management.azure.com/providers/Microsoft.Management/managementGroups/{YourMG}/providers/Microsoft.Blueprint/blueprints/MyBlueprint?api-version=2018-11-01-preview
  

• Isi Permintaan

  {
      "properties": {
          "description": "This blueprint has blueprint level parameters.",
          "targetScope": "subscription",
          "parameters": {
              "owners": {
                  "type": "array",
                  "metadata": {
                      "description": "List of AAD object IDs that is assigned Owner role at the resource group"
                  }
              }
          },
          "resourceGroups": {
              "storageRG": {
                  "description": "Contains the resource template deployment and a role assignment."
              }
          }
      }
  }
  

Setelah parameter tingkat cetak biru dibuat,parameter tersebut dapat digunakan pada artefak yang ditambahkan ke cetak biru itu. Contoh REST API berikut membuat artefak penetapan peran pada cetak biru dan menggunakan parameter tingkat cetak biru.

• URI REST API

  PUT https://management.azure.com/providers/Microsoft.Management/managementGroups/{YourMG}/providers/Microsoft.Blueprint/blueprints/MyBlueprint/artifacts/roleOwner?api-version=2018-11-01-preview
  

• Isi Permintaan

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

Dalam contoh ini, properti principalIds menggunakan parameter tingkat cetak biru pemilik dengan menggunakan nilai [parameters('owners')]. Menetapkan parameter pada artefak menggunakan parameter tingkat cetak biru masih merupakan contoh parameter statik. Parameter tingkat cetak biru tidak dapat diatur selama penetapan cetak biru dan akan menjadi nilai yang sama pada setiap penugasan.

Parameter tingkat artefak

Membuat parameter statik pada artefak serupa, tetapi mengambil nilai lurus alih-alih menggunakan fungsi parameters(). Contoh berikut membuat dua parameter statik, tagName dan tagValue. Nilai pada masing-masing parameter secara langsung disediakan dan tidak menggunakan panggilan fungsi.

• URI REST API

  PUT https://management.azure.com/providers/Microsoft.Management/managementGroups/{YourMG}/providers/Microsoft.Blueprint/blueprints/MyBlueprint/artifacts/policyStorageTags?api-version=2018-11-01-preview
  

• Isi Permintaan

  {
      "kind": "policyAssignment",
      "properties": {
          "description": "Apply storage tag and the parameter also used by the template to resource groups",
          "policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/49c88fc8-6fd1-46fd-a676-f12d1d3a4c71",
          "parameters": {
              "tagName": {
                  "value": "StorageType"
              },
              "tagValue": {
                  "value": "Premium_LRS"
              }
          }
      }
  }
  

Parameter dinamis

Kebalikan dari parameter statik adalah parameter dinamis. Parameter ini tidak didefinisikan pada cetak biru, tetapi didefinisikan selama setiap penugasan cetak biru. Dalam contoh grup sumber daya, penggunaan parameter dinamis masuk akal untuk nama grup sumber daya. Ini memberikan nama yang berbeda untuk setiap penugasan cetak biru. Untuk daftar fungsi cetak biru, lihat referensi fungsi cetak biru.

Mengatur parameter dinamis di portal

1. Pilih Semua layanan di panel sebelah kiri. Cari dan pilih Cetak Biru.

2. Pilih Definisi Cetak Biru dari halaman di sebelah kiri.

3. Klik kanan pada cetak biru yang ingin Anda tetapkan. Pilih Tetapkan cetak biru ATAU pilih cetak biru yang ingin Anda tetapkan, lalu gunakan tombol Tetapkan cetak biru.

4. Pada halaman Tetapkan cetak biru, temukan bagian Parameter artefak. Setiap artefak dengan setidaknya satu parameter dinamis menampilkan artefak dan opsi konfigurasi. Berikan nilai yang diperlukan ke parameter sebelum menetapkan cetak biru. Dalam contoh berikut, Name adalah parameter dinamis yang harus didefinisikan untuk menyelesaikan penetapan cetak biru.

   

Mengatur parameter dinamis dari REST API

Pengaturan parameter dinamis selama penugasan dilakukan dengan memasukkan nilai secara langsung. Alih-alih menggunakan fungsi, seperti parameters(), nilai yang disediakan adalah string yang sesuai. Artefak untuk grup sumber daya didefinisikan dengan "template name", name, dan properti lokasi. Semua parameter lain untuk artefak yang disertakan ditentukan di bagian parameter dengan pasangan kunci <nama> dan nilai. Jika cetak biru dikonfigurasi untuk parameter dinamis yang tidak disediakan selama penugasan, penugasan akan gagal.

• URI REST API

  PUT https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Blueprint/blueprintAssignments/assignMyBlueprint?api-version=2018-11-01-preview
  

• Isi Permintaan

  {
      "properties": {
          "blueprintId": "/providers/Microsoft.Management/managementGroups/{YourMG}  /providers/Microsoft.Blueprint/blueprints/MyBlueprint",
          "resourceGroups": {
              "storageRG": {
                  "name": "StorageAccount",
                  "location": "eastus2"
              }
          },
          "parameters": {
              "storageAccountType": {
                  "value": "Standard_GRS"
              },
              "tagName": {
                  "value": "CostCenter"
              },
              "tagValue": {
                  "value": "ContosoIT"
              },
              "contributors": {
                  "value": [
                      "7be2f100-3af5-4c15-bcb7-27ee43784a1f",
                      "38833b56-194d-420b-90ce-cff578296714"
                  ]
                },
              "owners": {
                  "value": [
                      "44254d2b-a0c7-405f-959c-f829ee31c2e7",
                      "316deb5f-7187-4512-9dd4-21e7798b0ef9"
                  ]
              }
          }
      },
      "identity": {
          "type": "systemAssigned"
      },
      "location": "westus"
  }
  

Langkah berikutnya

• Lihat daftar fungsi cetak biru.
• Pelajari tentang siklus hidup cetak biru.
• Pelajari cara menyesuaikan urutan rangkaian cetak biru.
• Cari tahu cara memanfaatkan penguncian sumber daya cetak biru.
• Pelajari cara memperbarui penugasan yang ada.
• Mengatasi masalah selama penetapan cetak biru dengan pemecahan masalah umum.