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, como 2026-02-01. Las versiones preliminares agregan un sufijo -preview, como 2026-03-01-preview. https://management.azure.com
Plano de datos Objetos dentro de un almacén: claves, secretos, certificados y operaciones criptográficas. Basado en fechas, como 2026-04-01, o numérico, como 7.6. Las versiones preliminares agregan un sufijo, como 2026-03-01-preview o 7.6-preview.2. 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.

Dado que ambas superficies usan versiones basadas en fechas, una cadena de versión por sí sola no identifica la superficie. Por ejemplo, tanto el plano de control como el plano de datos tienen una versión 2026-03-01-preview.

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.

Identificación de llamadas API afectadas mediante registros

Un aviso de servicio no significa necesariamente que la telemetría detectó una versión de API de retirada en cada suscripción o Key Vault que posee. Los avisos pueden llegar a un público más amplio que los recursos detectados en la telemetría reciente.

Use los registros de auditoría de Key Vault para buscar qué almacenes de claves y operaciones usaron una versión de API en proceso de retirada. A continuación, busque dónde su código, las plantillas o las herramientas establecen esa versión, tal como se describe en Buscar referencias de versión de API en el código y los flujos de trabajo, y actualice la versión de la API.

Recopilación de registros de auditoría de Key Vault

Envíe los registros de auditoría de cada Key Vault que quiera investigar a un área de trabajo de Log Analytics. Para ver los pasos, consulte Habilitar el registro de Key Vault. Para configurar muchos almacenes de claves a la vez, consulte Crear opciones de diagnóstico a escala mediante Azure Policy integrada. Use un espacio de trabajo para estos almacenes de claves para poder consultarlos juntos.

Configure el registro desde el principio. Los registros incluyen solo las solicitudes realizadas después de que la configuración de diagnóstico surte efecto, y las solicitudes anteriores no se completan retroactivamente. Después de crear una configuración de diagnóstico, los datos pueden tardar hasta 90 minutos en aparecer. Para obtener más información, consulte Latencia esperada después de crear una configuración de diagnóstico.

Los eventos de auditoría incluyen las operaciones del plano de control y del plano de datos, pero esta retirada afecta solo a las operaciones del plano de control.

El registro de actividad de Azure no registra la versión de api de una solicitud, por lo que use los registros de auditoría de Key Vault para buscar solicitudes que usan una versión que se va a retirar.

Para confirmar que llegan los registros, ejecute la consulta siguiente en el área de trabajo. Para obtener más información sobre la ejecución de consultas, consulte Log Analytics tutorial.

AzureDiagnostics
| where TimeGenerated >= ago(30d)
| where ResourceProvider =~ "MICROSOFT.KEYVAULT"
| where Category == "AuditEvent"
| order by TimeGenerated desc
| take 50

Compruebe _ResourceId y TimeGenerated para confirmar que los registros llegan desde los almacenes de claves previstos. Para comprobar un almacén de claves que no está en las 50 filas más recientes, filtre por _ResourceId antes de order by.

Si falta una tabla o la consulta no devuelve ningún registro, vuelva a comprobar el área de trabajo, la configuración de diagnóstico guardada, el almacén de claves de origen, el ámbito de la consulta, el intervalo de tiempo y los permisos. Si la configuración de diagnóstico envía registros a tablas específicas de recursos, consulte la AZKVAuditLogs tabla en su lugar, como se describe al final de la sección siguiente.

Buscar solicitudes que usan una versión de API en retirada

Importante

Los registros incluyen solo las solicitudes que recibe un almacén de claves mientras su configuración de diagnóstico está activa y solo dentro del intervalo de tiempo que consulta. Si las consultas no devuelven solicitudes coincidentes, eso no significa que no esté afectado. Por ejemplo, los registros no muestran las solicitudes que crearon Key Vault hace años, incluso si las plantillas o scripts que crearon esos Key Vault todavía especifican una versión en proceso de retirada. Revise siempre el código de la aplicación, las plantillas de implementación, los scripts de automatización y otros flujos de trabajo para ver las referencias a una versión de API de retirada.

