Establecer cuerpo

  • Artículo

SE APLICA A: todos los niveles de API Management

Use la directiva set-body para establecer el cuerpo del mensaje para una solicitud o respuesta. 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.

Importante

De forma predeterminada, al acceder al cuerpo del mensaje mediante context.Request.Body o context.Response.Body, se pierde el cuerpo del mensaje original, por lo que es preciso establecerlo, para lo que se devuelve el cuerpo en la expresión. Para conservar el contenido del cuerpo, establezca el parámetro preserveContent en true al acceder al mensaje. Si preserveContent está establecido en true y la expresión devuelve un cuerpo distinto, se utiliza el que se devuelva.

Nota

Establezca los elementos de la directiva y los elementos secundarios en el orden proporcionado en la instrucción de directiva. Obtenga más información sobre el establecimiento o modificación de directivas de API Management.

Instrucción de la directiva

<set-body template="liquid" xsi-nil="blank | null" parse-date="true | false">
    new body value as text
</set-body>

Atributos

Atributo Descripción Necesario Valor predeterminado
template Se utiliza para cambiar el modo de creación de plantillas que ejecutará la directiva set-body. Actualmente, el único valor admitido es:

- liquid: la directiva set-body usará el motor de plantillas liquid		 No N/D
xsi-nil Se usa para controlar cómo se representan los elementos marcados con xsi:nil="true" en cargas XML. Seleccione uno de los siguientes valores:

- blank - nil se representa con una cadena vacía.
- null - nil se representa con un valor NULL.

No se permiten expresiones de directiva.		 No blank
parse-date booleano. Especifica si las cadenas con formato de fecha (por ejemplo, "/Date(1198908717056)/", "2012-03-21T05:40Z") se analizan en System.DateTime (mm/dd/yyyy hh:mm:ss). Cuando se establece en false, los valores de fecha se copian simplemente.

No se permiten expresiones de directiva.		 No true

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

Notas de uso

  • Si usa la directiva set-body para devolver un cuerpo nuevo o actualizado, no hay que establecer preserveContent en true porque estará especificando explícitamente el nuevo contenido del cuerpo.
  • No tiene sentido conservar el contenido de una respuesta en la canalización de entrada porque todavía no hay ninguna respuesta.
  • De igual modo, no tiene sentido conservar el contenido de una solicitud en la canalización de salida porque la solicitud ya se ha enviado al servidor en este momento.
  • Si esta directiva se usa cuando no haya ningún cuerpo de mensaje, por ejemplo, en un GET entrante, se producirá una excepción.

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

Uso de plantillas Liquid con set-body

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

Importante

La implementación de Liquid que se utiliza en la directiva set-body está configurada en el modo de C#. Esto es especialmente importante al realizar tareas como el filtrado. Por ejemplo, para usar un filtro de fecha se requiere usar las mayúsculas y minúsculas de Pascal y el formato de fecha de C#; por ejemplo:

{{body.foo.startDateTime| Date:"yyyyMMddTHH:mm:ssZ"}}

Importante

Para enlazar correctamente con un cuerpo XML mediante la plantilla Liquid, use una directiva set-header para establecer que Content-Type sea application/xml, text/xml (o cualquier tipo que termine en +xml); para un cuerpo JSON, debe ser application/json, texto/json (o cualquier tipo que termine en +json).

Importante

Las plantillas líquidas usan el cuerpo de la solicitud o respuesta en la canalización de ejecución actual como entrada. Por este motivo, las plantillas líquidas no funcionan cuando se usan dentro de una directiva de respuesta de retorno. Una directiva de respuesta de retorno cancela la canalización de ejecución actual y quita el cuerpo de la solicitud o respuesta. Como resultado, cualquier plantilla líquida usada dentro de la respuesta de retorno recibirá una cadena vacía como entrada y no generará la salida esperada.

Filtros de Liquid admitidos

En la directiva set-body, se admiten los siguientes filtros de Liquid. Para ver ejemplos de filtros, consulte la documentación de Liquid.

Nota:

La directiva requiere el uso de mayúsculas y minúsculas de Pascal para los nombres de filtro de Liquid (por ejemplo, "AtLeast" en lugar de "at_least").

  • Abs
  • Anexar
  • AtLeast
  • AtMost
  • Capitalize
  • Compacto
  • Moneda
  • Date
  • Valor predeterminado
  • DividedBy
  • Downcase
  • Escape
  • First
  • H
  • Join
  • Último
  • Lstrip
  • Asignación
  • Resta
  • Módulo
  • NewlineToBr
  • Plus
  • Prepend
  • Quitar
  • RemoveFirst
  • Replace
  • ReplaceFirst
  • Round
  • Rstrip
  • Size
  • Segmento
  • Sort
  • Dividir
  • Strip
  • StripHtml
  • StripNewlines
  • Horas
  • Truncate
  • TruncateWords
  • Uniq
  • Upcase
  • UrlDecode
  • UrlEncode

Ejemplos

Texto literal

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

Acceso al cuerpo como una cadena

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>

Acceso al cuerpo como un elemento JObject

Al no conservar el cuerpo de la solicitud original, el acceso posterior al mismo 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. En la respuesta de back-end de ejemplo se incluyen propiedades de nivel raíz similares a One Call API de OpenWeather.

<!-- 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 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 [] {"current", "minutely", "hourly", "daily", "alerts"}) {
          response.Property (key).Remove ();
        }
        return response.ToString();
      }
    </set-body>
  </when>
</choose>

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

<set-body template="liquid">
{
"order": {
    "id": "{{body.customer.purchase.identifier}}",
    "summary": "{{body.customer.purchase.orderShortDesc}}"
    }
}
</set-body>

Acceso al cuerpo como datos de formulario con codificación de URL

En el ejemplo siguiente se usa la expresión AsFormUrlEncodedContent() para acceder al cuerpo de la solicitud como datos de formulario con codificación de URL (tipo application/x-www-form-urlencoded de contenido) y, después, se convierte en JSON. Al no conservar el cuerpo de la solicitud original, el acceso posterior al mismo en la canalización producirá una excepción.

<set-body> 
@{ 
    var inBody = context.Request.Body.AsFormUrlEncodedContent();
    return JsonConvert.SerializeObject(inBody); 
} 
</set-body>

Obtener acceso y devolver el cuerpo como datos de formulario codificados con URL

En el ejemplo siguiente se usa la expresión AsFormUrlEncodedContent() para tener acceso al cuerpo de la solicitud como datos de formulario con codificación URL (tipo de contenido application/x-www-form-urlencoded), se agregan datos a la carga y se devuelven datos de formulario con codificación URL. Al no conservar el cuerpo de la solicitud original, el acceso posterior al mismo en la canalización producirá una excepción.

<set-body> 
@{ 
    var body = context.Request.Body.AsFormUrlEncodedContent();
    body["newKey"].Add("newValue");
    return body.ToFormUrlEncodedContent(); 
} 
</set-body>

Contenido relacionado

Para más información sobre el trabajo con directivas, vea: