Quickstart: Menentukan dan menetapkan blueprint Azure dengan REST API

Artikel
09/07/2023

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.
Daftarkan penyedia sumber Microsoft.Blueprint. Untuk petunjuk, lihat Penyedia dan jenis sumber daya.

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.
Buka https://shell.azure.com, atau pilih tombol Luncurkan Cloud Shell untuk membuka Cloud Shell di browser Anda.
Pilih tombol Cloud Shell pada bilah menu di kanan atas di portal Microsoft Azure.

Untuk menggunakan Azure Cloud Shell:

Mulai Cloud Shell.
Pilih tombol Salin pada blok kode (atau blok perintah) untuk menyalin kode atau perintah.
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.
Pilih Masukkan untuk menjalankan kode atau perintah.

Mulai dengan REST API

Jika Anda tidak terbiasa dengan REST API, mulailah dengan meninjau Referensi Azure REST API, khususnya bagian tentang URI permintaan dan badan permintaan. Panduan mulai cepat ini menggunakan konsep ini untuk memberikan arahan untuk bekerja dengan Azure Blueprints, dan mengasumsikan pengetahuan tentangnya. Alat seperti ARMClient dapat menangani pembuatan secara otomatis, dan direkomendasikan untuk pemula.

Untuk spesifikasi Azure Blueprints, lihat REST API Azure Blueprints.

REST API dan PowerShell

Jika Anda belum memiliki alat untuk melakukan panggilan REST API, sebaiknya gunakan PowerShell untuk petunjuk ini. Berikut ini adalah contoh header untuk melakukan autentikasi dengan Azure. Buat header autentikasi, yang terkadang disebut token pembawa, dan berikan REST API URI untuk tersambung dengan parameter apa pun atau Request Body:

# Log in first with Connect-AzAccount if not using Cloud Shell

$azContext = Get-AzContext
$azProfile = [Microsoft.Azure.Commands.Common.Authentication.Abstractions.AzureRmProfileProvider]::Instance.Profile
$profileClient = New-Object -TypeName Microsoft.Azure.Commands.ResourceManager.Common.RMProfileClient -ArgumentList ($azProfile)
$token = $profileClient.AcquireAccessToken($azContext.Subscription.TenantId)
$authHeader = @{
    'Content-Type'='application/json'
    'Authorization'='Bearer ' + $token.AccessToken
}

# Invoke the REST API
$restUri = 'https://management.azure.com/subscriptions/{subscriptionId}?api-version=2020-01-01'
$response = Invoke-RestMethod -Uri $restUri -Method Get -Headers $authHeader

Ganti {subscriptionId} di variabel $restUri sebelumnya untuk mendapatkan informasi tentang langganan Anda. Variabel $response menyimpan hasil Invoke-RestMethod cmdlet, yang dapat Anda urai dengan cmdlet seperti ConvertFrom-Json. Jika titik akhir layanan REST API mengharapkan Request Body, sediakan variabel berformat JSON ke parameter -Body dari Invoke-RestMethod.

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 REST API, objek blueprint dibuat terlebih dahulu. Untuk setiap artefak yang akan ditambahkan yang memiliki parameter, Anda menentukan parameter terlebih dahulu pada blueprint awal.

Di setiap REST API URI, ganti variabel berikut dengan nilai Anda sendiri:

{YourMG} - Mengganti dengan ID grup manajemen Anda.
{subscriptionId} - Mengganti dengan ID langganan Anda.

Catatan

Anda juga dapat membuat blueprint di tingkat langganan. Untuk informasi lebih lanjut, lihat membuat blueprint di contoh langganan.

Membuat objek cetak biru awal. Request Body Mencakup properti tentang blueprint, grup sumber daya apa pun 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.

REST API URI

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

Tambahkan penetapan peran di tingkat langganan. Request Body 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.
- REST API URI
```
PUT https://management.azure.com/providers/Microsoft.Management/managementGroups/{YourMG}/providers/Microsoft.Blueprint/blueprints/MyBlueprint/artifacts/roleContributor?api-version=2018-11-01-preview
```
- Isi Permintaan
```
{
    "kind": "roleAssignment",
    "properties": {
        "roleDefinitionId": "/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c",
        "principalIds": "[parameters('contributors')]"
    }
}
```

Menambahkan penugasan kebijakan di langganan. Request Body 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.

REST API URI

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

Isi Permintaan

{
    "kind": "policyAssignment",
    "properties": {
        "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')]"
            }
        }
    }
}

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.

REST API URI

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": "[parameters('storageAccountType')]"
            }
        }
    }
}

