Directivas de transformación de API Management

En este tema se proporciona una referencia para las siguientes directivas de API Management. Para obtener más información sobre cómo agregar y configurar directivas, consulte Directivas en Administración de API.

Directivas de transformación

• Convertir JSON a XML : convierte el cuerpo de solicitud o respuesta de JSON a XML.

• Convertir XML a JSON : convierte el cuerpo de solicitud o respuesta de XML a JSON.

• Buscar y reemplazar la cadena en el cuerpo : encuentra una subcadena de solicitud o de respuesta y la reemplaza por una subcadena diferente.

• Enmascarar URL en el contenido : reescribe (enmascara) vínculos en el cuerpo de respuesta para que apunten al vínculo equivalente a través de la puerta de enlace.

• Establecer el servicio back-end : cambia el servicio back-end para una solicitud entrante.

• Establecer cuerpo -establece el cuerpo del mensaje para las solicitudes entrantes y salientes.

• Establecer encabezado HTTP : asigna un valor a un encabezado de respuesta o de solicitud existente o agrega un nuevo encabezado de este tipo.

• Establecer el parámetro de cadena de consulta : agrega, reemplaza el valor o elimina el parámetro de la cadena de consulta de la solicitud.

• URL de reescritura : convierte una URL de solicitud de su forma pública a la forma esperada por el servicio web.

• Transformar XML mediante una XSLT: aplica una transformación de XSL al XML del cuerpo de la solicitud o respuesta.

Conversión de JSON a XML

La directiva json-to-xml convierte un cuerpo de solicitud o respuesta de JSON a XML.

Instrucción de la directiva

<json-to-xml apply="always | content-type-json" consider-accept-header="true | false" parse-date="true | false"/>

Ejemplo

<policies>
    <inbound>
        <base />
    </inbound>
    <outbound>
        <base />
        <json-to-xml apply="always" consider-accept-header="false" parse-date="false"/>
    </outbound>
</policies>

Elementos

Atributos

Uso

Esta directiva puede usarse en las siguientes secciones y ámbitos de directiva.

• Secciones de la directiva: entrante, saliente y en caso de error

• Ámbitos de la directiva: todos los ámbitos

Conversión de XML a JSON

La directiva xml-to-json convierte un cuerpo de solicitud o respuesta de XML a JSON. Esta directiva puede usarse para modernizar API basadas en servicios web de back-end de solo XML.

Instrucción de la directiva

<xml-to-json kind="javascript-friendly | direct" apply="always | content-type-xml" consider-accept-header="true | false"/>

Ejemplo

<policies>
    <inbound>
        <base />
    </inbound>
    <outbound>
        <base />
        <xml-to-json kind="direct" apply="always" consider-accept-header="false" />
    </outbound>
</policies>

Elementos

Atributos

Uso

Esta directiva puede usarse en las siguientes secciones y ámbitos de directiva.

• Secciones de la directiva: entrante, saliente y en caso de error

• Ámbitos de la directiva: todos los ámbitos

Buscar y reemplazar la cadena en el cuerpo

La política find-and-replace busca una subcadena de solicitud o de respuesta y la sustituye por otra distinta.

Instrucción de la directiva

<find-and-replace from="what to replace" to="replacement" />

Ejemplo

<find-and-replace from="notebook" to="laptop" />

Elementos

Atributos

Uso

Esta directiva puede usarse en las siguientes secciones y ámbitos de directiva.

• Secciones de la directiva: inbound, outbound, backend, on-error

• Ámbitos de la directiva: todos los ámbitos

Enmascarar URL en el contenido

La directiva redirect-content-urls reescribe (enmascara) los vínculos del cuerpo de la respuesta para que apunten al vinculo equivalente a través de la puerta de enlace. Utilícela en la sección saliente a fin de rescribir los vínculos del cuerpo de la respuesta para hacer que apunten a la puerta de enlace. Úsela en la sección entrante para obtener el resultado opuesto.

Instrucción de la directiva

<redirect-content-urls />

Ejemplo

<redirect-content-urls />

Elementos

Uso

Esta directiva puede usarse en las siguientes secciones y ámbitos de directiva.

• Secciones de la directiva: entrante y saliente

• Ámbitos de la directiva: todos los ámbitos

Establecer el servicio back-end

Use la directiva set-backend-service a fin de redirigir una solicitud entrante a un back-end distinto al especificado en la configuración de la API para esa operación. Esta directiva cambia la dirección URL base del servicio back-end de la solicitud entrante a la especificada en la directiva.

Instrucción de la directiva

<set-backend-service base-url="base URL of the backend service" />

or

<set-backend-service backend-id="identifier of the backend entity specifying base URL of the backend service" />

Ejemplo

