Mulai cepat: Menentukan dan menetapkan blueprint Azure dengan PowerShell

  • 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:

Dalam tutorial ini, Anda mempelajari cara menggunakan Azure Blueprints untuk melakukan beberapa tugas umum yang terkait dengan membuat, menerbitkan, dan menetapkan cetak biru dalam organisasi Anda. Keterampilan ini membantu Anda menentukan pola umum untuk mengembangkan konfigurasi yang dapat digunakan kembali dan disebarkan dengan cepat, berdasarkan templat, kebijakan, dan keamanan Azure Resource Manager (ARM).

Prasyarat

  • Jika Anda tidak memiliki langganan Azure, buat akun gratis sebelum Anda memulai.
  • Jika belum diinstal, ikuti instruksi di modul Tambahkan Az.Blueprint untuk menginstal dan memvalidasi modul Az.Blueprint dari Galeri PowerShell.
  • Jika Anda belum menggunakan Azure Blueprints sebelumnya, daftarkan penyedia sumber daya melalui Azure PowerShell dengan Register-AzResourceProvider -ProviderNamespace Microsoft.Blueprint.

Azure Cloud Shell

Azure meng-hosting Azure Cloud Shell, lingkungan shell interaktif yang dapat Anda gunakan melalui browser. Anda dapat menggunakan Bash atau PowerShell dengan Cloud Shell untuk bekerja dengan layanan Azure. Anda dapat menggunakan perintah Cloud Shell yang telah diinstal sebelumnya untuk menjalankan kode dalam artikel ini tanpa harus menginstal apa-apa di lingkungan lokal Anda.

Untuk memulai Azure Cloud Shell:

Opsi Contoh/Tautan
Pilih Coba di pojok kanan atas blok kode atau perintah. Memilih Coba tidak otomatis menyalin kode atau perintah ke Cloud Shell. Screenshot that shows an example of Try It for Azure Cloud Shell.
Buka https://shell.azure.com, atau pilih tombol Luncurkan Cloud Shell untuk membuka Cloud Shell di browser Anda. Button to launch Azure Cloud Shell.
Pilih tombol Cloud Shell pada bilah menu di kanan atas di portal Microsoft Azure. Screenshot that shows the Cloud Shell button in the Azure portal

Untuk menggunakan Azure Cloud Shell:

  1. Mulai Cloud Shell.

  2. Pilih tombol Salin pada blok kode (atau blok perintah) untuk menyalin kode atau perintah.

  3. Tempel kode atau perintah ke dalam sesi Cloud Shell dengan memilih Ctrl+Shift+V di Windows dan Linux, atau dengan memilih Cmd+Shift+V di macOS.

  4. Pilih Masukkan untuk menjalankan kode atau perintah.

Buat cetak biru

Langkah pertama dalam mendefinisikan pola standar untuk kepatuhan adalah menyusun cetak biru dari sumber daya yang tersedia. Mari buat cetak biru bernama MyBlueprint untuk mengonfigurasi penetapan peran dan kebijakan untuk langganan. Kemudian Anda menambahkan grup sumber daya, pola dasar ARM, dan penetapan peran pada grup sumber daya.

Catatan