Menambahkan pola dasar di bawah grup sumber daya. Request Body Untuk pola dasar ARM mencakup komponen JSON normal dari pola dasar, dan mendefinisikan grup sumber daya target dengan properties.resourceGroup. Templat juga menggunakan storageAccountTypekembali parameter cetak biru , tagName, dan tagValue dengan meneruskan masing-masing ke templat. Parameter blueprint tersedia untuk pola dasar dengan mendefinisikan properties.parameters, dan di dalam template JSON pasangan kunci-nilai digunakan untuk memasukkan nilai. Nama parameter blueprint dan pola dasar bisa sama, tetapi berbeda di sini untuk mengilustrasikan bagaimana masing-masing berpindah dari blueprint ke artefak pola dasar.

REST API URI

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

Isi Permintaan

{
    "kind": "template",
    "properties": {
        "template": {
            "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
            "contentVersion": "1.0.0.0",
            "parameters": {
                "storageAccountTypeFromBP": {
                    "type": "string",
                    "defaultValue": "Standard_LRS",
                    "allowedValues": [
                        "Standard_LRS",
                        "Standard_GRS",
                        "Standard_ZRS",
                        "Premium_LRS"
                    ],
                    "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": "[resourceGroups('storageRG').location]",
                "sku": {
                    "name": "[parameters('storageAccountTypeFromBP')]"
                },
                "kind": "Storage",
                "properties": {}
            }],
            "outputs": {
                "storageAccountSku": {
                    "type": "string",
                    "value": "[variables('storageAccountName')]"
                }
            }
        },
        "resourceGroup": "storageRG",
        "parameters": {
            "storageAccountTypeFromBP": {
                "value": "[parameters('storageAccountType')]"
            },
            "tagNameFromBP": {
                "value": "[parameters('tagName')]"
            },
            "tagValueFromBP": {
                "value": "[parameters('tagValue')]"
            }
        }
    }
}

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.

REST API URI

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')]"
    }
}

Menerbitkan cetak biru

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

REST API URI

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

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 REST API, blueprint tersebut 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. Request Body menentukan blueprint yang akan ditetapkan, dan memberikan nama dan lokasi ke grup sumber daya apa pun dalam definisi blueprint. Request Body juga menyediakan semua parameter yang ditentukan pada blueprint dan digunakan oleh satu atau beberapa artefak yang dilampirkan.

Di setiap REST API URI, ganti variabel berikut dengan nilai Anda sendiri:

{tenantId} - Ganti dengan ID penyewa Anda.
{YourMG} - Mengganti dengan ID grup manajemen Anda.
{subscriptionId} - Mengganti dengan ID langganan Anda.

Berikan prinsip layanan Azure Blueprints Owner pada langganan target. AppId Bersifat statik (f71766dc-90d9-4b7d-bd9d-4499c4331c3f), tetapi ID utama layanan bervariasi menurut penyewa. Gunakan REST API berikut untuk meminta detail penyewa Anda. Ini menggunakan API Azure Active Directory Graph, yang memiliki otorisasi berbeda.
- REST API URI
```
GET https://graph.windows.net/{tenantId}/servicePrincipals?api-version=1.6&$filter=appId eq 'f71766dc-90d9-4b7d-bd9d-4499c4331c3f'
```

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 Request Body untuk pengguna, grup, atau prinsipal layanan Anda sendiri.

REST API URI

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

Identitas terkelola yang ditetapkan pengguna

Penetapan cetak biru juga dapat menggunakan identitas terkelola yang ditetapkan pengguna. Dalam hal ini, identity bagian isi permintaan berubah sebagai berikut. Ganti {yourRG} dan {userIdentity} berturut-turut dengan nama grup sumber daya Anda dan nama identitas terkelola yang ditetapkan pengguna Anda.
```
"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

Menghapus penugasan cetak biru

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 operasi REST API berikut:

REST API URI

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

Menghapus cetak biru

Untuk menghapus cetak biru itu sendiri, gunakan operasi REST API berikut:

REST API URI

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

Langkah berikutnya

Dalam mulai cepat, Anda membuat, menetapkan, dan menghapus blueprint dengan REST API. Untuk mempelajari Azure Blueprints lebih lanjut, lanjutkan ke artikel siklus hidup cetak biru.

Pelajari siklus hidup cetak biru

Quickstart: Menentukan dan menetapkan blueprint Azure dengan REST API

Prasyarat

Azure Cloud Shell

Mulai dengan REST API

REST API dan PowerShell

Buat cetak biru

Menerbitkan cetak biru

Menetapkan cetak biru

Membersihkan sumber daya

Menghapus penugasan cetak biru

Menghapus cetak biru

Langkah berikutnya

Sumber Daya Tambahan: