Memahami kerangka kerja sarana data AzAPI

Sebagian besar sumber daya Azure dikelola melalui sarana kontrol Azure Resource Manager (ARM) —satu permukaan API terpadu pada management.azure.com. Jenis azapi_resourcesumber daya , azapi_update_resource, dan azapi_resource_action semuanya menargetkan sarana kontrol ini.

Beberapa layanan Azure mengekspos data plane API terpisah—titik akhir HTTPS khusus layanan tempat Anda berinteraksi langsung dengan layanan daripada melalui ARM. Contohnya termasuk API rahasia Key Vault di {vaultName}.vault.azure.net, API indeks Pencarian Azure AI pada {searchServiceName}.search.windows.net, dan API alur ruang kerja Synapse di {workspaceName}.dev.azuresynapse.net.

azapi_data_plane_resource menjembatani kesenjangan ini dengan mengaktifkan Terraform untuk mengelola sumber daya pada titik akhir bidang data ini menggunakan model autentikasi dan siklus hidup penyedia AzAPI yang sama.

Mengapa hanya sekumpulan jenis sumber daya yang dikumpulkan yang didukung

Tidak seperti azapi_resource, yang dapat menargetkan jenis sumber daya ARM apa pun, azapi_data_plane_resource hanya berfungsi dengan daftar spespesifik jenis sumber daya terdaftar.

Batasan ini ada karena ekstensibilitas bidang data memerlukan pendaftaran eksplisit dalam kerangka kerja sarana data penyedia AzAPI. Kerangka kerja harus mengetahui:

  • Pola titik akhir dasar untuk layanan (misalnya, {vaultName}.vault.azure.net)
  • Jalur REST untuk setiap jenis sumber daya yang didukung (misalnya, /secrets/{secret-name})
  • Cara melakukan autentikasi pada endpoint ini (beberapa layanan memerlukan audiens token khusus layanan alih-alih audiens ARM default di https://management.azure.com)

Setiap jenis sumber daya terdaftar menambahkan pemetaan ini ke kerangka kerja. Jenis sumber daya yang tidak terdaftar tidak dapat ditargetkan melalui azapi_data_plane_resource, karena penyedia tidak memiliki cara untuk menentukan titik akhir atau cakupan autentikasi yang benar.

Tip

Jika jenis sumber daya sarana data yang Anda butuhkan tidak didukung, Anda dapat membuka masalah atau menyumbang pendaftaran di terraform-provider-azapi GitHub repositori.

Cara kerja parent_id untuk sumber daya plane data

Untuk sumber daya sarana kontrol (azapi_resource), parent_id selalu merupakan ID sumber daya ARM—jalur dalam formulir /subscriptions/{sub}/resourceGroups/{rg}/providers/{namespace}/{type}/{name}.

Untuk sumber daya data plane, parent_id adalah nama host sarana data layanan, dilucuti dari https:// skema dan garis miring berikutnya. Titik akhir ini biasanya merupakan properti yang diekspos pada sumber daya sarana kontrol ARM setelah pembuatan.

Pola bervariasi menurut layanan:

Service Properti keluaran ARM pola parent_id
Key Vault properties.vaultUri {vaultName}.vault.azure.net
Azure App Configuration properties.endpoint {storeName}.azconfig.io
Pencarian Azure AI (dibangun dari nama) {searchServiceName}.search.windows.net
Ruang kerja Synapse connectivityEndpoints.dev {workspaceName}.dev.azuresynapse.net
Aplikasi IoT Central properties.subdomain {appSubdomain}.azureiotcentral.com
Microsoft Purview (dibangun dari nama) {accountName}.purview.azure.com

Mengekstrak parent_id dari output ARM

Gunakan response_export_values pada sumber daya ARM induk untuk mengekstrak titik akhir bidang data, lalu hapus skema dengan trimprefix atau 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 }
  }
}

Saat menggunakan azapi_resource untuk membuat induk alih-alih AzureRM, gunakan response_export_values untuk mengambil titik akhir:

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

Untuk layanan di mana titik akhir berasal dari nama sumber daya daripada properti URI, buat secara langsung:

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

Autentikasi ke titik akhir bidang data

Penyedia AzAPI menangani autentikasi secara transparan. Ini menggunakan kredensial yang sama dengan yang Anda konfigurasi pada blok provider "azapi" (Azure CLI, perwakilan layanan, identitas terkelola, atau OpenID Connect (OIDC)), tetapi secara otomatis meminta token yang diatur khusus untuk audiens bidang data dari setiap layanan, bukan untuk audiens ARM.

Misalnya, operasi bidang data Key Vault memerlukan audiens token https://vault.azure.net, bukan https://management.azure.com. Penyedia AzAPI memilih audiens yang benar berdasarkan titik akhir terdaftar untuk setiap jenis sumber daya.

Sebagai praktisi, Anda tidak perlu mengonfigurasi apa pun secara berbeda. Izin kontrol akses berbasis peran standar (RBAC) untuk layanan berlaku—misalnya, Key Vault Secrets Officer untuk mengelola rahasia Key Vault, atau App Configuration Data Owner untuk mengelola nilai kunci App Configuration.

Nota

Untuk beberapa layanan (seperti Azure App Configuration dan Pencarian Azure AI), pemanggil harus memiliki penetapan peran bidang data yang sesuai, bukan hanya peran pemilik sarana kontrol. Pastikan identitas yang menjalankan Terraform memiliki penetapan kontrol akses berbasis peran (RBAC) bidang data yang benar sebelum menerapkan konfigurasi yang menggunakan azapi_data_plane_resource.

Format ID sumber daya untuk impor

ID sumber daya pada data plane menggunakan format yang berbeda dari ID sumber daya ARM. Saat mengimpor sumber daya sarana data yang ada, gunakan format {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"
}

Atau dengan terraform import:

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

Layanan sarana data yang didukung

Penyedia AzAPI saat ini mendukung azapi_data_plane_resource jenis sumber daya di seluruh layanan ini:

  • Azure App Configuration—nilai kunci
  • Azure AI Foundry—agen
  • Azure Device Update—grup, penyebaran
  • Azure Digital Twins—digital twins, hubungan, rute acara, pekerjaan impor
  • Azure IoT Central—organisasi, pengguna, pekerjaan terjadwal, token API, dasbor, grup perangkat, templat perangkat, perangkat, grup pendaftaran, ekspor data, manifes penyebaran
  • Azure Key Vault—kontak sertifikat, penerbit sertifikat, kunci, rahasia, akun penyimpanan, definisi SAS
  • Microsoft Purview—koleksi, konfigurasi aturan kumpulan sumber daya, brankas kunci, aturan klasifikasi, kredensial, sumber data, pemindaian, pemicu pemindaian, runtime integrasi, titik akhir privat terkelola, alur kerja
  • Pencarian Azure AI—sumber data, pengindeks, indeks, set keterampilan, peta sinonim
  • Azure Synapse Analytics—database, aliran data, himpunan data, skrip Kusto Query Language (KQL), pustaka, koneksi tautan, layanan tertaut, titik akhir privat terkelola, buku catatan, alur, penetapan peran, definisi kerja Spark, konfigurasi Spark, skrip SQL, pemicu

Untuk daftar lengkap dengan versi API dan pola titik akhir, lihat referensi sumber daya tersedia di Terraform Registry.

Langkah berikutnya

Kelola sumber daya sarana data Azure dengan AzAPI (mulai cepat)

Gambaran umum penyedia Terraform AzAPI

  • Last updated on