Entender a estrutura do plano de dados do AzAPI

A maioria dos recursos do Azure é gerenciada por meio do plano de controle do Azure Resource Manager (ARM) — uma única superfície de API unificada em management.azure.com. Os tipos de recurso azapi_resource, azapi_update_resource e azapi_resource_action são direcionados a este plano de controle.

Alguns serviços do Azure expõem uma API separada do plano de dados — um ponto de extremidade HTTPS específico do serviço em que você interage diretamente com o serviço e não por meio 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 de pipeline do workspace Synapse em {workspaceName}.dev.azuresynapse.net.

azapi_data_plane_resource abre essa lacuna permitindo que o Terraform gerencie recursos nesses pontos de extremidade do plano de dados usando o mesmo modelo de autenticação e ciclo de vida do provedor AzAPI.

Por que há suporte apenas para um conjunto de tipos de recursos com curadoria

Ao contrário de azapi_resource, que pode direcionar qualquer tipo de recurso arm, azapi_data_plane_resource funciona apenas com uma lista específica de tipos de recursos registrados.

Essa restrição existe porque a extensibilidade do plano de dados requer um registro explícito na estrutura do plano de dados do provedor de AzAPI. A estrutura deve saber:

• O padrão de ponto de extremidade base para um serviço (por exemplo, {vaultName}.vault.azure.net)
• O caminho REST para cada tipo de recurso com suporte (por exemplo, /secrets/{secret-name})
• Como autenticar neste endpoint (alguns serviços exigem audiências de token específicas do serviço em vez do padrão ARM em https://management.azure.com)

Cada tipo de recurso registrado adiciona esse mapeamento à estrutura. Os tipos de recurso não registrados não podem ser alvo por meio de azapi_data_plane_resource, pois o provedor não tem como determinar o ponto de extremidade ou o escopo de autenticação corretos.

Como parent_id funciona para recursos do plano de dados

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

Para recursos do plano de dados, parent_id é o nome do host do plano de dados do serviço, sem o esquema https:// e qualquer barra no final. Esse endpoint normalmente é uma propriedade exposta no recurso do plano de controle ARM após a criação.

O padrão varia de acordo com o serviço:

Extraindo parent_id a partir da saída do ARM

Use response_export_values no recurso ARM pai para extrair o ponto de extremidade do plano de dados e, em seguida, remova 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 pai, em vez de AzureRM, utilize response_export_values para capturar o ponto de extremidade:

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 em que o endpoint é derivado do nome do recurso em vez de uma propriedade URI, construa-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 para pontos de extremidade do plano de dados

O provedor AzAPI lida com a autenticação de forma transparente. Ele usa as mesmas credenciais que você configura no bloco provider "azapi" (CLI do Azure, entidade de serviço, identidade gerenciada ou OIDC (OpenID Connect)), mas solicita automaticamente tokens com escopos específicos para o público do plano de dados de cada serviço em vez do público do ARM.

Por exemplo, as operações do plano de dados do Key Vault exigem o público-alvo de token de https://vault.azure.net, não https://management.azure.com. O provedor de AzAPI seleciona o público-alvo correto com base no ponto de extremidade registrado para cada tipo de recurso.

Como praticante, você não precisa configurar nada diferente. As permissões padrão de RBAC (controle de acesso baseado em função) para o serviço se aplicam—por exemplo, Key Vault Secrets Officer para gerenciar segredos do Key Vault ou App Configuration Data Owner para gerenciar valores de chave do App Configuration.

Formato de ID do recurso para importação

As IDs de recurso do plano de dados usam um formato diferente das IDs de recurso do ARM. Ao importar um recurso de plano de dados existente, use 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 de plano de dados com suporte

Atualmente, o provedor de AzAPI dá suporte azapi_data_plane_resource a tipos de recursos nesses serviços:

• Configuração de Aplicativos do Azure — key-values
• Fábrica de IA do Azure— agentes
• Azure Device Update — grupos, implantações
• Gêmeos Digitais do Azure — gêmeos digitais, relações, rotas de eventos, trabalhos de importação
• Azure IoT Central — organizações, usuários, trabalhos agendados, tokens de API, dashboards, grupos de dispositivos, modelos de dispositivo, dispositivos, grupos de registro, exportações de dados, manifestos de implantação
• Azure Key Vault — contatos de certificados, emissores de certificado, chaves, segredos, contas de armazenamento, definições de SAS
• Microsoft Purview— coleções, configurações de regra do conjunto de recursos, cofres de chaves, regras de classificação, credenciais, fontes de dados, varreduras, gatilhos de varredura, tempos de execução de integração, endpoints privados gerenciados, fluxos de trabalho
• Pesquisa de IA do Azure  — fontes de dados, indexadores, índices, conjuntos de habilidades, mapas de sinônimos
• Azure Synapse Analytics — bancos de dados, fluxos de dados, conjuntos de dados, scripts de KQL (Linguagem de Consulta Kusto), bibliotecas, conexões de vínculo, serviços vinculados, pontos de extremidade privados gerenciados, notebooks, pipelines, atribuições de função, definições de trabalho do Spark, configurações do Spark, scripts SQL, gatilhos

Para obter a lista completa com versões de API e padrões de ponto de extremidade, consulte a referência de recursos disponíveis no Registro Terraform.

Próximas Etapas