了解 AzAPI 資料平面框架

大多數Azure資源透過 Azure Resource Manager（ARM）控制平面管理——一個位於 management.azure.com 的單一統一 API 表面。 azapi_resource、azapi_update_resource、和azapi_resource_action資源類型都鎖定這個控制平面。

部分 Azure 服務會提供獨立的 資料平面 API——一個服務專屬的 HTTPS 端點，讓使用者可以直接與服務互動，而無需透過 ARM。 例如{vaultName}.vault.azure.net的金鑰保存庫秘密API、{searchServiceName}.search.windows.net的Azure AI 搜尋服務索引API，以及{workspaceName}.dev.azuresynapse.net的Synapse工作區管線API。

azapi_data_plane_resource 透過啟用 Terraform 使用相同的 AzAPI 提供者認證與生命週期模型，以管理這些資料平面端點上的資源，來填補這個差距。

為什麼只支援經過精選的資源類型

與可針對任何 ARM 資源類型的 azapi_resource 不同，azapi_data_plane_resource 僅能支援 特定的註冊資源類型清單。

此限制存在是因為資料平面可擴充性需要在 AzAPI 提供者的資料平面框架中明確註冊。 該框架必須知道：

• 服務的基底端點模式（例如， {vaultName}.vault.azure.net）
• 每種支援資源類型的 REST 路徑（例如 /secrets/{secret-name}）
• 如何驗證這個端點（有些服務需要服務專屬的令牌受眾，而非預設的 ARM 受眾 https://management.azure.com）

每個註冊的資源類型都會將這種映射加入框架中。 未註冊的資源類型無法透過 來鎖定 azapi_data_plane_resource，因為提供者無法判斷正確的端點或認證範圍。

資料平面資源的運作方式parent_id

對於控制平面資源（azapi_resource），parent_id 總是 ARM 資源 ID，呈現為一個路徑格式 /subscriptions/{sub}/resourceGroups/{rg}/providers/{namespace}/{type}/{name}。

對於資料平面資源，parent_id 是 服務的資料平面主機名稱，但已去除該 https:// 協定和任何後方斜線。 此端點通常是建立後在 ARM 控制平面資源中暴露的屬性。

模式依服務而異：

從 ARM 輸出中擷取parent_id

使用response_export_values在父 ARM 資源中擷取資料平面端點，然後用trimprefix或replace剝離該協定：

resource "azurerm_key_vault" "example" {
  # ... configuration
}

resource "azapi_data_plane_resource" "secret" {
  type      = "Microsoft.KeyVault/vaults/secrets@7.4"
  # Strip "https://" and the trailing "/" from the vault URI
  parent_id = trimsuffix(trimprefix(azurerm_key_vault.example.vault_uri, "https://"), "/")
  name      = "my-secret"
  body = {
    value      = var.secret_value
    attributes = { enabled = true }
  }
}

當使用 azapi_resource 來建立父節點而非 AzureRM 時，請使用 response_export_values 來擷取端點：

resource "azapi_resource" "app_config" {
  type      = "Microsoft.AppConfiguration/configurationStores@2023-03-01"
  name      = "my-store"
  parent_id = azapi_resource.resource_group.id
  location  = "eastus"
  body      = { sku = { name = "standard" } }

  response_export_values = {
    endpoint = "properties.endpoint"
  }
}

resource "azapi_data_plane_resource" "key_value" {
  type      = "Microsoft.AppConfiguration/configurationStores/keyValues@1.0"
  parent_id = replace(azapi_resource.app_config.output.endpoint, "https://", "")
  name      = "mykey"
  body      = { value = "myvalue", content_type = "" }
}

對於端點源自資源名稱而非 URI 屬性的服務，請直接構造：

resource "azurerm_search_service" "example" {
  name                = "my-search"
  # ... configuration
}

resource "azapi_data_plane_resource" "index" {
  type      = "Microsoft.Search/searchServices/indexes@2024-07-01"
  parent_id = "${azurerm_search_service.example.name}.search.windows.net"
  name      = "my-index"
  body      = { fields = [ /* ... */ ] }
}

資料平面端點的認證

AzAPI 提供者則透明地處理認證。 它使用您在 provider "azapi" 區塊中配置的相同憑證（Azure CLI、服務主體、受管身份或 OpenID Connect (OIDC)），但會自動請求針對每個服務的資料平面受眾的權杖，而非 ARM 受眾的權杖。

例如，金鑰保存庫資料平面操作所需的標記受眾為 https://vault.azure.net，而非 https://management.azure.com。 AzAPI 提供者會根據註冊端點為每種資源類型選擇正確的受眾。

作為實務工作者，你不需要改變設定方式。 服務適用標準的角色基礎存取控制（RBAC）權限——例如，金鑰保存庫 Secrets Officer 管理 金鑰保存庫 機密，或 App Configuration Data Owner 管理應用程式設定金鑰值。

匯入資源 ID 格式

資料平面資源 ID 使用與 ARM 資源 ID 不同的格式。 匯入現有資料平面資源時，請使用以下格式 {parent_id}/{path}|{resource-type}@{api-version}：

import {
  to = azapi_data_plane_resource.example
  id = "exampleappconf.azconfig.io/kv/mykey|Microsoft.AppConfiguration/configurationStores/keyValues@1.0"
}

或者用：terraform import

terraform import azapi_data_plane_resource.example 'exampleappconf.azconfig.io/kv/mykey|Microsoft.AppConfiguration/configurationStores/keyValues@1.0'

支援的資料平面服務

AzAPI 提供者目前支援 azapi_data_plane_resource 以下服務的資源類型：

• Azure 應用程式組態—鍵值
• Azure AI Foundry—代理人
• Azure 裝置更新—群組、部署
• Azure Digital Twins—數位孿生、關係、事件路徑、匯入工作
• Azure IoT Central—組織、使用者、排程工作、API 令牌、儀表板、裝置群組、裝置範本、裝置、註冊群組、資料匯出、部署清單
• Azure Key Vault—憑證聯絡人、憑證發行者、金鑰、秘密、儲存帳號、SAS 定義
• Microsoft Purview—收藏、資源集規則設定、金鑰庫、分類規則、憑證、資料來源、掃描、掃描觸發器、整合執行時、受管理的私有端點、工作流程
• Azure AI 搜尋服務—資料來源、索引器、索引器、技能集、同義映射
• Azure Synapse Analytics—資料庫、資料流、資料集、Kusto 查詢語言（KQL）腳本、函式庫、連結連接、連結服務、受管理私有端點、筆記本、管線、角色指派、Spark 工作定義、Spark 設定、SQL 腳本、觸發器

完整清單及 API 版本與端點模式，請參閱 Terraform 登錄檔中的 available resources reference。

下一步