Actualización de la versión de la API de Azure Key Vault que usa

Azure Key Vault usa API con versiones. Si las aplicaciones, scripts o plantillas de infraestructura llaman a una versión anterior de la API, es posible que pierda características más recientes, use el comportamiento que ha cambiado en una versión posterior o dependa de una versión que ya no se recomienda. En este artículo se explica cómo determinar qué versión de API usa y cómo pasar a una versión compatible actual.

Importante

Todas las versiones de API del plano de control de Key Vault anteriores a 2026-02-01 se retirarán el 27 de febrero de 2027. Después de esa fecha, sus almacenes de claves seguirán existiendo, pero solo podrá administrarlos con la versión 2026-02-01 o posterior de la API del plano de control. No hay ninguna excepción ni extensión a esta fecha. Esta retirada no afecta a las API del plano de datos (las API que se usan para trabajar con claves, secretos y certificados). Para obtener más información, consulte Planear Azure RBAC como modelo de control de acceso predeterminado en Key Vault.

Azure Key Vault tiene dos superficies de API independientes, cada una con sus propias versiones:

Superficie de la API	Lo que administra	Esquema de versión	Punto de conexión de ejemplo
Plano de control (administración)	El recurso del almacén de claves en sí: crear, actualizar y eliminar almacenes, y configurar propiedades como SKU, reglas de red y control de acceso.	Basado en fechas (`{YYYY}-{MM}-{DD}`)	`https://management.azure.com`
Plano de datos	Objetos dentro de un almacén: claves, secretos, certificados y operaciones criptográficas.	Basado en fechas (`{YYYY}-{MM}-{DD}`)	`https://<vault-name>.vault.azure.net`

Las dos interfaces tienen prácticas distintas de control de versiones y de ciclo de vida. La actualización de una no actualiza la otra. Revise los dos si su carga de trabajo utiliza ambos.

Las versiones de la API del plano de control se pueden retirar, como se ha descrito anteriormente en este artículo.

Las versiones preliminares de la API del plano de datos se pueden dejar de usar, por lo que no use versiones preliminares en producción a menos que acepte ese ciclo de vida. Para consultar las versiones compatibles de la API del plano de datos, consulte la referencia de la API REST de Azure Key Vault.

Este artículo se centra en identificar y actualizar versiones de API. La actualización de una versión de API del plano de control no requiere migrar un almacén de claves existente de directivas de acceso a Azure RBAC. Si desea migrar el control de acceso, consulte Migración a Azure RBAC desde directivas de acceso. Para obtener el comportamiento predeterminado de RBAC de Azure introducido para los nuevos almacenes de claves en la versión 2026-02-01 de la API y versiones posteriores, consulte Planear Azure RBAC como modelo de control de acceso predeterminado en Key Vault.

¿Por qué pasar a una versión de API actual?

Use las funcionalidades admitidas. Las versiones de API más recientes pueden agregar funcionalidades, comportamiento correcto o admitir nuevas características de servicio.
Mantenga estables las cargas de trabajo de producción. Use una versión de API estable actual para cargas de trabajo de producción. Las versiones preliminares de la API son para la evaluación y las primeras pruebas, y es posible que Soporte técnico de Azure SLA no las cubran. Las versiones preliminares pueden quedar en desuso.
Mantener las herramientas y bibliotecas compatibles. CLI de Azure, Azure PowerShell, SDK, plantillas y el portal pueden usar diferentes versiones de API. La actualización de la versión de un cliente no actualiza las demás.

Para ver las versiones actuales del plano de control, consulte Versiones de API del plano de control compatibles. Para consultar las versiones admitidas del plano de datos, consulte la referencia de la API REST de Azure Key Vault.

Determinación de la versión de API que usa

Especifique la versión de la API de forma diferente en función de cómo llame a Key Vault. Compruebe cada superficie que utiliza su carga de trabajo.

Plano de control (administración)

REST API: La versión se especifica mediante el parámetro de cadena de consulta api-version en las peticiones a https://management.azure.com, por ejemplo ?api-version=<control-plane-version>.
Plantillas de ARM, Bicep y Terraform: La versión es la propiedad apiVersion de cada recurso Microsoft.KeyVault/vaults. En Bicep, forma parte de la declaración de tipo de recurso, por ejemploresource kv 'Microsoft.KeyVault/vaults@2026-02-01'.
SDK de administración del plano de control: la versión del paquete puede determinar qué versiones de API admite un SDK, pero la versión del paquete por sí sola no siempre identifica la versión de API usada por una solicitud. Compruebe las notas de la versión del paquete y la referencia de API (por ejemplo, para Azure.ResourceManager.KeyVault o azure-mgmt-keyvault) y compárelas con la versión del paquete en el manifiesto de dependencia del proyecto. Para obtener referencias de API por lenguaje, consulte Azure Key Vault bibliotecas cliente.
CLI de Azure y Azure PowerShell: la versión de la CLI de Azure o Az el módulo determina la versión de la API. Compruebe la versión instalada con az version o Get-InstalledModule -Name Az.
Azure portal: el portal selecciona la versión de la API del plano de control para sus solicitudes. No se puede establecer esa versión directamente. El portal puede usar una versión de API diferente a las plantillas, scripts o SDK, por lo que no use el comportamiento del portal para determinar la versión usada por la automatización.
Azure Cloud Shell: Cloud Shell usa las versiones actuales de CLI de Azure y Azure PowerShell. Si ejecuta scripts en Cloud Shell, asegúrese de que son compatibles con la versión de API del plano de control compatible actualmente.

Plano de datos

REST API: La versión es el parámetro api-version de la cadena de consulta en las solicitudes al endpoint del vault, por ejemplo GET https://<vault-name>.vault.azure.net/secrets/<name>?api-version=<data-plane-version>.
SDK del plano de datos: la versión del paquete puede determinar qué versiones de API admite un SDK, pero la versión del paquete por sí sola no siempre identifica la versión de API usada por una solicitud. Compruebe las notas de la versión del paquete y la referencia de API (por ejemplo, para Azure.Security.KeyVault.Secrets, Azure.Security.KeyVault.Keyso Azure.Security.KeyVault.Certificates) y compárelas con la versión del paquete en el manifiesto de dependencia del proyecto. Para obtener referencias de API por lenguaje, consulte Azure Key Vault bibliotecas cliente.