Compartir vía

Uso de valores con nombre en las directivas de Azure API Management

SE APLICA A: Todos los niveles de API Management

Las directivas de API Management constituyen una eficaz funcionalidad del sistema que permite al editor cambiar el comportamiento de la API a través de la configuración. Las directivas son una colección de declaraciones que se ejecutan secuencialmente en la solicitud o respuesta de una API. Las instrucciones de las directivas se pueden crear con valores de texto literal, expresiones de directiva y valores con nombre.

Los valores con nombre son una colección global de pares nombre-valor en cada instancia de API Management. Puede usar valores con nombre para administrar los valores de cadena constante y los secretos en todas las configuraciones y directivas de API.

Valores con nombre en Azure Portal

Tipos de valor

Tipo Descripción
Normal Cadena literal o expresión de directiva
Secreto Expresión de directiva o cadena literal cifrada por API Management
Almacén de claves Identificador de un secreto almacenado en una instancia de Azure Key Vault.

Los valores normales o los secretos pueden contener expresiones de directiva. Por ejemplo, la expresión @(DateTime.Now.ToString()) devuelve una cadena que contiene la fecha y la hora actuales.

Para obtener más información sobre los atributos de los valores con nombre, consulte la referencia de la API REST de API Management.

Secretos de un almacén de claves

Los valores de los secretos se pueden almacenar como cadenas cifradas en API Management (secretos personalizados) o mediante referencia a secretos en Azure Key Vault.

Se recomienda usar secretos del almacén de claves porque ayudan a mejorar la seguridad API Management:

Nota

Actualmente, la integración con el almacén de claves para este escenario no está disponible en las áreas de trabajo.

  • Puede reutilizar secretos almacenados en almacenes de claves entre servicios.
  • Puede aplicar directivas de acceso pormenorizadas a secretos.
  • Los secretos actualizados en el almacén de claves se rotan automáticamente en API Management. Después de actualizar en Azure Key Vault, un valor con nombre en API Management de Azure se actualiza dentro de un plazo de cuatro horas. También puede actualizar manualmente el secreto mediante Azure Portal o a través de la API REST de administración.

Nota

Los secretos almacenados en Azure Key Vault deben tener entre 1 y 4096 caracteres, ya que API Management no puede recuperar valores que superen este límite.

Requisitos previos

Requisitos previos para la integración de un almacén de claves

Nota

Actualmente, esta característica no está disponible en las áreas de trabajo.

Configuración del acceso al almacén de claves

  1. En el portal, vaya al almacén de claves.
  2. En el menú de la izquierda, seleccione Configuración>de acceso. Tenga en cuenta el modelo de permisos configurado.
  3. En función del modelo de permisos, configure una directiva de acceso al almacén de claves o el acceso de Azure RBAC para una identidad administrada de API Management.

Para agregar una directiva de acceso del almacén de claves:

  1. En el menú de la izquierda, seleccione Directivas de acceso.
  2. En la página Directivas de acceso, seleccione + Crear.
  3. En la pestaña Permisos , en Permisos secretos, seleccione Obtener y enumerar y, a continuación, seleccione Siguiente.
  4. En la pestaña Principal, busque el nombre del recurso de su identidad administrada y, a continuación, seleccione Siguiente. Si usa una identidad asignada por el sistema, la entidad de seguridad es el nombre de la instancia de API Management.
  5. Seleccione Siguiente de nuevo. En la pestaña Revisar y crear, seleccione Crear.

Para configurar el acceso de Azure RBAC:

  1. En el menú izquierdo, seleccione Control de acceso (IAM).
  2. En la página Control de acceso (IAM), seleccione Agregar asignación de roles.
  3. En la pestaña Rol , seleccione Usuario de secretos de Key Vault y, a continuación, seleccione Siguiente.
  4. En la pestaña Miembros, seleccione Identidad administrada>+Seleccionar miembros.
  5. En la página Seleccionar identidad administrada, seleccione la identidad administrada asignada por el sistema o una identidad administrada asignada por el usuario asociada a la instancia de API Management y, después, seleccione Seleccionar.
  6. Seleccione Revisar y asignar.

Requisitos de firewall de Key Vault

Si el firewall de Key Vault está habilitado en el almacén de claves, debe cumplir estos requisitos:

  • Debe usar la identidad administrada asignada por el sistema de la instancia de API Management para acceder al almacén de claves.

  • Asegúrese de que la instancia de API Management tenga conectividad de red hacia el almacén de claves. En función de los escenarios, configure una de las siguientes opciones de acceso de red en el almacén de claves:

    • Permitir el acceso público desde todas las redes.

    • Establezca una regla de seguridad de red para permitir el tráfico de API Management en función de la dirección IP o la conectividad de red virtual.

    • Proteja el tráfico de API Management con conectividad de Private Link.

    • Use un perímetro de seguridad de red para proteger el almacén de claves y permitir el tráfico desde API Management.

  • Asegúrese de que la dirección IP del cliente local tenga permiso para acceder al almacén de claves temporalmente mientras selecciona un certificado o secreto para agregar a Azure API Management. Para obtener más información, vea Configurar redes de Azure Key Vault.

    Después de completar la configuración, puede bloquear la dirección del cliente en el firewall del almacén de claves.

Importante

A partir de marzo de 2026, la conectividad de servicios de confianza a Azure Key Vault desde API Management al habilitar la configuración de firewall Permitir que los servicios de Microsoft de confianza omitan este firewall ya no será admitida. Para seguir usando Key Vault con API Management después de este cambio, asegúrese de elegir una opción de acceso de red compatible como se ha descrito anteriormente. Más información.

Requisitos de red virtual

Si la instancia de API Management se ha implementado en una red virtual, configure también las siguientes opciones de red:

Para más información, consulte Configuración de red al configurar API Management en una red virtual.

Adición o edición de un valor con nombre

Agregar un secreto del almacén de claves a API Management

Consulte Requisitos previos para la integración de un almacén de claves.

Importante

Al agregar un secreto de almacén de claves a la instancia de API Management, debe tener permisos para enumerar los secretos del almacén de claves.

Precaución

Al usar un secreto del almacén de claves en API Management, tenga cuidado de no eliminar el secreto, el almacén de claves ni la identidad administrada que se usa para acceder al almacén de claves.

  1. Vaya a la instancia de API Management en Azure Portal.

  2. En API, seleccione Valores con nombre>+ Agregar.

  3. Escriba un identificador de Nombre y escriba un Nombre para mostrar que se use para hacer referencia a la propiedad en las directivas.

  4. Agregue una o varias etiquetas opcionales para ayudar a organizar los valores nombrados.

  5. En la lista desplegable Tipo , seleccione Almacén de claves.

  6. Escriba el identificador de un secreto de almacén de claves (sin versión) o elija Seleccionar para seleccionar un secreto de un almacén de claves.

    Importante

    Si especifica usted mismo el identificador de un secreto del almacén de claves, asegúrese de que no tenga la información de versión. De lo contrario, el secreto no se rotará automáticamente en API Management después de una actualización en el almacén de claves.

  7. En Client identity (Identidad del cliente), seleccione una identidad asignada por el sistema o una identidad administrada existente asignada por el usuario. Obtenga información sobre cómo agregar o modificar identidades administradas en el servicio de API Management.

    Nota

    La identidad necesita permisos para obtener y enumerar los secretos del almacén de claves. Si aún no ha configurado el acceso al almacén de claves, API Management se lo pedirá para poder configurar automáticamente la identidad con los permisos necesarios.

  8. Seleccione Guardar y, a continuación, seleccione Crear.

    Añadir un valor de secreto del almacén de claves

Agregar un valor normal o secreto a API Management

  1. Vaya a la instancia de API Management en Azure Portal.
  2. En API, seleccione Calores con nombre>+Agregar.
  3. Escriba un identificador de Nombre y escriba un Nombre para mostrar que se use para hacer referencia a la propiedad en las directivas.
  4. En la lista desplegable Tipo , seleccione Sin formato o Secreto.
  5. En Valor, escriba una cadena o expresión de directiva.
  6. Agregue una o varias etiquetas opcionales para ayudar a organizar los valores con nombre y, a continuación, elija Guardar.
  7. Seleccione Crear.

