Terraform AzAPI 提供者概觀

AzAPI 提供者是 Azure ARM REST API 之上的精簡層。 它讓你能使用任何 API 版本管理任何 Azure 資源類型，讓你能在 Azure 中使用最新的功能。 AzAPI 是一流的提供者，其設計目的是要單獨或與 AzureRM 提供者搭配使用。

使用 AzAPI 提供者的優點

AzAPI 提供者具有下列優點：

• 支援所有 Azure 控制平面服務：
  • 預覽服務和功能
  • 所有 API 版本
• Terraform 狀態檔案的完整性
  • 屬性和值被保存到狀態中
• 不依賴 Swagger
• 一般且一致的 Azure 驗證
• 內建前置檢查驗證
• 精細控制基礎設施開發
• Microsoft Terraform Visual Studio Code extension

資源

若要讓您管理所有 Azure 資源和功能，而不需要更新，AzAPI 提供者包含下列一般資源：

關於資料平面框架的詳細說明，以及它與控制平面資源的 parent_id 差異，請參見 「了解 AzAPI 資料平面框架」。

使用階層

整體而言，使用方式應遵循下列步驟：

1. 從在azapi_resource內開始盡可能多地執行操作。
2. 如果資源類型不存在於 azapi_resource，但落在 azapi_data_plane_resource 支援的其中一種類型之下，請改用該類型。
3. 如果資源已存在於 AzureRM 中，或具有無法在 azapi_resource 中存取的屬性，請使用 azapi_update_resource 來存取這些特定屬性。 azapi_resource或azapi_data_plane_resource不支援的資源無法透過此資源更新。
4. 如果您嘗試執行一項不基於 Azure CRUD 友好資源的操作，azapi_resource_action 雖然不如 azapi_update_resource 直接，但卻更靈活。

資源組態範例

以下程式碼片段直接透過 ARM API 配置 Azure 資源：

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

啟用時，預檢會在 terraform plan 期間顯示設定錯誤，而不是在套用時。

數據源

AzAPI 提供者支援多種有用的資料來源：

若想了解如何使用 azapi_resource_list 及 JMESPath 過濾的實作範例，請參考 使用 AzAPI Terraform 提供者列出 Azure 資源。

閱讀現有的資源與 azapi_resource 資料來源

azapi_resource 資料來源會讀取任何Azure資源的當前狀態，並透過 output 屬性揭露其屬性。 當你需要 AzureRM 提供者不會暴露的屬性時，才會使用它：

data "azapi_resource" "aks" {
  type      = "Microsoft.ContainerService/managedClusters@2024-02-01"
  resource_id = azurerm_kubernetes_cluster.example.id

  # Extract the OIDC issuer URL, not exposed by azurerm_kubernetes_cluster
  response_export_values = ["properties.oidcIssuerProfile.issuerURL"]
}

output "oidc_issuer_url" {
  value = data.azapi_resource.aks.output.properties.oidcIssuerProfile.issuerURL
}

使用 response_export_values 與 JMESPath

response_export_values 控制從原始 ARM API 回應中擷取哪些屬性，並以屬性形式提供 output 。 它接受清單或地圖：

• 清單：指定要提取的 JSON 屬性路徑。 用 ["*"] 來匯出完整的回應正文。
• 地圖：使用 JMESPath 表達式來過濾並重塑回應。 鍵是輸出欄位名稱;值為 JMESPath 查詢。

映射形式較適合列表回應及需要轉換輸出的情況：

data "azapi_resource_list" "storage_accounts" {
  type      = "Microsoft.Storage/storageAccounts@2023-01-01"
  parent_id = azurerm_resource_group.example.id

  response_export_values = {
    "names"     = "value[].name"
    "locations" = "value[].location"
  }
}

完整攻略請參閱 使用 AzAPI Terraform 提供程式列出 Azure 資源。

使用 AzAPI 提供者進行驗證

AzAPI 提供者會啟用與 AzureRM 提供者相同的驗證方法。 如需驗證選項的詳細資訊，請參閱 向 Azure 驗證 Terraform。

AzAPI 提供者的體驗和生命週期

本節說明一些可協助您使用 AzAPI 提供者的工具。

VS Code 延伸模組和語言伺服器

Microsoft Terraform VS Code 擴充為 AzureRM 與 AzAPI 提供者提供豐富的創作體驗，包括：

