AzAPI 提供者是 Azure ARM REST API 之上的精簡層。 它可讓您使用任何 API 版本來管理任何 Azure 資源類型，讓您能夠利用 Azure 內的最新功能。 AzAPI 是一流的提供者，其設計目的是要單獨或與 AzureRM 提供者搭配使用。
使用 AzAPI 提供者的優點
AzAPI 提供者具有下列優點：
- 支援所有 Azure 控制平面服務：
- 預覽服務和功能
- 所有 API 版本
- Terraform 狀態檔案的完整性
- 屬性和值被保存到狀態中
- 不依賴 Swagger
- 一般且一致的 Azure 驗證
- 內建前置檢查驗證
- 精細控制基礎設施開發
- 強大的 VS Code 擴充功能
資源
若要讓您管理所有 Azure 資源和功能，而不需要更新，AzAPI 提供者包含下列一般資源：
| 資源名稱 | 描述 |
|---|---|
azapi_resource |
用來全面管理任何 Azure 資源（控制平面 API），提供完整的 CRUD 功能。 範例使用案例： 新的預覽服務 新增至現有服務的新功能 目前未涵蓋的現有功能/服務 |
azapi_update_resource |
用來管理沒有完整 CRUD 的資源或部分資源 範例使用案例： 更新現有服務上的新屬性 更新預先建立的子資源 - 例如 DNS SOA 記錄。 |
azapi_resource_action |
用來在資源上執行單一作業，而不需管理資源的生命週期 範例使用案例： 關閉虛擬機 將秘密新增至 金鑰保存庫 |
azapi_data_plane_resource |
用來管理 Azure 數據平面資源的特定子集 範例使用案例： KeyVault 憑證聯繫人 Synapse 工作區資料庫 |
使用階層
整體而言，使用方式應遵循下列步驟：
- 建議您先在
azapi_resource中執行盡可能多的操作。 - 如果資源類型不存在於
azapi_resource，但落在azapi_data_plane_resource支援的其中一種類型之下，請改用該類型。 - 如果資源已存在於 AzureRM 中，或具有無法在
azapi_resource中存取的屬性，請使用azapi_update_resource來存取這些特定屬性。azapi_resource或azapi_data_plane_resource不支援的資源無法透過此資源更新。 - 如果您嘗試執行一項不基於 Azure CRUD 友好資源的操作，
azapi_resource_action雖然不如azapi_update_resource直接，但卻更靈活。
資源組態範例
下列代碼段會設定 AzureRM 提供者中目前不存在的資源：
resource "azapi_resource" "publicip" {
type = "Microsoft.Network/Customipprefixes@2021-03-01"
name = "exfullrange"
parent_id = azurerm_resource_group.example.id
location = "westus2"
body = {
properties = {
cidr = "10.0.0.0/24"
signedMessage = "Sample Message for WAN"
}
}
}
下列代碼段會從 AzureRM 設定現有資源的預覽屬性：
resource "azapi_update_resource" "test" {
type = "Microsoft.ContainerRegistry/registries@2020-11-01-preview"
resource_id = azurerm_container_registry.acr.id
body = {
properties = {
anonymousPullEnabled = var.bool_anonymous_pull
}
}
}
下列代碼段會在現有的 AzureRM 資源上設定資源動作：
resource "azapi_resource_action" "vm_shutdown" {
type = "Microsoft.Compute/virtualMachines@2023-07-01"
resource_id = azurerm_linux_virtual_machine.example.id
action = "powerOff”
}
下列代碼段會設定一個因為在數據平面上配置而在 AzureRM 提供者中目前不存在的資源。
resource "azapi_data_plane_resource" "dataset" {
type = "Microsoft.Synapse/workspaces/datasets@2020-12-01"
parent_id = trimprefix(data.azurerm_synapse_workspace.example.connectivity_endpoints.dev, "https://")
name = "example-dataset"
body = {
properties = {
type = "AzureBlob",
typeProperties = {
folderPath = {
value = "@dataset().MyFolderPath"
type = "Expression"
}
fileName = {
value = "@dataset().MyFileName"
type = "Expression"
}
format = {
type = "TextFormat"
}
}
parameters = {
MyFolderPath = {
type = "String"
}
MyFileName = {
type = "String"
}
}
}
}
}
預檢使用範例
由於 AzAPI 的內建預檢驗證，terraform plan 期間發生下列代碼段錯誤：
provider "azapi" {
enable_preflight = true
}
resource "azapi_resource" "vnet" {
type = "Microsoft.Network/virtualNetworks@2024-01-01"
parent_id = azapi_resource.resourceGroup.id
name = "example-vnet"
location = "westus"
body = {
properties = {
addressSpace = {
addressPrefixes = [
"10.0.0.0/160", # preflight will throw an error here
]
}
}
}
}
Preflight 檢查會隱藏在供應商標誌後面，但有助於在 plan 階段拋出錯誤。
數據源
AzAPI 提供者支援各種不同的實用數據源：
| 數據源名稱 | 描述 |
|---|---|
azapi_resource |
用來從任何 Azure 控制平面資源的 API 讀取資訊。 範例使用案例： 新的預覽服務 新增至現有服務的新功能 目前未涵蓋的現有功能/服務 |
azapi_client_config |
存取客戶端資訊，例如訂用帳戶標識碼和租使用者標識碼。 |
azapi_resource_action |
用來在資源上執行單一讀取作業，而不需管理資源的生命週期 範例使用案例： 列出鍵值 VM 的讀取狀態 |
azapi_data_plane_resource |
用來存取 Azure 數據平面資源的 特定子集 範例使用案例： KeyVault 憑證聯繫人 Synapse 工作區程式庫 |
azapi_resource_id |
存取資源的資源標識碼，並能夠輸出資訊，例如訂用帳戶標識碼、父標識碼、資源組名和資源名稱。 |
azapi_resource_list |
列出指定父資源標識碼下的所有資源。 範例使用案例： 訂用帳戶/資源群組底下的資源 虛擬網路下的子網 |
使用 AzAPI 提供者進行驗證
AzAPI 提供者會啟用與 AzureRM 提供者相同的驗證方法。 如需驗證選項的詳細資訊，請參閱 向 Azure 驗證 Terraform。
AzAPI 提供者的體驗和生命週期
本節說明一些可協助您使用 AzAPI 提供者的工具。
VS Code 延伸模組和語言伺服器
AzAPI VS Code 擴充功能提供豐富的撰寫體驗，具有下列優點：
- 列出所有可用的資源類型和 API 版本。
- 自動完成任何資源項目的允許屬性和值。
- 當將滑鼠停留在屬性欄上方時顯示提示。
- 語法驗證
- 使用程式代碼範例自動完成。
aztfmigrate 遷移工具
aztfmigrate 工具 的設計目的是協助在 AzAPI 與 AzureRM 提供者之間移轉現有的資源。
aztfmigrate 有兩種模式：規劃和移轉：
- 方案會顯示可移轉的 AzAPI 資源。
- 移轉過程會將 AzAPI 資源在 HCL 文件和狀態中轉換為 AzureRM 資源。
aztfmigrate 可確保在移轉之後，您的 Terraform 組態和狀態會與您的實際狀態一致。 完成移轉之後，您可以執行 terraform plan 來驗證狀態的更新，以查看沒有任何變更。
對基礎結構的細微控制
AzAPI 的其中一個主要優點是能夠微調您的設定，以符合正確的設計模式。 有數種方式可以執行此動作：
提供者功能
AzAPI （v2.0 和更新版本） 有大量 提供者函式：
| 函式名稱 | 描述 |
|---|---|
build_resource_id |
根據父標識碼、資源類型和資源名稱，建構 Azure 資源識別碼。 對於在特定範圍內建立最上層和巢狀資源的資源標識碼很有用。 |
extension_resource_id |
根據基底資源標識碼、資源類型和其他資源名稱，建構 Azure 擴充功能資源識別符。 |
management_group_resource_id |
根據管理組名、資源類型和資源名稱，建構 Azure 管理群組範圍資源識別符。 |
parse_resource_id |
此函式會採用 Azure 資源識別碼和資源類型，並將標識碼剖析成其個別元件，例如訂用帳戶標識碼、資源組名、提供者命名空間和其他元件。 |
resource_group_resource_id |
根據訂用帳戶標識碼、資源組名、資源類型和資源名稱，建構 Azure 資源群組範圍資源標識符。 |
subscription_resource_id |
根據訂用帳戶標識碼、資源類型和資源名稱，建構 Azure 訂用帳戶範圍資源識別碼。 |
tenant_resource_id |
根據資源類型和資源名稱，建構 Azure 租使用者範圍資源識別碼。 |
具有 retry 區塊的使用者定義可重試錯誤
AzAPI 提供者可以透過 retry 區塊來處理錯誤。 例如，如果資源可能遇到建立逾時問題，下列程式代碼區塊可能會有所幫助：
resource "azapi_resource" "example" {
# usual properties
retry {
interval_seconds = 5
randomization_factor = 0.5 # adds randomization to retry pattern
multiplier = 2 # if try fails, multiplies time between next try by this much
error_message_regex = ["ResourceNotFound"]
}
timeouts {
create = "10m"
}
資源取代的觸發因素
AzAPI 提供者可讓您設定資源取代的參數：
replace_triggers_external_values
如果值變更，則會取代資源。 例如，如果要修改 SKU 或區域變數，將會重新建立此資源：
resource "azapi_resource" "example" {
name = var.name
type = "Microsoft.Network/publicIPAddresses@2023-11-01"
parent_id = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/example"
body = properties = {
sku = var.sku
zones = var.zones
}
replace_triggers_external_values = [
var.sku,
var.zones,
]
}
這可以在廣泛的一組資源中運作，即在定義屬性變更時的策略指派。
replace_triggers_refs
如果參考的值變更，則會取代資源。 例如，如果 SKU 名稱或階層已修改，則會重新建立此資源：
resource "azapi_resource" "example" {
type = "Microsoft.Relay/namespaces@2021-11-01"
parent_id = azurerm_resource_group.example.id
name = "xxx"
location = "westus"
body = {
properties = {
}
sku = {
name = "Standard"
tier = "Standard"
}
}
replace_triggers_refs = ["sku"]
}
如果某個不同資源的 SKU 要變更，則這不會觸發替換操作。