Saat Anda menggunakan PowerShell, objek blueprint dibuat terlebih dahulu. Untuk setiap artefak yang akan ditambahkan yang memiliki parameter, Anda menentukan parameter terlebih dahulu pada blueprint awal.

  1. Membuat objek cetak biru awal. Parameter BlueprintFile mengambil file JSON yang menyertakan properti tentang blueprint, semua grup sumber daya yang akan dibuat, dan semua parameter tingkat blueprint. Anda mengatur parameter selama penugasan, dan parameter tersebut digunakan oleh artefak yang Anda tambahkan di langkah selanjutnya.

    • File JSON - blueprint.json

      {
    "properties": {
        "description": "This blueprint sets tag policy and role assignment on the subscription, creates a ResourceGroup, and deploys a resource template and role assignment to that ResourceGroup.",
        "targetScope": "subscription",
        "parameters": {
            "storageAccountType": {
                "type": "string",
                "defaultValue": "Standard_LRS",
                "allowedValues": [
                    "Standard_LRS",
                    "Standard_GRS",
                    "Standard_ZRS",
                    "Premium_LRS"
                ],
                "metadata": {
                    "displayName": "storage account type.",
                    "description": null
                }
            },
            "tagName": {
                "type": "string",
                "metadata": {
                    "displayName": "The name of the tag to provide the policy assignment.",
                    "description": null
                }
            },
            "tagValue": {
                "type": "string",
                "metadata": {
                    "displayName": "The value of the tag to provide the policy assignment.",
                    "description": null
                }
            },
            "contributors": {
                "type": "array",
                "metadata": {
                    "description": "List of AAD object IDs that is assigned Contributor role at the subscription",
                    "strongType": "PrincipalId"
                }
            },
            "owners": {
                "type": "array",
                "metadata": {
                    "description": "List of AAD object IDs that is assigned Owner role at the resource group",
                    "strongType": "PrincipalId"
                }
            }
        },
        "resourceGroups": {
            "storageRG": {
                "description": "Contains the resource template deployment and a role assignment."
            }
        }
    }
}

    • Perintah PowerShell

      # Login first with Connect-AzAccount if not using Cloud Shell

# Get a reference to the new blueprint object, we'll use it in subsequent steps
$blueprint = New-AzBlueprint -Name 'MyBlueprint' -BlueprintFile .\blueprint.json

      Catatan

      Gunakan nama file blueprint.json saat Anda membuat definisi blueprint Anda secara terprogram. Nama file ini digunakan saat Anda memanggil Import-AzBlueprintWithArtifact.

      Objek cetak biru dibuat di langganan default secara default. Untuk menentukan grup pengelolaan, gunakan parameter ManagementGroupId. Untuk menentukan langganan, gunakan parameter SubscriptionId.

  2. Tambahkan penetapan peran di tingkat langganan. ArtifactFile Mendefinisikan jenis artefak, properti disejajarkan dengan pengidentifikasi definisi peran, dan identitas utama diteruskan sebagai array nilai. Dalam contoh berikut, identitas utama yang mendapatkan peran tertentu dikonfigurasi ke parameter yang diatur selama penetapan cetak biru. Contoh ini menggunakan Contributor peran bawaan, dengan GUID b24988ac-6180-42a0-ab88-20f7382dd24c.

    • File JSON - \artifacts\roleContributor.json

      {
    "kind": "roleAssignment",
    "properties": {
        "roleDefinitionId": "/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c",
        "principalIds": "[parameters('contributors')]"
    }
}

    • Perintah PowerShell

      # Use the reference to the new blueprint object from the previous steps
New-AzBlueprintArtifact -Blueprint $blueprint -Name 'roleContributor' -ArtifactFile .\artifacts\roleContributor.json

  3. Menambahkan penugasan kebijakan di langganan. ArtifactFile Mendefinisikan jenis artefak, properti yang disejajarkan dengan definisi kebijakan atau inisiatif, dan penetapan kebijakan dikonfigurasi untuk menggunakan parameter blueprint yang ditentukan selama penetapan blueprint. Contoh ini menggunakan Apply tag and its default value to resource groups kebijakan bawaan, dengan GUID 49c88fc8-6fd1-46fd-a676-f12d1d3a4c71.

    • File JSON - \artifacts\policyTags.json

      {
    "kind": "policyAssignment",
    "properties": {
        "displayName": "Apply tag and its default value to resource groups",
        "description": "Apply tag and its default value to resource groups",
        "policyDefinitionId": "/providers/Microsoft.Authorization/policyDefinitions/49c88fc8-6fd1-46fd-a676-f12d1d3a4c71",
        "parameters": {
            "tagName": {
                "value": "[parameters('tagName')]"
            },
            "tagValue": {
                "value": "[parameters('tagValue')]"
            }
        }
    }
}

    • Perintah PowerShell

      # Use the reference to the new blueprint object from the previous steps
New-AzBlueprintArtifact -Blueprint $blueprint -Name 'policyTags' -ArtifactFile .\artifacts\policyTags.json

  4. Menambahkan penugasan kebijakan lain untuk tag penyimpanan (dengan menggunakan kembali storageAccountType_ parameter) di langganan. Artefak penugasan kebijakan tambahan ini menunjukkan bahwa parameter yang ditentukan pada cetak biru dapat digunakan oleh lebih dari satu artefak. Dalam contoh, Anda menggunakan storageAccountType untuk menetapkan tag pada grup sumber daya. Nilai ini menyediakan informasi tentang akun penyimpanan yang Anda buat di langkah berikutnya. Contoh ini menggunakan Apply tag and its default value to resource groups kebijakan bawaan, dengan GUID 49c88fc8-6fd1-46fd-a676-f12d1d3a4c71.

    • File JSON - \artifacts\policyStorageTags.json

      {
    "kind": "policyAssignment",
    "properties": {
        "displayName": "Apply storage tag to resource group",
        "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": "[parameters('storageAccountType')]"
            }
        }
    }
}

    • Perintah PowerShell

      # Use the reference to the new blueprint object from the previous steps
New-AzBlueprintArtifact -Blueprint $blueprint -Name 'policyStorageTags' -ArtifactFile .\artifacts\policyStorageTags.json

  5. Menambahkan pola dasar di bawah grup sumber daya. TemplateFile untuk templat ARM menyertakan komponen JSON normal templat. Templat juga menggunakan storageAccountTypekembali parameter cetak biru , tagName, dan tagValue dengan meneruskan masing-masing ke templat. Parameter blueprint tersedia untuk pola dasar dengan menggunakan parameter TemplateParameterFile, dan di dalam pola dasar JSON pasangan kunci-nilai digunakan untuk memasukkan nilai. Nama parameter blueprint dan pola dasar mungkin sama.

    • File pola dasar JSON ARM - \artifacts\templateStorage.json

      {
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "storageAccountTypeFromBP": {
            "type": "string",
            "metadata": {
                "description": "Storage Account type"
            }
        },
        "tagNameFromBP": {
            "type": "string",
            "defaultValue": "NotSet",
            "metadata": {
                "description": "Tag name from blueprint"
            }
        },
        "tagValueFromBP": {
            "type": "string",
            "defaultValue": "NotSet",
            "metadata": {
                "description": "Tag value from blueprint"
            }
        }
    },
    "variables": {
        "storageAccountName": "[concat(uniquestring(resourceGroup().id), 'standardsa')]"
    },
    "resources": [{
        "type": "Microsoft.Storage/storageAccounts",
        "name": "[variables('storageAccountName')]",
        "apiVersion": "2016-01-01",
        "tags": {
            "[parameters('tagNameFromBP')]": "[parameters('tagValueFromBP')]"
        },
        "location": "[resourceGroup().location]",
        "sku": {
            "name": "[parameters('storageAccountTypeFromBP')]"
        },
        "kind": "Storage",
        "properties": {}
    }],
    "outputs": {
        "storageAccountSku": {
            "type": "string",
            "value": "[variables('storageAccountName')]"
        }
    }
}

    • File parameter pola dasar JSON ARM - \artifacts\templateStorageParams.json

      {
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "storageAccountTypeFromBP": {
            "value": "[parameters('storageAccountType')]"
        },
        "tagNameFromBP": {
            "value": "[parameters('tagName')]"
        },
        "tagValueFromBP": {
            "value": "[parameters('tagValue')]"
        }
    }
}

    • Perintah PowerShell

      # Use the reference to the new blueprint object from the previous steps
New-AzBlueprintArtifact -Blueprint $blueprint -Type TemplateArtifact -Name 'templateStorage' -TemplateFile .\artifacts\templateStorage.json -TemplateParameterFile .\artifacts\templateStorageParams.json -ResourceGroupName storageRG

  6. Menambahkan penetapan peran di bawah grup sumber daya. Mirip dengan entri penetapan peran sebelumnya, contoh berikut menggunakan pengidentifikasi definisi untuk peran Owner, dan memberikannya parameter yang berbeda dari blueprint. Contoh ini menggunakan Owner peran bawaan, dengan GUID 8e3af657-a8ff-443c-a75c-2fe8c4bcb635.

    • File JSON - \artifacts\roleOwner.json

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

    • Perintah PowerShell

      # Use the reference to the new blueprint object from the previous steps