• 列出所有可用的資源類型和 API 版本。
• 自動補全任何資源允許的屬性與值。
• 當將滑鼠停留在屬性欄上方時顯示提示。
• 語法驗證
• 自動補全並附有程式碼範例。

該擴充套件也支援貼上即 AzAPI（將 ARM JSON 轉換為 azapi_resource 區塊）、Azure 透過 aztfexport 匯出資源、AzureRM 遷移至 AzAPI，以及檢查前驗證。 完整指南請參見 Use the Microsoft Terraform VS Code 擴充功能。

aztfmigrate 遷移工具

aztfmigrate 工具 的設計目的是協助在 AzAPI 與 AzureRM 提供者之間移轉現有的資源。

aztfmigrate 有兩種模式：規劃和移轉：

• 方案會顯示可移轉的 AzAPI 資源。
• 移轉過程會將 AzAPI 資源在 HCL 文件和狀態中轉換為 AzureRM 資源。

aztfmigrate 可確保在移轉之後，您的 Terraform 組態和狀態會與您的實際狀態一致。 你可以在完成遷移後執行 terraform plan 來驗證狀態更新，並確認沒有發生任何變更。

欲了解逐步操作，請參見 「將資源從 AzAPI 遷移到 AzureRM」。

匯入現有的 Azure 資源

若要將現有的 Azure 資源納入 AzAPI 管理而不需重新建立，請使用 import 區塊（Terraform 1.5 及更新版本）或 terraform import 指令。 資源 ID 必須包含 API 版本作為查詢參數：

import {
  to = azapi_resource.example
  id = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/example-rg/providers/Microsoft.Network/virtualNetworks/example-vnet?api-version=2023-11-01"
}

resource "azapi_resource" "example" {
  type      = "Microsoft.Network/virtualNetworks@2023-11-01"
  name      = "example-vnet"
  parent_id = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/example-rg"
  location  = "westus"
  body = {
    properties = {
      addressSpace = {
        addressPrefixes = ["10.0.0.0/16"]
      }
    }
  }
}

若要同時從現有Azure基礎設施匯入多個資源，請使用 Azure Export for Terraform （），該功能會自動產生 HCL 設定與匯入區塊。

對基礎結構的細微控制

AzAPI 的其中一個主要優點是能夠微調您的設定，以符合正確的設計模式。 有數種方式可以執行這項作業：

提供者設定選項

AzAPI 提供者區塊接受多項設定，這些設定適用於配置中所有資源：

欲了解完整的提供者設定選項，請參閱 AzAPI 提供者架構。

關於啟用預檢的操作步驟，請參閱 AzAPI Terraform 提供者中的「啟用預檢驗證」。

提供者功能

AzAPI v2.0 及以後版本包含多項 提供者功能：

使用者自訂的可重試錯誤，搭配 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"
}

該 retry 區塊接受以下屬性：

與retry及timeouts區塊結合，設定總重試期間的上限：

timeouts {
  create = "10m"
}

短暫資源與唯寫屬性

AzAPI v2.x 透過sensitive_body屬性在azapi_resource上支援只寫參數（Terraform 1.11 及更新版本）。 唯寫屬性會傳送到 ARM API，但不會以 Terraform 狀態儲存，這對於秘密和憑證很有用：

resource "azapi_resource" "example" {
  type      = "Microsoft.SomeService/resources@2024-01-01"
  name      = "example"
  parent_id = azurerm_resource_group.example.id

  body = {
    properties = {
      name = "example"
    }
  }

  # Write-only — not stored in state
  sensitive_body = {
    properties = {
      adminPassword = var.admin_password
    }
  }
}

用 sensitive_body_version 來控制何時重送唯寫屬性到 API（例如輪換憑證時）。

資源取代的觸發因素

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 改變，這不會觸發更換。

下一步

• 選擇 AzureRM 與 AzAPI Terraform 提供者之間
• 了解 AzAPI 資料平面框架
• 使用 AzAPI 提供者部署您的第一個資源
• 使用 AzAPI 提供者部署您的第一個更新資源
• 使用 AzAPI 提供者部署您的第一個資源動作
• 使用 AzAPI 提供者執行資源操作
• 用 AzAPI
• 使用 AzAPI 提供者列出 Azure 資源
• 啟用檢查前驗證
• 使用 AzAPI 提供者函數
• Azure、AzureRM 和 AzAPI 之間的遷移路徑
• 造訪供應商登錄