<policies>
    <inbound>
        <choose>
            <when condition="@(context.Request.Url.Query.GetValueOrDefault("version") == "2013-05")">
                <set-backend-service base-url="http://contoso.com/api/8.2/" />
            </when>
            <when condition="@(context.Request.Url.Query.GetValueOrDefault("version") == "2014-03")">
                <set-backend-service base-url="http://contoso.com/api/9.1/" />
            </when>
        </choose>
        <base />
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>

En este ejemplo, la directiva del servicio back-end establecida enruta las solicitudes según el valor de versión pasado en la cadena de consulta a un servicio back-end distinto del especificado en la API.

Inicialmente, la dirección URL base del servicio back-end se obtiene a partir de la configuración de la API. Por ello, la dirección URL de solicitud https://contoso.azure-api.net/api/partners/15?version=2013-05&subscription-key=abcdef se convierte en http://contoso.com/api/10.4/partners/15?version=2013-05&subscription-key=abcdef, donde http://contoso.com/api/10.4/ se corresponde con la dirección URL del servicio back-end especificada en la configuración de la API.

Cuando se aplica la instrucción de la directiva <choose>, la dirección URL base del servicio back-end puede volver a cambiar a http://contoso.com/api/8.2 o http://contoso.com/api/9.1, en función del valor del parámetro de consulta de la solicitud de la versión. Por ejemplo, si el valor es "2013-15", la dirección URL final de la solicitud se convierte en http://contoso.com/api/8.2/partners/15?version=2013-05&subscription-key=abcdef.

Si se desea aplicar más transformaciones a la solicitud, es posible usar otras directivas de transformación. Por ejemplo, para quitar el parámetro de consulta de la versión ahora que la solicitud se está enrutando a un back-end específico de la versión, se puede usar la directiva de establecimiento del parámetro de cadena de consulta para quitar el atributo de versión, que ahora presenta un carácter redundante.

Ejemplo

<policies>
    <inbound>
        <set-backend-service backend-id="my-sf-service" sf-partition-key="@(context.Request.Url.Query.GetValueOrDefault("userId","")" sf-replica-type="primary" />
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>

En este ejemplo, la directiva enruta la solicitud a un back-end de Service Fabric, con la cadena de consulta userId como la clave de partición y con la réplica principal de la partición.

Elementos

Atributos

Uso

Esta directiva puede usarse en las siguientes secciones y ámbitos de directiva.

• Secciones de la directiva: entrante y back-end

• Ámbitos de la directiva: todos los ámbitos

Establecer cuerpo

Utilice la directiva set-body con la finalidad de establecer el cuerpo del mensaje para las solicitudes entrantes y salientes. Para acceder al cuerpo del mensaje, puede utilizar las propiedades context.Request.Body o context.Response.Body, según si la directiva se encuentra en la sección entrante o saliente.

Para obtener más información, consulte las secciones context.Request.Body, context.Response.Body y IMessage de la tabla Context variable (Variable de contexto).

Instrucción de la directiva

<set-body>new body value as text</set-body>

Ejemplos

Ejemplo de texto literal

<set-body>Hello world!</set-body>

Ejemplo de acceso al cuerpo como una cadena. Tenga en cuenta que estamos conservando el cuerpo de la solicitud original para que resulte accesible más adelante en la canalización.

<set-body>
@{ 
    string inBody = context.Request.Body.As<string>(preserveContent: true); 
    if (inBody[0] =='c') { 
        inBody[0] = 'm'; 
    } 
    return inBody; 
}
</set-body>

Ejemplo de acceso al cuerpo como un elemento JObject. Tenga en cuenta que, al no conservar el cuerpo de la solicitud original, el acceso posterior a él en la canalización producirá una excepción.

<set-body> 
@{ 
    JObject inBody = context.Request.Body.As<JObject>(); 
    if (inBody.attribute == <tag>) { 
        inBody[0] = 'm'; 
    } 
    return inBody.ToString(); 
} 
</set-body>

Filtro de respuesta según un producto

En este ejemplo se muestra cómo filtrar contenido quitando elementos de datos de la respuesta recibida del servicio back-end al usar el producto Starter. Para ver una demostración de la configuración y el uso de esta directiva, consulte el Episodio 177 de Cloud Cover: More API Management Features with Vlad Vinogradsky (Más características de API Management con Vlad Vinogradsky) y avance hasta el minuto 34:30. Empiece en el minuto 31:50 para ver una introducción a la API de previsión de Dark Sky empleada en esta demostración.

<!-- Copy this snippet into the outbound section to remove a number of data elements from the response received from the backend service based on the name of the api product -->
<choose>
  <when condition="@(context.Response.StatusCode == 200 && context.Product.Name.Equals("Starter"))">
    <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>