Las consultas siguientes solo devuelven solicitudes del plano de control filtrando por el punto de conexión de Azure Resource Manager en el URI de solicitud. Las solicitudes del plano de datos van al punto de conexión del almacén en su lugar, como https://<vault-name>.vault.azure.net. Las consultas usan el punto de conexión para la nube pública de Azure. En el caso de otras nubes, reemplace https://management.azure.com/ por el punto de conexión de su nube:

Cloud punto de conexión de Azure Resource Manager
Nube pública de Azure https://management.azure.com/
Azure Government https://management.usgovcloudapi.net/
Azure operado por 21Vianet https://management.chinacloudapi.cn/

Otras nubes usan su propio punto de conexión de Azure Resource Manager.

Las consultas filtran en el punto de conexión porque algunas versiones de API del plano de datos usan el mismo formato basado en fechas que las versiones del plano de control. Por ejemplo, el plano de datos también tiene una 2026-03-01-preview versión. Para conocer los nombres de operación que registra Key Vault, consulte tabla Nombres de operación.

Para enumerar los almacenes de claves que recibieron solicitudes del plano de control con una versión de API anterior a 2026-02-01, ejecute la consulta siguiente. Devuelve una fila para cada almacén de claves y versión de API, con el número de solicitudes, la solicitud más reciente y las operaciones solicitadas.

AzureDiagnostics
| where TimeGenerated >= ago(30d)
| where ResourceProvider =~ "MICROSOFT.KEYVAULT"
| where Category == "AuditEvent"
| where requestUri_s startswith "https://management.azure.com/"
| where strcmp(OperationVersion, "2026-02-01") < 0
| summarize Requests = count(), LastSeen = max(TimeGenerated), Operations = make_set(OperationName) by _ResourceId, OperationVersion
| order by Requests desc

Para investigar solicitudes individuales, use una de las siguientes consultas.

Para buscar solicitudes que usan una versión de retirada específica, como 2026-03-01-preview, filtre por esa versión:

AzureDiagnostics
| where TimeGenerated >= ago(30d)
| where ResourceProvider =~ "MICROSOFT.KEYVAULT"
| where Category == "AuditEvent"
| where requestUri_s startswith "https://management.azure.com/"
| where OperationVersion == "2026-03-01-preview"
| order by TimeGenerated desc

Para buscar solicitudes que usen cualquier versión de API del plano de control anterior a 2026-02-01, filtre por versiones que ordenan antes 2026-02-01de :

AzureDiagnostics
| where TimeGenerated >= ago(30d)
| where ResourceProvider =~ "MICROSOFT.KEYVAULT"
| where Category == "AuditEvent"
| where requestUri_s startswith "https://management.azure.com/"
| where strcmp(OperationVersion, "2026-02-01") < 0
| order by TimeGenerated desc

Las consultas de este artículo usan la tabla AzureDiagnostics, que recibe registros de auditoría de Key Vault cuando la tabla de destino de la configuración de diagnóstico es Azure diagnostics. Si la tabla de destino es específica del recurso, los registros de auditoría van a la AZKVAuditLogs tabla en su lugar. En ese caso, ajuste cada consulta de este artículo, incluida la comprobación de recopilación: reemplace AzureDiagnostics por ResourceProvider, quite los filtros Category y RequestUri, y reemplace requestUri_s por AZKVAuditLogs. Por ejemplo, la consulta de almacenes de claves afectada se convierte en:

AZKVAuditLogs
| where TimeGenerated >= ago(30d)
| where RequestUri startswith "https://management.azure.com/"
| where strcmp(OperationVersion, "2026-02-01") < 0
| summarize Requests = count(), LastSeen = max(TimeGenerated), Operations = make_set(OperationName) by _ResourceId, OperationVersion
| order by Requests desc

No filtre por los nombres de operación que empiecen por Vault, ya que ese filtro puede excluir las operaciones de recursos secundarios registrados. Use OperationName y el URI de solicitud para comprender qué operación de administración se ha producido. Usa los detalles de estos registros para identificar quién realiza la llamada. A continuación, busque dónde el componente que realiza la llamada establece la versión de la API, tal como se describe en la sección siguiente, y actualícela como se describe en Actualizar la versión de la API.

Busque referencias a la versión de API en el código y los flujos de trabajo

