Exploración de directivas de API Management

Completado

En Azure API Management, las directivas permiten al publicador 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 directivas se aplican en la puerta de enlace que se encuentra entre el consumidor de la API y la API administrada. La puerta de enlace recibe todas las solicitudes y normalmente las reenvía sin modificar a la API subyacente. Sin embargo, una directiva puede aplicar cambios a la solicitud de entrada y a la respuesta de salida. Las expresiones de directiva pueden utilizarse como valores de atributos o valores de texto en cualquiera de las directivas de API Management, a menos que la directiva especifique lo contrario.

Descripción de la configuración de directivas

La definición de la directiva es un documento XML simple que describe una secuencia de declaraciones de entrada y de salida. El XML se puede editar directamente en la ventana de definición.

La configuración se divide en inbound, backend, outbound y on-error. La serie de instrucciones de una directiva determinada se ejecuta en orden para una solicitud y una respuesta.

<policies>
  <inbound>
    <!-- statements to be applied to the request go here -->
  </inbound>
  <backend>
    <!-- statements to be applied before the request is forwarded to 
         the backend service go here -->
  </backend>
  <outbound>
    <!-- statements to be applied to the response go here -->
  </outbound>
  <on-error>
    <!-- statements to be applied if there is an error condition go here -->
  </on-error>
</policies>

Si se produce un error durante el procesamiento de una solicitud, los pasos restantes de las secciones inbound, backend o outbound se omiten y la ejecución salta a las instrucciones de la sección on-error. Mediante la colocación de instrucciones de directiva en la sección on-error puede revisar el error con la propiedad context.LastError, inspeccionar y personalizar la respuesta de error con la directiva set-body y configurar lo que ocurre si se produce un error.

Expresiones de directiva

Salvo que la directiva especifique lo contrario, las expresiones de directiva pueden utilizarse como valores de atributo o valores de texto en cualquiera de las directivas de API Management. Una expresión de directiva es:

• una sola instrucción de C# incluida en @(expression), o
• un bloque de código de C# de varias instrucciones incluido en @{expression}, que devuelve un valor.

Cada expresión tiene acceso a la variable de context proporcionada de forma implícita y a un subconjunto permitido de tipos de .NET Framework.

Las expresiones de directiva proporcionan un medio sofisticado para controlar el tráfico y modificar el comportamiento de la API sin necesidad de escribir código especializado ni modificar servicios back-end.

En el ejemplo siguiente se usan expresiones de directiva y la directiva set-header para agregar datos de usuario a la solicitud entrante. El encabezado agregado incluye el identificador de usuario asociado a la clave de suscripción en la solicitud y la región donde se hospeda la puerta de enlace que procesa la solicitud.

<policies>
    <inbound>
        <base />
        <set-header name="x-request-context-data" exists-action="override">
            <value>@(context.User.Id)</value>
            <value>@(context.Deployment.Region)</value>
      </set-header>
    </inbound>
</policies>

Aplicación de las directivas especificadas en distintos ámbitos

Si tiene una directiva de nivel global y una directiva configurada para una API, cuando se use esa API específica, se aplican ambas directivas. Administración de API tiene en cuenta el orden determinista de declaraciones de directiva combinadas mediante el elemento base.

<policies>
    <inbound>
        <cross-domain />
        <base />
        <find-and-replace from="xyz" to="abc" />
    </inbound>
</policies>

En la definición de directiva de ejemplo anterior, la instrucción cross-domain se ejecutaría primero. La directiva find-and-replace se ejecuta después de cualquier directiva en un ámbito más amplio.

Filtro de contenido de respuestas

La directiva definida en el ejemplo siguiente muestra cómo filtrar los elementos de datos de la carga de respuesta en función del producto asociado a la solicitud.

El fragmento de código supone que el contenido de la respuesta tiene el formato JSON y contiene propiedades de nivel raíz denominadas "minutely", "hourly", "daily", "flags".

<policies>
  <inbound>
    <base />
  </inbound>
  <backend>
    <base />
  </backend>
  <outbound>
    <base />
    <choose>
      <when condition="@(context.Response.StatusCode == 200 && context.Product.Name.Equals("Starter"))">
        <!-- NOTE that we are not using preserveContent=true when deserializing response body stream into a JSON object since we don't intend to access it again. See details on /azure/api-management/api-management-transformation-policies#SetBody -->
        <set-body>
          @{
            var response = context.Response.Body.As<JObject>();
            foreach (var key in new [] {"minutely", "hourly", "daily", "flags"}) {
            response.Property (key).Remove ();
           }
          return response.ToString();
          }
    </set-body>
      </when>
    </choose>    
  </outbound>
  <on-error>
    <base />
  </on-error>
</policies>