Terraform AzAPI 提供者概觀

發行項
11/05/2024

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

資源

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

資源名稱	描述
azapi_resource	用來使用完整 CRUD 完全管理任何 Azure（控制平面）資源（API）。範例使用案例：新的預覽服務新增至現有服務的新功能目前未涵蓋的現有功能/服務
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 提供者進行驗證

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

使用 AzAPI 提供者的優點

AzAPI 提供者具有下列優點：

支援所有 Azure 控制平面服務：
- 預覽服務和功能
- 所有 API 版本
完整 Terraform 狀態檔案逼真度
- 屬性和值會儲存至狀態
不相依於 Swagger
一般且一致的 Azure 驗證
健全的 VS Code 擴充功能

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

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

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

AzAPI VS Code 擴充功能提供豐富的撰寫體驗，具有下列優點：

列出所有可用的資源類型和 API 版本。
自動完成任何資源的允許屬性和值。
將滑鼠停留在屬性上方時顯示提示。
語法驗證
使用程式代碼範例自動完成。

AzAPI2AzureRM 移轉工具

AzureRM 提供者提供最整合的 Terraform 體驗來管理 Azure 資源。因此，建議使用 AzAPI 和 AzureRM 提供者，如下所示：

當服務或功能處於預覽狀態時，請使用 AzAPI 提供者。
正式發行服務之後，請使用 AzureRM 提供者。

AzAPI2AzureRM 工具旨在協助從 AzAPI 提供者移轉至 AzureRM 提供者。

AzAPI2AzureRM 是開放原始碼工具，可將 AzAPI 資源轉換為 AzureRM 資源的程式自動化。

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

方案會顯示可移轉的 AzAPI 資源。
將 AzAPI 資源移轉至 HCL 檔案和狀態中的 AzureRM 資源。

AzAPI2AzureRM 可確保移轉後的 Terraform 組態和狀態會與您的實際狀態一致。完成移轉之後，您可以執行 terraform plan 來驗證狀態的更新，以查看沒有任何變更。

使用 AzAPI 提供者

安裝 VS Code 擴充功能

將 AzAPI 提供者新增至您的 Terraform 組態。

terraform {
  required_providers {
    azapi = {
      source  = "Azure/azapi"
    }
  }
}

provider "azapi" {
  # More information on the authentication methods supported by
  # the AzureRM Provider can be found here:
  # https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs

  # subscription_id = "..."
  # client_id       = "..."
  # client_secret   = "..."
  # tenant_id       = "..."
}

宣告一或多個 AzAPI 資源，如下列範例程式代碼所示：

resource "azapi_resource" "example" {
  name = "example"
  parent_id = data.azurerm_machine_learning_workspace.existing.id
  type = "Microsoft.MachineLearningServices/workspaces/computes@2021-07-01"

  location = "eastus"
  body = {
    properties = {
      computeType      = "ComputeInstance"
      disableLocalAuth = true
      properties = {
        vmSize = "STANDARD_NC6"
      }
    }
  }
}

共用方式為