La ubicación en la que establece la versión de la API depende de cómo llame a Key Vault. Compruebe cada método que use la carga de trabajo, incluso si los registros no muestran ninguna solicitud de él.

Plano de control (administración)

  • API REST: la versión es el api-version parámetro de cadena de consulta en las solicitudes a https://management.azure.com, por ejemplo ?api-version=<control-plane-version>.
  • Plantillas de ARM y archivos Bicep: 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'. Los recursos secundarios, como Microsoft.KeyVault/vaults/secrets, Microsoft.KeyVault/vaults/keysy Microsoft.KeyVault/vaults/accessPolicies también son recursos del plano de control, y cada uno declara su propia versión de API. La actualización de la versión del almacén primario no actualiza sus recursos secundarios.
  • Terraform: con el proveedor AzAPI, la versión forma parte del tipo de recurso, por ejemplo Microsoft.KeyVault/vaults@2026-02-01. Con el proveedor azureRM, la versión del proveedor determina la versión de la API y los recursos no tienen una configuración de versión de API. Consulte las notas de la versión del proveedor y la documentación del recurso para conocer la versión de API que usa la versión de su proveedor.
  • 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 usa la versión 2026-02-01 de API, por lo que las operaciones del portal no usan una versión en proceso de retirada. 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

  • API REST: la versión es el api-version parámetro de cadena de consulta en las solicitudes al punto de conexión del almacén, 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.

Actualización de la versión de la API

Actualización de la versión de la API del plano de control

  1. Actualice la versión de la API en las plantillas y las llamadas REST. Establezca apiVersion (ARM, Bicep), el tipo de recurso con versiones (Terraform AzAPI) o el api-version parámetro de cadena de consulta (REST) en una versión del plano de control compatible actualmente. Actualice todas las Microsoft.KeyVault/vaults definiciones, sus recursos secundarios y las solicitudes de administración. Si usa el proveedor de AzureRM de Terraform, actualice el proveedor a una versión que use una versión de API del plano de control compatible.

  2. Actualice los SDK de administración del plano de control. Consulte las notas de la versión del paquete y la referencia de la API para la versión del paquete compatible con la versión de la API del plano de control que haya seleccionado. Para obtener referencias de API por idioma y las versiones de paquete que admiten la versión actual del plano de control de Key Vault, consulte Azure Key Vault bibliotecas cliente y versiones del SDK del plano de control.

    Note

    La actualización de un SDK de administración del plano de control no actualiza los SDK del plano de datos. Actualice cada SDK por separado si la aplicación usa ambas superficies de API.

  3. Actualice CLI de Azure y Azure PowerShell. Las versiones más recientes de las herramientas invocan versiones más recientes de la API.

    Actualice la CLI de Azure a la versión más reciente. Para obtener más información, vea How to update the CLI de Azure.


  1. Revise los cambios de comportamiento antes de implementar. Lea el registro de cambios y la especificación de la versión de la API antes de realizar la implementación. La versión 2026-02-01 de la API y posteriores modifican el modelo de control de acceso predeterminado solo para los nuevos KeyStores. Para obtener más información, consulte Planear Azure RBAC como modelo de control de acceso predeterminado en Key Vault.

Actualizar la versión de la API del plano de datos

  1. Actualice la versión de la API en las llamadas REST. Configure el parámetro de cadena de consulta api-version con una versión del plano de datos admitida actualmente que figura en la referencia de la API REST de Azure Key Vault.

  2. Actualice los SDK del plano de datos. Actualice los Azure.Security.KeyVault.* paquetes (o equivalentes para el idioma) a una versión estable actual. Compruebe las notas de la versión del paquete y la referencia de API para determinar qué versiones de API del plano de datos admite el paquete. Para obtener referencias de API y vínculos de paquetes por idioma, consulte Azure Key Vault bibliotecas cliente.

Las versiones estables de la API del plano de datos no se ven afectadas por la retirada actual del plano de control. Si usa una API de plano de datos en versión preliminar, revise los anuncios del servicio y la referencia de API para su ciclo de vida.

Para obtener más información sobre cómo llamar a la API REST del plano de datos, consulte Autenticación, solicitudes y respuestas y la referencia de la API rest de Azure Key Vault.