New-AzBlueprintArtifact -Blueprint $blueprint -Name 'roleOwner' -ArtifactFile .\artifacts\roleOwner.json

Menerbitkan cetak biru

Sekarang setelah Anda menambahkan artefak ke blueprint, saatnya untuk menerbitkannya. Penerbitan membuat blueprint tersedia untuk ditetapkan ke langganan.

# Use the reference to the new blueprint object from the previous steps
Publish-AzBlueprint -Blueprint $blueprint -Version '{BlueprintVersion}'

Nilai untuk {BlueprintVersion} adalah rangkaian huruf, angka, dan tanda hubung (tanpa spasi atau karakter khusus lainnya). Panjang maksimum adalah 20 karakter. Gunakan sesuatu yang unik dan informatif, seperti v20180622-135541.

Menetapkan cetak biru

Setelah Anda menerbitkan blueprint dengan menggunakan PowerShell, itu dapat ditetapkan ke langganan. Tetapkan cetak biru yang Anda buat pada salah satu langganan di bawah hierarki grup manajemen Anda. Jika cetak biru disimpan ke langganan, cetak biru hanya dapat ditetapkan ke langganan tersebut. Parameter Blueprint menentukan cetak biru yang akan ditetapkan. Untuk menyediakan parameter name, location, identity, lock, dan blueprint, gunakan parameter PowerShell yang cocok pada cmdlet New-AzBlueprintAssignment, atau sediakan di file JSON parameter AssignmentFile.

  1. Jalankan penyebaran cetak biru dengan menetapkannya ke langganan. Karena parameter contributors dan owners memerlukan array objectIds prinsipal untuk diberikan penetapan peran, gunakan Azure Active Directory Graph API untuk mengumpulkan objectIds untuk digunakan di AssignmentFile untuk pengguna, grup, atau prinsipal layanan Anda sendiri.

    • File JSON - blueprintAssignment.json

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

    • Perintah PowerShell

      # Use the reference to the new blueprint object from the previous steps
New-AzBlueprintAssignment -Blueprint $blueprint -Name 'assignMyBlueprint' -AssignmentFile .\blueprintAssignment.json

    • Identitas terkelola yang ditetapkan pengguna

      Penetapan cetak biru juga dapat menggunakan identitas terkelola yang ditetapkan pengguna. Dalam hal ini, identity bagian dari file penugasan JSON berubah sebagai berikut. Ganti {tenantId}, {subscriptionId}, {yourRG}, dan {userIdentity} dengan masing-masing ID penyewa, ID langganan, nama grup sumber daya, dan nama identitas terkelola yang ditetapkan pengguna.

      "identity": {
    "type": "userAssigned",
    "tenantId": "{tenantId}",
    "userAssignedIdentities": {
        "/subscriptions/{subscriptionId}/resourceGroups/{yourRG}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{userIdentity}": {}
    }
},

      Identitas terkelola yang ditetapkan pengguna dapat berada dalam langganan dan grup sumber daya apa pun yang izinnya dimiliki oleh pengguna yang menetapkan blueprint.

      Penting

      Azure Blueprints tidak mengelola identitas terkelola yang ditetapkan pengguna. Pengguna bertanggung jawab untuk menetapkan peran dan izin yang memadai, atau penugasan blueprint akan gagal.

Membersihkan sumber daya

Anda dapat menghapus cetak biru dari langganan. Penghapusan sering dilakukan ketika sumber daya artefak tidak lagi diperlukan. Ketika cetak biru dihapus, artefak yang ditetapkan sebagai bagian dari cetak biru tersebut akan tertinggal. Untuk menghapus penetapan cetak biru, gunakan cmdlet Remove-AzBlueprintAssignment:

assignMyBlueprint

Remove-AzBlueprintAssignment -Name 'assignMyBlueprint'

Langkah berikutnya

Dalam mylai cepat ini, Anda membuat, menetapkan, dan menghapus blue print dengan PowerShell. Untuk mempelajari Azure Blueprints lebih lanjut, lanjutkan ke artikel siklus hidup cetak biru.

Pelajari siklus hidup cetak biru