Uso de plantillas Liquid con la directiva de establecer cuerpo

La directiva set-body se puede configurar para usar el lenguaje de plantillas Liquid para transformar el cuerpo de una solicitud o una respuesta. Esto puede resultar muy eficaz si necesita cambiar completamente el formato del mensaje.

Conversión de JSON en SOAP mediante una plantilla Liquid

<set-body template="liquid">
    <soap:Envelope xmlns="http://tempuri.org/" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
        <soap:Body>
            <GetOpenOrders>
                <cust>{{body.getOpenOrders.cust}}</cust>
            </GetOpenOrders>
        </soap:Body>
    </soap:Envelope>
</set-body>

Transformación de JSON mediante una plantilla Liquid

{
"order": {
    "id": "{{body.customer.purchase.identifier}}",
    "summary": "{{body.customer.purchase.orderShortDesc}}"
    }
}

Elementos

Propiedades

Para acceder a información sobre solicitud y respuesta, la plantilla Liquid puede enlazar a un objeto de contexto con las siguientes propiedades:

context.
    Request.
        Url
        Method
        OriginalMethod
        OriginalUrl
        IpAddress
        MatchedParameters
        HasBody
        ClientCertificates
        Headers

    Response.
        StatusCode
        Method
        Headers
Url.
    Scheme
    Host
    Port
    Path
    Query
    QueryString
    ToUri
    ToString

OriginalUrl.
    Scheme
    Host
    Port
    Path
    Query
    QueryString
    ToUri
    ToString

Uso

Esta directiva puede usarse en las siguientes secciones y ámbitos de directiva.

• Secciones de la directiva: entrante, saliente y back-end

• Ámbitos de la directiva: todos los ámbitos

Establecer encabezado HTTP

La directiva set-header asigna un valor a un encabezado de respuesta o de solicitud existente o agrega un nuevo encabezado de este tipo.

Inserta una lista de encabezados HTTP en un mensaje HTTP. Cuando se coloca en un proceso entrante, esta directiva establece los encabezados HTTP para la solicitud que se pasa al servicio de destino. Cuando se coloca en una canalización saliente, esta directiva establece los encabezados HTTP para la respuesta que se está enviando al cliente de la puerta de enlace.

Instrucción de la directiva

<set-header name="header name" exists-action="override | skip | append | delete">
    <value>value</value> <!--for multiple headers with the same name add additional value elements-->
</set-header>

Ejemplos

Ejemplo: agregar encabezado, invalidar existente

<set-header name="some header name" exists-action="override">
    <value>20</value>
</set-header>

Ejemplo: quitar el encabezado

 <set-header name="some header name" exists-action="delete" />

Reenvío de información contextual al servicio back-end

En este ejemplo se muestra cómo aplicar directivas en el nivel de API para proporcionar información contextual al servicio back-end. Para ver una demostración de la configuración y el uso de esta directiva, consulte el Episodio 177 de Cloud Cover: More API Management Features with Vlad Vinogradsky (Más características de API Management con Vlad Vinogradsky) y avance hasta el minuto 10:30. En el minuto 12:10 se realiza una demostración del llamamiento de una operación en el portal para desarrolladores donde podrá ver la directiva en funcionamiento.

<!-- Copy this snippet into the inbound element to forward some context information, user id and the region the gateway is hosted in, to the backend service for logging or evaluation -->
<set-header name="x-request-context-data" exists-action="override">
  <value>@(context.User.Id)</value>
  <value>@(context.Deployment.Region)</value>
</set-header>

Para obtener más información, consulte Policy expressions (Expresiones de política) y Context variable (Variable de contexto).

Elementos

Propiedades

Uso

Esta directiva puede usarse en las siguientes secciones y ámbitos de directiva.

• Secciones de la directiva: inbound, outbound, backend, on-error

• Ámbitos de la directiva: todos los ámbitos

Establecimiento del parámetro de cadena de consulta

La directiva set-query-parameter agrega o elimina el parámetro de cadena de consulta de la solicitud, o bien sustituye su valor. Se puede utilizar para pasar parámetros de consulta previstos por el servicio back-end que tienen carácter opcional o que nunca están presentes en la solicitud.

Instrucción de la directiva

<set-query-parameter name="param name" exists-action="override | skip | append | delete">
    <value>value</value> <!--for multiple parameters with the same name add additional value elements-->
</set-query-parameter>

Ejemplo

<set-query-parameter name="api-key" exists-action="skip">
  <value>12345678901</value>
</set-query-parameter>

Reenvío de información contextual al servicio back-end

