Compreender a estrutura do plano de dados AzAPI

A maioria dos recursos Azure é gerida através do plano de controlo Azure Resource Manager (ARM) — uma única superfície API unificada em management.azure.com. Os tipos de recursos azapi_resource, azapi_update_resource e azapi_resource_action têm todos como alvo este plano de controlo.

Alguns serviços do Azure expõem uma API de plano de dados separada — um endpoint HTTPS específico do serviço onde se interage diretamente com o serviço, em vez de através do ARM. Exemplos incluem a API de segredos do Key Vault em {vaultName}.vault.azure.net, a API de índice do Pesquisa de IA do Azure em {searchServiceName}.search.windows.net, e a API do pipeline do espaço de trabalho do Synapse em {workspaceName}.dev.azuresynapse.net.

azapi_data_plane_resource colmata esta lacuna ao permitir que o Terraform gere recursos nestes endpoints do plano de dados usando o mesmo modelo de autenticação e ciclo de vida do fornecedor AzAPI.

Porque é que apenas um conjunto selecionado de tipos de recursos é suportado

Ao contrário do azapi_resource, que pode direcionar qualquer tipo de recurso ARM, azapi_data_plane_resource só funciona com uma lista específica de tipos de recursos registados.

Esta restrição existe porque a extensibilidade do plano de dados requer registo explícito no framework do plano de dados do fornecedor AzAPI. O quadro deve saber:

• O padrão base de endpoint para um serviço (por exemplo, {vaultName}.vault.azure.net)
• O caminho REST para cada tipo de recurso suportado (por exemplo, /secrets/{secret-name})
• Como efetuar a autenticação neste endpoint (alguns serviços requerem públicos específicos de tokens de serviço em vez do público padrão ARM em https://management.azure.com)

Cada tipo de recurso registado adiciona este mapeamento ao framework. Tipos de recursos não registados não podem ser direcionados através de azapi_data_plane_resource, porque o fornecedor não consegue determinar o ponto final ou o escopo de autenticação corretos.

Tip

Se um tipo de recurso de plano de dados que precisa não for suportado, pode abrir uma questão ou contribuir com um registo no repositório GitHub terraform-provider-azapi.

Como parent_id funciona para os recursos da camada de dados

Para recursos do plano de controlo (azapi_resource), parent_id é sempre um ID de recurso ARM — um caminho na forma /subscriptions/{sub}/resourceGroups/{rg}/providers/{namespace}/{type}/{name}.

Para os recursos do plano de dados, parent_id é o nome host do plano de dados do serviço, despojado do https:// esquema e de qualquer barra final. Este endpoint é tipicamente exposto como uma propriedade no recurso do plano de controlo ARM após a sua criação.

O padrão varia consoante o serviço:

Service	Propriedade de saída ARM	parent_id padrão
Cofre de Chaves	properties.vaultUri	{vaultName}.vault.azure.net
Azure App Configuration	properties.endpoint	{storeName}.azconfig.io
Pesquisa de IA do Azure	(construído a partir do nome)	{searchServiceName}.search.windows.net
Espaço de Trabalho do Synapse	connectivityEndpoints.dev	{workspaceName}.dev.azuresynapse.net
Aplicação IoT Central	properties.subdomain	{appSubdomain}.azureiotcentral.com
Microsoft Purview	(construído a partir do nome)	{accountName}.purview.azure.com

Extração parent_id da saída do ARM

Use response_export_values no recurso ARM pai para extrair o ponto final do plano de dados, depois remove o esquema com trimprefix ou 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 }
  }
}

Ao usar azapi_resource para criar o elemento pai em vez do AzureRM, use response_export_values para capturar o endpoint:

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 = "" }
}

Para serviços onde o endpoint é derivado do nome do recurso em vez de uma propriedade URI, constrói-o diretamente:

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 = [ /* ... */ ] }
}

Autenticação aos pontos finais do plano de dados

O fornecedor AzAPI gere a autenticação de forma transparente. Utiliza as mesmas credenciais que configura no bloco provider "azapi" (CLI do Azure, principal de serviço, identidade gerida, ou OpenID Connect (OIDC)), mas solicita automaticamente tokens destinados à audiência de plano de dados de cada serviço, ao invés da audiência ARM.

Por exemplo, as operações do plano de dados do Key Vault exigem uma audiência de token de https://vault.azure.net, não https://management.azure.com. O fornecedor AzAPI seleciona o público correto com base no endpoint registado para cada tipo de recurso.

Como praticante, não precisas de configurar nada de forma diferente. Aplicam-se as permissões padrão de controlo de acesso baseado em funções (RBAC) para o serviço — por exemplo, Key Vault Secrets Officer para gerir segredos do Key Vault, ou App Configuration Data Owner para gerir valores chave da App Configuration.

Observação

Para alguns serviços (como Azure App Configuration e Pesquisa de IA do Azure), o chamador deve ter a atribuição adequada da função no plano de dados, e não apenas a função de proprietário no plano de gestão. Certifique-se de que a identidade que executa o Terraform tem a atribuição correta de controlo de acesso baseado em funções (RBAC) no plano de dados antes de aplicar configurações que utilizem azapi_data_plane_resource.

Formato de ID de recurso para importação

Os IDs de recursos do plano de dados usam um formato diferente dos IDs de recursos ARM. Ao importar um recurso existente no plano de dados, utilize o formato {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"
}

Ou com terraform import:

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

Serviços suportados no plano de dados

O fornecedor AzAPI atualmente suporta azapi_data_plane_resource para os tipos de recursos nestes serviços:

• Azure App Configuration—valores-chave
• Azure AI Foundry—agentes
• Azure Atualização de Dispositivos—grupos, implementações
• Azure Digital Twins—gémeos digitais, relações, rotas de eventos, tarefas de importação
• Azure IoT Central—organizações, utilizadores, trabalhos agendados, tokens de API, painéis, grupos de dispositivos, modelos de dispositivos, dispositivos, grupos de inscrição, exportações de dados, manifestos de implementação
• Azure Key Vault—contactos de certificados, emissores de certificados, chaves, segredos, contas de armazenamento, definições SAS
• Microsoft Purview—coleções, configurações de regras do conjunto de recursos, cofres de chaves, regras de classificação, credenciais, fontes de dados, varreduras, disparadores de análise, plataformas de execução de integração, endpoints privados geridos, fluxos de trabalho
• Pesquisa de IA do Azure—fontes de dados, indexadores, índices, conjuntos de competências, mapas de sinónimos
• Azure Synapse Analytics—bases de dados, fluxos de dados, conjuntos de dados, scripts da Linguagem de Consulta Kusto (KQL), bibliotecas, ligações de ligação, serviços ligados, endpoints privados geridos, cadernos, pipelines, atribuições de funções, definições de tarefas Spark, configurações Spark, scripts SQL, triggers

Para a lista completa com versões da API e padrões de endpoint, consulte a referência recursos disponíveis no Terraform Registry.

Passos seguintes

Gerir recursos do plano de dados do Azure com AzAPI (início rápido)

Visão geral do fornecedor do Terraform AzAPI