了解 AzAPI 数据平面框架

大多数 Azure 资源都通过微软的 Azure 资源管理器（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

在父 ARM 资源上使用response_export_values提取数据平面终结点，然后通过使用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 数字孪生 — 数字孪生、关系、事件路由、导入作业
• Azure IoT Central — 组织、用户、计划作业、API 令牌、仪表板、设备组、设备模板、设备、注册组、数据导出、部署清单
• Azure 密钥保管库 — 证书联系人、证书颁发者、密钥、机密、存储帐户、SAS 定义
• Microsoft Purview — 集合、资源集规则配置、密钥保管库、分类规则、凭据、数据源、扫描、扫描触发器、集成运行时、托管专用终结点、工作流
• Azure AI 搜索 — 数据源、索引器、索引器、技能集、同义词映射
• Azure Synapse Analytics — 数据库、数据流、数据集、Kusto 查询语言（KQL）脚本、库、链接连接、链接服务、托管专用终结点、笔记本、管道、角色分配、Spark 作业定义、Spark 配置、SQL 脚本、触发器

有关 API 版本和终结点模式的完整列表，请参阅 Terraform 注册表中的 可用资源参考。

后续步骤