En este ejemplo se muestra cómo aplicar directivas en el nivel de API para proporcionar información contextual al servicio back-end. Para ver una demostración de la configuración y el uso de esta directiva, consulte el Episodio 177 de Cloud Cover: More API Management Features with Vlad Vinogradsky (Más características de API Management con Vlad Vinogradsky) y avance hasta el minuto 10:30. En el minuto 12:10 se realiza una demostración del llamamiento de una operación en el portal para desarrolladores donde podrá ver la directiva en funcionamiento.

<!-- Copy this snippet into the inbound element to forward a piece of context, product name in this example, to the backend service for logging or evaluation -->
<set-query-parameter name="x-product-name" exists-action="override">
  <value>@(context.Product.Name)</value>
</set-query-parameter>

Para obtener más información, consulte Policy expressions (Expresiones de política) y Context variable (Variable de contexto).

Elementos

Propiedades

Uso

Esta directiva puede usarse en las siguientes secciones y ámbitos de directiva.

• Secciones de la directiva: entrante y back-end

• Ámbitos de la directiva: todos los ámbitos

URL de reescritura

La directiva rewrite-uri convierte una dirección URL de solicitud de su forma pública a la que espera recibir el servicio web, como se muestra en el siguiente ejemplo.

• URL pública: http://api.example.com/storenumber/ordernumber

• URL de solicitud: http://api.example.com/v2/US/hardware/storenumber&ordernumber?City&State

  Esta directiva se puede utilizar cuando una URL apta para el explorador o para individuos debe transformarse en el formato de URL que espera el servicio web. Esta directiva solo debe aplicarse al exponer un formato de URL alternativo, como URL limpias, direcciones URL RESTful y direcciones URL sencillas o aptas para optimización del motor de búsqueda que son URL puramente estructurales que no contienen una cadena de consulta, sino solo la ruta del recurso (después del esquema y la autoridad). Este procedimiento se realiza con fines estéticos, de usabilidad o de optimización del motor de búsqueda (SEO).

Instrucción de la directiva

<rewrite-uri template="uri template" copy-unmatched-params="true | false" />

Ejemplo

<policies>
    <inbound>
        <base />
        <rewrite-uri template="/v2/US/hardware/{storenumber}&{ordernumber}?City=city&State=state" />
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>

<!-- Assuming incoming request is /get?a=b&c=d and operation template is set to /get?a={b} -->
<policies>
    <inbound>
        <base />
        <rewrite-uri template="/put" />
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>
<!-- Resulting URL will be /put?c=d -->

<!-- Assuming incoming request is /get?a=b&c=d and operation template is set to /get?a={b} -->
<policies>
    <inbound>
        <base />
        <rewrite-uri template="/put" copy-unmatched-params="false" />
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>
<!-- Resulting URL will be /put -->

Elementos

Atributos

Uso

Esta directiva puede usarse en las siguientes secciones y ámbitos de directiva.

• Secciones de la directiva: inbound (entrada)

• Ámbitos de la directiva: todos los ámbitos

Transformar XML mediante una XSLT

La directiva Transform XML using an XSLT aplica una transformación XSL al XML del cuerpo de la solicitud o la respuesta.

Instrucción de la directiva

<xsl-transform>
    <parameter name="User-Agent">@(context.Request.Headers.GetValueOrDefault("User-Agent","non-specified"))</parameter>
    <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
        <xsl:output method="xml" indent="yes" />
        <xsl:param name="User-Agent" />
        <xsl:template match="* | @* | node()">
            <xsl:copy>
                <xsl:if test="self::* and not(parent::*)">
                    <xsl:attribute name="User-Agent">
                        <xsl:value-of select="$User-Agent" />
                    </xsl:attribute>
                </xsl:if>
                <xsl:apply-templates select="* | @* | node()" />
            </xsl:copy>
        </xsl:template>
    </xsl:stylesheet>
  </xsl-transform>

Ejemplo

<policies>
  <inbound>
      <base />
  </inbound>
  <outbound>
      <base />
      <xsl-transform>
          <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
            <xsl:output omit-xml-declaration="yes" method="xml" indent="yes" />
            <!-- Copy all nodes directly-->
            <xsl:template match="node()| @*|*">
                <xsl:copy>
                    <xsl:apply-templates select="@* | node()|*" />
                </xsl:copy>
            </xsl:template>
          </xsl:stylesheet>
    </xsl-transform>
  </outbound>
</policies>

Elementos

Uso

Esta directiva puede usarse en las siguientes secciones y ámbitos de directiva.

• Secciones de la directiva: entrante y saliente

• Ámbitos de la directiva: todos los ámbitos

Pasos siguientes

Para obtener más información, vea los temas siguientes:

• Directivas de Azure API Management
• En la Referencia de directivas se muestra una lista completa de declaraciones de directivas y su configuración
• Ejemplos de directivas