Una vez creado el valor con nombre, selecciónelo para editarlo. Si cambia el nombre para mostrar, las directivas que hagan referencia a ese valor con nombre se actualizarán automáticamente para utilizar el nuevo nombre para mostrar.

Uso de un valor con nombre

En los ejemplos de esta sección se usan los valores con nombre que aparecen en la tabla siguiente.

Nombre Valor Secreto
ContosoHeader TrackingId Falso
ContosoHeaderValue •••••••••••••••••••••• Verdadero
ExpressionProperty @(DateTime.Now.ToString()) Falso
ContosoHeaderValue2 This is a header value. Falso

Para utilizar un valor con nombre en una directiva, coloque su nombre para mostrar dentro de un par doble de llaves (como {{ContosoHeader}}), de la misma forma que se muestra en el ejemplo siguiente:

<set-header name="{{ContosoHeader}}" exists-action="override">
  <value>{{ContosoHeaderValue}}</value>
</set-header>

En este ejemplo, ContosoHeader se utiliza como el nombre de un encabezado en una directiva set-header, y ContosoHeaderValue se utiliza como valor de ese encabezado. Cuando esta directiva se evalúa durante una solicitud o responde a la pasarela de API Management, {{ContosoHeader}} y {{ContosoHeaderValue}} se reemplazan por sus respectivos valores.

Puede usar valores con nombre como atributos completos o valores de elemento como se muestra en el ejemplo anterior, pero también se pueden insertar en o combinar con parte de una expresión de texto literal, como se muestra en el ejemplo siguiente:

<set-header name = "CustomHeader{{ContosoHeader}}" ...>

Los valores con nombre también pueden contener expresiones de directiva. En el ejemplo siguiente, se usa la expresión ExpressionProperty.

<set-header name="CustomHeader" exists-action="override">
    <value>{{ExpressionProperty}}</value>
</set-header>

Cuando se evalúa esta directiva, se reemplaza {{ExpressionProperty}} por su valor, @(DateTime.Now.ToString()). Dado que el valor es una expresión de directiva, la expresión se evalúa y la directiva continúa con su ejecución.

Para probarlo en Azure Portal o en el portal para desarrolladores, puede llamar a una operación que tenga dentro de su ámbito una directiva con valores con nombre. En el ejemplo siguiente, se llama a una operación con las dos directivas set-header de ejemplo anteriores con valores con nombre. Tenga en cuenta que la respuesta contiene dos encabezados personalizados que se han configurado mediante directivas con valores con nombre.

Captura de pantalla de una respuesta de api de prueba.

Si busca en el seguimiento de API de salida una llamada que incluya las dos directivas de ejemplo anteriores con valores con nombre, verá las dos directivas set-header con los valores con nombre insertados, así como la evaluación de la expresión de directiva para el valor con nombre que la contiene.

Captura de pantalla de un seguimiento de API Inspector.

También puede usar la interpolación de cadenas con valores nombrados.

<set-header name="CustomHeader" exists-action="override">
    <value>@($"The URL encoded value is {System.Net.WebUtility.UrlEncode("{{ContosoHeaderValue2}}")}")</value>
</set-header>

El valor de CustomHeader será The URL encoded value is This+is+a+header+value..

Precaución

Si una directiva hace referencia a un secreto en Azure Key Vault, el valor del almacén de claves es visible para los usuarios que tienen acceso a las suscripciones habilitadas para el seguimiento de solicitudes de API.

Aunque los valores con nombre pueden contener expresiones de directiva, no pueden contener otros valores con nombre. En caso de usarse texto que contenga una referencia a valores con nombre para un valor, como Text: {{MyProperty}}, dicha referencia no se resolverá ni reemplazará.

Eliminación de un valor con nombre

Para eliminar un valor con nombre, seleccione el nombre y, a continuación, seleccione Eliminar en el menú contextual (...).

Importante

Si alguna directiva de API Management hace referencia al valor con nombre, no podrá eliminarlo hasta que lo quite de todas las directivas que lo usen.

Contenido relacionado

Aprenda más sobre cómo trabajar con políticas:

  • Last updated on