Condividi tramite

Set body (Imposta corpo)

  • Articolo

SI APPLICA A: Tutti i livelli di Gestione API

Usare il criterio set-body per impostare il corpo del messaggio per una richiesta o una risposta. Per accedere al corpo del messaggio è possibile usare la proprietà context.Request.Body o context.Response.Body, a seconda che il criterio sia nella sezione inbound o outbound.

Importante

Per impostazione predefinita, quando si accede al corpo del messaggio con context.Request.Body o context.Response.Body, il corpo del messaggio originale viene perso e deve essere impostato riportandolo nell'espressione. Per mantenere il contenuto del corpo, impostare il parametro preserveContent su true quando si accede al messaggio. Se preserveContent è impostato su true e l'espressione restituisce un corpo diverso, viene usato il corpo restituito.

Nota

Impostare gli elementi e gli elementi figlio del criterio nell'ordine specificato nell'istruzione del criterio. Altre informazioni su come impostare o modificare i criteri di API Management.

Istruzione del criterio

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

Attributi

Attributo Descrizione Richiesto Valore predefinito
annidato Consente di modificare la modalità di creazione di modelli in cui verrà eseguito il criterio set-body. Al momento, l'unico valore supportato è:

- liquid: i criteri set-body useranno il motore di creazione di modelli Liquid		 No N/D
xsi-nil Utilizzato per controllare il modo in cui gli elementi contrassegnati con xsi:nil="true" vengono rappresentati nei payload XML. Impostare su uno dei valori seguenti:

- blank - nil è rappresentato con una stringa vuota.
- null - nil è rappresentato con un valore Null.

Le espressioni del criterio non sono consentite.		 No blank
parse-date Booleano. Specifica se le stringhe in formato data (ad esempio, "/Date(1198908717056)/", "2012-03-21T05:40Z") vengono analizzate in System.DateTime (mm/dd/yyyy hh:mm:ss). Se impostato su false, i valori data vengono semplicemente copiati.

Le espressioni del criterio non sono consentite.		 No true

Per accedere alle informazioni sulla richiesta e la risposta, il modello Liquid può essere associato a un oggetto di contesto con le proprietà seguenti: 

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

Utilizzo

Note sull'utilizzo

  • Se il criterio set-body viene usato per restituire un corpo nuovo o aggiornato non è necessario impostare preserveContent su true, perché il nuovo contenuto del corpo viene fornito in modo esplicito.
  • Non ha senso mantenere il contenuto di una risposta nella pipeline in ingresso, poiché non è ancora stata ricevuta alcuna risposta.
  • Non ha senso neanche mantenere il contenuto di una risposta nella pipeline in uscita perché a questo punto la richiesta è già stata inviata al back-end.
  • Se questo criterio viene usato quando non vi è alcun corpo del messaggio, ad esempio in un'operazione GET in ingresso, viene generata un'eccezione.

Per altre informazioni, vedere le sezioni context.Request.Body, context.Response.Bodye IMessageBody nella tabella Variabile di contesto.

Uso di modelli Liquid con set body

Il criterio set-body può essere configurato per l'uso del linguaggio di modellazione Liquid per trasformare il corpo di una richiesta o di una risposta. Può essere efficace se si desidera modificare completamente il formato del messaggio.

Importante

L'implementazione di Liquid usato nel criterio set-body è configurato in "modalità C#". Questo è particolarmente importante quando si eseguono operazioni quali l'applicazione del filtro. Ad esempio, l'uso di un filtro data richiede l'uso della convenzione Pascal e della formattazione delle date C#, ad esempio:

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

Importante

Per eseguire correttamente l'associazione a un corpo XML utilizzando il modello Liquid, usare un criterio set-header per impostare il tipo di contenuto su application/xml, text/xml (o su qualsiasi tipo che termini con +xml); per un corpo JSON, deve essere application/json, testo/json (o qualsiasi tipo che termini con +json).

Importante

I modelli Liquid usano il corpo della richiesta/risposta nella pipeline di esecuzione corrente come input. Per questo motivo, i modelli Liquid non funzionano quando vengono usati all'interno di un criterio di risposta restituita. Un criterio di risposta restituita annulla la pipeline di esecuzione corrente e rimuove il corpo della richiesta/risposta. Di conseguenza, qualsiasi modello Liquid usato all'interno della risposta restituita riceverà una stringa vuota come input e non genererà l'output previsto.

Filtri Liquid supportati

I filtri Liquid seguenti sono supportati nei criteri set-body. Per esempi di filtro, vedere la documentazione su Liquid.

Nota

Il criterio richiede l'uso di maiuscole e minuscole Pascal per i nomi di filtri Liquid (ad esempio, "AtLeast" anziché "at_least").

  • Abs
  • Aggiunta
  • AtLeast
  • AtMost
  • Iniziali maiuscole
  • Compact
  • Valuta
  • Data
  • Default
  • DividedBy
  • Downcase
  • ESC
  • First
  • H
  • Join.
  • Last
  • Lstrip
  • Mapping
  • Meno
  • Modulo
  • NewlineToBr
  • Più
  • Anteponi
  • Rimuovi
  • RemoveFirst
  • Sostituzione
  • ReplaceFirst
  • Round
  • Rstrip
  • Dimensione
  • Fetta
  • Ordinamento
  • Divisa
  • Strip
  • StripHtml
  • StripNewlines
  • Times
  • Truncate
  • TruncateWords
  • Uniq
  • Upcase
  • UrlDecode
  • UrlEncode

Esempi

Testo letterale

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

Accedere al corpo come stringa

Il corpo della richiesta originale viene mantenuto per potervi accedere più avanti nella pipeline.

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

Accedere al corpo come JObject

Poiché il corpo della richiesta originale non viene mantenuto, l'accesso a tale corpo più avanti nella pipeline genererà un'eccezione.

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

Filtrare la risposta in base al prodotto

Questo esempio mostra come eseguire operazioni di filtro sui contenuti rimuovendo elementi di dati dalla risposta ricevuta da un servizio back-end quando si usa il prodotto Starter. La risposta back-end di esempio include proprietà a livello radice simili all'API OpenWeather One Call.

<!-- 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>

Convertire JSON in SOAP usando un modello 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>

Trasformare JSON usando un modello Liquid

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

Accedere al corpo come dati del modulo codificati con URL

Nell'esempio seguente viene usata l'espressione AsFormUrlEncodedContent() per accedere al corpo della richiesta come dati del modulo con codifica URL (tipo di contenuto application/x-www-form-urlencoded) e quindi la converte in JSON. Poiché il corpo della richiesta originale non viene mantenuto, l'accesso a tale corpo più avanti nella pipeline genererà un'eccezione.

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

Accedere e restituire il corpo come dati del modulo codificati con URL

Nell'esempio seguente viene usata l'espressione AsFormUrlEncodedContent() per accedere al corpo della richiesta come dati del modulo con codifica URL (tipo di contenuto application/x-www-form-urlencoded), aggiunge dati al payload e restituisce i dati del modulo con codifica URL. Poiché il corpo della richiesta originale non viene mantenuto, l'accesso a tale corpo più avanti nella pipeline genererà un'eccezione.

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

Contenuto correlato

Per ulteriori informazioni sull'utilizzo dei criteri, vedere: