Přehled provideru Terraform AzAPI

Zprostředkovatel AzAPI je tenká vrstva nad REST API Azure ARM. Umožňuje spravovat jakýkoli typ prostředku Azure pomocí libovolné verze rozhraní API, což vám umožní používat nejnovější funkce v rámci Azure. AzAPI je prvotřídní poskytovatel navržený tak, aby se používal samostatně nebo společně s poskytovatelem AzureRM.

Výhody použití poskytovatele AzAPI

Poskytovatel AzAPI má následující výhody:

Podporuje všechny služby řídicí vrstvy Azure:
- Služby a funkce ve verzi Preview
- Všechny verze rozhraní API
Úplná přesnost souboru stavu Terraformu
- Vlastnosti a hodnoty se ukládají do stavu.
Bez závislosti na Swaggeru
Běžné a konzistentní ověřování Azure
Vestavěná kontrola před spuštěním
Podrobná kontrola vývoje infrastruktury
Rozšíření Microsoft Terraform pro Visual Studio Code

Zdroje informací

Aby bylo možné spravovat všechny prostředky a funkce Azure bez nutnosti aktualizací, poskytovatel AzAPI obsahuje následující obecné prostředky:

Název prostředku	Popis
`azapi_resource`	Slouží k úplné správě jakéhokoli prostředku v Azure (řídicí rovina, API) s úplným CRUD. Příklady případů použití: Nová služba Preview Nová funkce přidaná do existující služby Všechny Azure prostředky přístupné prostřednictvím rozhraní API ARM
`azapi_update_resource`	Slouží ke správě prostředků nebo částí prostředků, které nemají úplné CRUD. Příklady případů použití: Aktualizace existující služby o nové vlastnosti Aktualizace předem vytvořených podřízených prostředků , jako je záznam DNS SOA.
`azapi_resource_action`	Slouží k provedení jedné operace s prostředkem bez správy životního cyklu prostředku. Příklady případů použití: Vypnutí virtuálního počítače Přidání tajného kódu do služby Key Vault
`azapi_data_plane_resource`	Slouží ke správě konkrétní podmnožinu prostředků roviny dat Azure. Příklady případů použití: Kontakty certifikátu služby KeyVault Knihovny pracovních prostorů Synapse

Podrobné vysvětlení toho, jak architektura roviny dat funguje a jak parent_id se liší od prostředků řídicí roviny, najdete v tématu Vysvětlení architektury roviny dat AzAPI.

Hierarchie využití

Celkově by využití mělo postupovat takto:

Začněte prováděním co nejvíce operací v rámci azapi_resource.
Pokud typ prostředku neexistuje v rámci azapi_resource, ale spadá pod jeden z typů podporovaných azapi_data_plane_resource, použijte ho.
Pokud prostředek již existuje v AzureRM nebo má vlastnost, ke které se nedá přistupovat uvnitř azapi_resource, použijte azapi_update_resource pro přístup k těmto konkrétním vlastnostem. Prostředky, které azapi_resource nebo azapi_data_plane_resource nepodporují, se nedají prostřednictvím tohoto prostředku aktualizovat.
Pokud se pokoušíte provést akci, která není založená na prostředku Azure přátelském pro CRUD, použití azapi_resource_action je méně přímé než použití azapi_update_resource, ale více flexibilní.

Příklady konfigurace prostředků

Následující fragment kódu konfiguruje prostředek Azure přímo prostřednictvím rozhraní API ARM:

resource "azapi_resource" "publicip" {
  type      = "Microsoft.Network/Customipprefixes@2021-03-01"
  name      = "exfullrange"
  parent_id = azurerm_resource_group.example.id
  location  = "westus2"

  body = {
    properties = {
      cidr          = "10.0.0.0/24"
      signedMessage = "Sample Message for WAN"
    }
  }
}

Následující fragment kódu nakonfiguruje vlastnost Preview pro existující prostředek z AzureRM:

resource "azapi_update_resource" "test" {
  type        = "Microsoft.ContainerRegistry/registries@2020-11-01-preview"
  resource_id = azurerm_container_registry.acr.id

  body = {
    properties = {
      anonymousPullEnabled = var.bool_anonymous_pull
    }
  }
}

Následující fragment kódu konfiguruje akci prostředku u existujícího prostředku AzureRM:

resource "azapi_resource_action" "vm_shutdown" {
  type = "Microsoft.Compute/virtualMachines@2023-07-01"
  resource_id = azurerm_linux_virtual_machine.example.id
  action = "powerOff”
}

Následující fragment kódu konfiguruje prostředek, který v zprostředkovateli AzureRM aktuálně neexistuje, protože je zřízený v rovině dat:

resource "azapi_data_plane_resource" "dataset" {
  type      = "Microsoft.Synapse/workspaces/datasets@2020-12-01"
  parent_id = trimprefix(data.azurerm_synapse_workspace.example.connectivity_endpoints.dev, "https://")
  name      = "example-dataset"
  body = {
    properties = {
      type = "AzureBlob",
      typeProperties = {
        folderPath = {
          value = "@dataset().MyFolderPath"
          type  = "Expression"
        }
        fileName = {
          value = "@dataset().MyFileName"
          type  = "Expression"
        }
        format = {
          type = "TextFormat"
        }
      }
      parameters = {
        MyFolderPath = {
          type = "String"
        }
        MyFileName = {
          type = "String"
        }
      }
    }
  }
}

Příklad předběžného využití

Následující fragment kódu obsahuje chybu kvůli integrovanému předběžnému ověření AzAPI během terraform plan.

provider "azapi" {
  enable_preflight = true
}
resource "azapi_resource" "vnet" {
  type      = "Microsoft.Network/virtualNetworks@2024-01-01"
  parent_id = azapi_resource.resourceGroup.id
  name      = "example-vnet"
  location  = "westus"
  body = {
    properties = {
      addressSpace = {
        addressPrefixes = [
          "10.0.0.0/160", # preflight will throw an error here
        ]
      }
    }
  }
}

Pokud je tato možnost povolená, kontrola před spuštěním zobrazí chyby konfigurace během terraform plan namísto před aplikací.

Zdroje dat

Poskytovatel AzAPI podporuje různé užitečné zdroje dat:

Název zdroje dat	Popis
`azapi_resource`	Používá se ke čtení informací z libovolného prostředku Azure (řídicí roviny) (API). Příklady případů použití: Nová služba Preview Nová funkce přidaná do existující služby Všechny Azure prostředky přístupné prostřednictvím rozhraní API ARM
`azapi_client_config`	Přístup k informacím o klientovi, jako je ID předplatného a ID tenanta
`azapi_resource_action`	Slouží k provedení jedné operace čtení u prostředku bez správy jeho životního cyklu. Příklady případů použití: Výpis klíčů Stav virtuálního počítače
`azapi_data_plane_resource`	Používá se pro přístup k konkrétní podmnožině prostředků roviny dat Azure. Příklady případů použití: Kontakty certifikátu služby KeyVault Knihovny pracovních prostorů Synapse
`azapi_resource_id`	Získejte přístup k ID prostředku s možností výstupu informací, jako je ID předplatného, nadřazené ID, název skupiny prostředků a název prostředku.
`azapi_resource_list`	Seznamuje všechny prostředky podle daného ID nadřazeného prostředku. Příklady případů použití: Prostředky v rámci předplatného nebo skupiny prostředků Podsítě ve virtuální síti

Praktický příklad na použití azapi_resource_list s filtrováním JMESPath naleznete v článku Seznam prostředků Azure pomocí AzAPI Terraform provideru.

Čtení existujícího prostředku s `azapi_resource` datovým zdrojem

Zdroj dat azapi_resource přečte aktuální stav jakéhokoli prostředku Azure a zpřístupní jeho vlastnosti prostřednictvím atributu output. Použijte ho, pokud potřebujete vlastnost, kterou poskytovatel AzureRM nezpřístupňuje:

data "azapi_resource" "aks" {
  type      = "Microsoft.ContainerService/managedClusters@2024-02-01"
  resource_id = azurerm_kubernetes_cluster.example.id

  # Extract the OIDC issuer URL, not exposed by azurerm_kubernetes_cluster
  response_export_values = ["properties.oidcIssuerProfile.issuerURL"]
}

output "oidc_issuer_url" {
  value = data.azapi_resource.aks.output.properties.oidcIssuerProfile.issuerURL
}

Použijte `response_export_values` a JMESPath

response_export_values určuje, které vlastnosti se extrahují z nezpracované odpovědi rozhraní ARM API a zpřístupní se v atributu output . Přijímá seznam nebo mapu:

Seznam: Zadejte cesty vlastností JSON, které se mají extrahovat. Slouží ["*"] k exportu celého textu odpovědi.
Mapa: Použití výrazů JMESPath k filtrování a přetváření odpovědi. Klíč je název výstupního pole; hodnota je dotaz JMESPath.

Formulář mapy je upřednostňovaný pro odpovědi na seznam a případy, kdy potřebujete transformovat výstup:

data "azapi_resource_list" "storage_accounts" {
  type      = "Microsoft.Storage/storageAccounts@2023-01-01"
  parent_id = azurerm_resource_group.example.id

  response_export_values = {
    "names"     = "value[].name"
    "locations" = "value[].location"
  }
}

Úplný návod najdete v tématu List Azure prostředků pomocí poskytovatele AzAPI Terraform.

Ověřování pomocí zprostředkovatele AzAPI

Zprostředkovatel AzAPI umožňuje stejné metody ověřování jako poskytovatel AzureRM. Další informace o možnostech ověřování najdete v tématu Ověřování Terraformu v Azure.

Zkušenosti a životní cyklus poskytovatele AzAPI

Tato část popisuje některé nástroje, které vám pomůžou používat poskytovatele AzAPI.

Rozšíření VS Code a jazykový server

Rozšíření Microsoft Terraform VS Code poskytuje bohaté prostředí pro vytváření obsahu pro poskytovatele AzureRM i AzAPI, mezi které patří:

Zobrazí seznam všech dostupných typů prostředků a verzí rozhraní API.
Automatické dokončování povolených vlastností a hodnot pro libovolný prostředek
Zobrazit nápovědy při najetí myší na vlastnost
Ověření syntaxe
Automatické dokončování s ukázkami kódu

Rozšíření také podporuje vložení jako AzAPI (převede ARM JSON na bloky azapi_resource), export prostředků Azure pomocí aztfexport, migraci z AzureRM na AzAPI a kontrolu předběžné validace. Úplnou příručku najdete v tématu Užití rozšíření Microsoft Terraform VS Code.

nástroj pro migraci `aztfmigrate`

Nástroj aztfmigrate je navržený tak, aby pomohl migrovat existující prostředky mezi poskytovateli AzAPI a AzureRM.

aztfmigrate má dva režimy: plánování a migrace:

Plán zobrazí prostředky AzAPI, které je možné migrovat.
Přenáší prostředky AzAPI do prostředků AzureRM jak v souborech HCL, tak ve stavu.

aztfmigrate po migraci zajistíte, že konfigurace a stav Terraformu odpovídají vašemu skutečnému stavu. Aktualizaci stavu můžete ověřit spuštěním terraform plan po dokončení migrace, abyste potvrdili, že nedošlo k žádným změnám.

Podrobný návod najdete v tématu Migrace prostředků z AzAPI do AzureRM.

Import existujících prostředků Azure

Pokud chcete do správy AzAPI přenést existující Azure prostředek bez jeho opětovného vytvoření, použijte blok import (Terraform 1.5 a novější) nebo příkaz terraform import. ID prostředku musí jako parametr dotazu obsahovat verzi rozhraní API:

import {
  to = azapi_resource.example
  id = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/example-rg/providers/Microsoft.Network/virtualNetworks/example-vnet?api-version=2023-11-01"
}

resource "azapi_resource" "example" {
  type      = "Microsoft.Network/virtualNetworks@2023-11-01"
  name      = "example-vnet"
  parent_id = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/example-rg"
  location  = "westus"
  body = {
    properties = {
      addressSpace = {
        addressPrefixes = ["10.0.0.0/16"]
      }
    }
  }
}

Pokud chcete importovat více prostředků najednou z existující infrastruktury Azure, použijte Azure Export pro Terraform (aztfexport), který generuje konfiguraci seznamu HCL i bloky importu automaticky.

Podrobné kontroly nad infrastrukturou

Jednou z hlavních výhod AzAPI je možnost doladit konfiguraci tak, aby odpovídala správným vzorům návrhu. Můžete to udělat několika způsoby:

Možnosti konfigurace zprostředkovatele

Blok zprostředkovatele AzAPI přijímá několik nastavení, která se vztahují globálně napříč všemi prostředky v konfiguraci:

Option	Popis
`enable_preflight`	Povolí předběžné ověření při plánování. Výchozí hodnota je `false`. Podrobnosti najdete v tématu Povolení předběžného ověření v zprostředkovateli Terraformu AzAPI.
`ignore_no_op_changes`	Potlačuje šum během doby plánování z rozdílů, které nemají operační účinek, mezi konfigurací a normalizovanými odpověďmi rozhraní API. Výchozí hodnota je `true`.
`disable_default_output`	Pokud je nastavená hodnota `true`, zakáže automatický výstup vlastností jen pro čtení, pokud `response_export_values` není zadán. Výchozí hodnota je `false`.
`default_location`	Nastaví výchozí hodnotu `location` pro všechny prostředky, které ho explicitně nezadávají.
`default_tags`	Nastaví výchozí značky pro všechny zdroje. Na úrovni `tags` prostředků přebíjí tyto výchozí hodnoty.
`skip_provider_registration`	Přeskočí automatickou registraci poskytovatele prostředků. Nastavte na `true` v omezených prostředích.

Úplný seznam možností konfigurace poskytovatele najdete v schématu zprostředkovateleAzAPI.

Návod k povolení předběžné kontroly najdete v tématu Povolení předběžného ověření ve zprostředkovateli AzAPI Terraform.

Funkce zprostředkovatele

AzAPI verze 2.0 a novější obsahuje několik funkcí poskytovatele:

Název funkce	Popis
`build_resource_id`	Konstruuje ID prostředku Azure na základě nadřazeného ID, typu prostředku a názvu prostředku. Užitečné při vytváření ID prostředků pro prostředky nejvyšší úrovně a vnořené prostředky v rámci určitého oboru.
`extension_resource_id`	Vytvoří ID prostředku rozšíření Azure na základě ID základního prostředku, typu prostředku a dalších názvů prostředků.
`management_group_resource_id`	Vytvoří ID prostředku v rozsahu management skupiny Azure uvedením názvu skupiny, typu prostředku a názvů prostředků.
`parse_resource_id`	Tato funkce přebírá ID prostředku Azure a typ prostředku a rozloží ID na jednotlivé komponenty, jako jsou ID předplatného, název skupiny prostředků, obor názvů poskytovatele a další části.
`resource_group_resource_id`	Vytvoří ID prostředku pro obor působnosti skupiny prostředků Azure na základě zadaného ID předplatného, názvu skupiny prostředků, typu prostředku a názvů prostředků.
`subscription_resource_id`	Vytvoří ID prostředku na úrovni předplatného Azure na základě ID předplatného, typu prostředku a názvů prostředků.
`tenant_resource_id`	Vytvoří ID prostředku prostředí tenanta Azure na základě typu prostředku a názvů prostředků.

Uživatelem definované opakovaně použitelné chyby s blokem `retry`

Zprostředkovatel AzAPI zpracovává očekávané chyby prostřednictvím retry bloku. Použijte následující konfiguraci pro opakování akce, pokud prostředek narazí na vypršení časového limitu při vytváření.

resource "azapi_resource" "example" {
    # usual properties
    retry {
        interval_seconds     = 5
        randomization_factor = 0.5 # adds randomization to retry pattern
        multiplier           = 2 # if try fails, multiplies time between next try by this much
        error_message_regex  = ["ResourceNotFound"]
    }
    timeouts {
        create = "10m"
}

Blok retry přijímá tyto atributy:

Attribute	Popis
`error_message_regex`	Required. Seznam regulárních výrazů odpovídajících chybovým zprávám Požadavek je opakovaně proveden, když se jakýkoliv výraz shoduje.
`interval_seconds`	Doba základního čekání mezi opakovanými pokusy. Výchozí hodnota je `10`.
`max_interval_seconds`	Maximální doba čekání mezi opakovanými pokusy. Výchozí hodnota je `180`.
`multiplier`	Násobitel, který se použije na interval po každém neúspěšném pokusu. Výchozí hodnota je `1.5`.
`randomization_factor`	Přidá náhodnost do intervalu opakování, aby nedocházelo k jevům nárazového zatížení. Výchozí hodnota je `0.5`.

Zkombinujte retry s blokem timeouts a nastavte horní mez celkové doby trvání opakování:

timeouts {
  create = "10m"
}

Dočasné prostředky a vlastnosti jen pro zápis

AzAPI v2.x podporuje argumenty jen pro zápis (Terraform 1.11 a novější) prostřednictvím atributu sensitive_body on azapi_resource. Vlastnosti jen pro zápis se odesílají do rozhraní API ARM, ale nejsou uložené ve stavu Terraformu, což je užitečné pro tajné kódy a přihlašovací údaje:

resource "azapi_resource" "example" {
  type      = "Microsoft.SomeService/resources@2024-01-01"
  name      = "example"
  parent_id = azurerm_resource_group.example.id

  body = {
    properties = {
      name = "example"
    }
  }

  # Write-only — not stored in state
  sensitive_body = {
    properties = {
      adminPassword = var.admin_password
    }
  }
}

Sloužte sensitive_body_version k tomu, abyste určovali, kdy se vlastnosti určené pouze pro zápis znovu odesílají do rozhraní API (například při rotaci přihlašovacích údajů).

Spouštěče pro výměnu zdrojů

Poskytovatel AzAPI umožňuje konfigurovat parametry nahrazování zdrojů.

`replace_triggers_external_values`

Nahradí prostředek, pokud se hodnota změní. Pokud by se například změnily proměnné skladové položky nebo zóny, tento prostředek by se znovu vytvořil:

resource "azapi_resource" "example" {
  name      = var.name
  type      = "Microsoft.Network/publicIPAddresses@2023-11-01"
  parent_id = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/example"
  body      = properties = {
    sku   = var.sku
    zones = var.zones
  }
  replace_triggers_external_values = [
    var.sku,
    var.zones,
  ]
}

Tento trigger funguje v široké sadě prostředků – například přiřazení zásad při změně vlastností definice.

`replace_triggers_refs`

Nahradí prostředek, pokud se odkazovaná hodnota změní. Pokud se například změnil název skladové položky nebo úroveň, tento prostředek by se znovu vytvořil:

resource "azapi_resource" "example" {
  type      = "Microsoft.Relay/namespaces@2021-11-01"
  parent_id = azurerm_resource_group.example.id
  name      = "xxx"
  location  = "westus"
  body = {
    properties = {
    }
    sku = {
      name = "Standard"
      tier = "Standard"
    }
  }

  replace_triggers_refs = ["sku"]
}

Toto by nespustilo nahrazení, pokud se změní SKU jiného prostředku.

Další kroky

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-05-06