Text festlegen

GILT FÜR: Alle API Management-Ebenen

Verwenden Sie die Richtlinie set-body, um den Meldungstext für eine Anforderung oder Antwort festzulegen. Um auf den Nachrichtentext zuzugreifen, können Sie die Eigenschaft context.Request.Body oder context.Response.Body verwenden, je nachdem, ob sich die Richtlinie im Abschnitt „inbound“ oder „outbound“ befindet.

Wichtig

Wenn Sie mit context.Request.Body oder context.Response.Body auf den Nachrichtentext zugreifen, geht der ursprüngliche Nachrichtentext standardmäßig verloren und muss durch Zurückgeben des Texts im Ausdruck wiederhergestellt werden. Um den Nachrichtentext zu erhalten, legen Sie den Parameter preserveContent auf true fest, wenn Sie auf die Nachricht zugreifen. Wenn preserveContent auf true festgelegt ist und ein anderer Text vom Ausdruck zurückgegeben wird, wird der zurückgegebene Text verwendet.

Hinweis

Legen Sie die Elemente und untergeordneten Elemente einer Richtlinie in der Reihenfolge fest, die in der Richtlinienanweisung angegeben ist. Erfahren Sie mehr darüber, wie Sie API Management-Richtlinien festlegen oder bearbeiten.

Richtlinienanweisung

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

Attribute

Attribut	BESCHREIBUNG	Erforderlich	Standard
Vorlage	Dient zum Ändern des Vorlagenmodus, in dem die Richtlinie set-body ausgeführt wird. Der einzige derzeit unterstützte Wert ist: - liquid: Die Richtlinie set-body verwendet die Liquid-Vorlagen-Engine.	Nein	–
xsi-nil	Wird verwendet, um zu steuern, wie mit xsi:nil="true" gekennzeichnete Elemente in XML-Nutzlasten dargestellt werden. Legen Sie einen der folgenden Werte fest: - blank - nil wird mit einer leeren Zeichenfolge dargestellt. - null - nil wird mit einem NULL-Wert dargestellt. Richtlinienausdrücke sind nicht zulässig.	Nein	blank
parse-date	Boolesch. Gibt an, ob datumsformatierte Zeichenfolgen (z. B. "/Date(1198908717056)/", "2012-03-21T05:40Z") in System.DateTime (mm/dd/yyyy hh:mm:ss) analysiert werden. Wenn dieser Wert auf false festgelegt ist, werden Datumswerte einfach kopiert. Richtlinienausdrücke sind nicht zulässig.	Nein	true

Für den Zugriff auf Informationen über die Anforderung und Antwort, kann die Liquid-Vorlage an ein context-Objekt mit den folgenden Eigenschaften binden:

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

Verwendung

• Richtlinienabschnitte: inbound, outbound, backend
• Richtlinienbereiche: global, Arbeitsbereich, Produkt, API, Vorgang
• Gateways: classic, v2, consumption, self-hosted

Hinweise zur Verwendung

• Wenn Sie die Richtlinie set-body verwenden, um einen neuen oder aktualisierten Text zurückzugeben, müssen Sie preserveContent nicht auf true festlegen, da Sie den Inhalt des neuen Texts explizit angeben.
• Das Beibehalten des Inhalts einer Antwort in der eingehenden Pipeline ergibt keinen Sinn, da noch keine Antwort vorliegt.
• Das Beibehalten des Inhalts einer Anforderung in der ausgehenden Pipeline ergibt keinen Sinn, da die Anforderung zu diesem Zeitpunkt bereits an den Back-End gesendet wurde.
• Falls diese Richtlinie verwendet wird, wenn kein Nachrichtentext vorhanden ist, z. B. in einem eingehenden GET-Vorgang, wird eine Ausnahme ausgelöst.

Weitere Informationen finden Sie in den Abschnitten zu context.Request.Body, context.Response.Body und IMessageBody in der Tabelle context.Request.Body.

Verwenden von Liquid-Vorlagen mit „set-body“

Die Richtlinie set-body kann so konfiguriert werden, dass Sie den Hauptteil einer Anforderung oder Antwort mit der Vorlagensprache set-body transformiert. Dies kann effektiv sein, wenn Sie das Format Ihrer Nachricht vollständig umformen müssen.

Wichtig

Die Implementierung von Liquid, verwendet in der set-body-Richtlinie, wird im „C#-Modus“ konfiguriert. Dies ist beim Ausführen von Aktionen wie z.B. dem Filtern besonders wichtig. Beispielsweise erfordert die Verwendung eines Datumfilters das Verwenden der Pascal-Schreibweise und die C#-Datumsformatierung, z.B.:

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

Wichtig

Zum ordnungsgemäßen Binden an ein XML-Text mithilfe der Vorlage für Liquid, verwenden Sie eine set-header-Richtlinie, um Content-Typ entweder auf Anwendung/xml, Text/xml (oder jeder Typ endend mit +xml) festzulegen. Für einen JSON-Text, muss es Anwendung/JSON, Text/JSON (oder jeder Typ endend mit +JSON) sein.

Wichtig

Liquid-Vorlagen verwenden den Anforderungs-/Antworttext in der aktuellen Ausführungspipeline als Eingabe. Aus diesem Grund funktionieren Liquid-Vorlagen nicht, wenn sie innerhalb einer Rückgabe-Antwort-Richtlinie verwendet werden. Eine Rückgabe-Antwort-Richtlinie bricht die aktuelle Ausführungspipeline ab und entfernt den Anforderungs-/Antworttext. Daher erhält jede Liquid-Vorlage, die innerhalb der Rückgabe-Antwort verwendet wird, eine leere Zeichenfolge als Eingabe und erzeugt nicht die erwartete Ausgabe.

Unterstützte Liquid-Filter

Die folgenden Liquid-Filter werden in der set-body-Richtlinie unterstützt. Filterbeispiele finden Sie in der Liquid-Dokumentation.

Hinweis

Die Richtlinie erfordert Pascal-Casing für Liquid-Filternamen (z. B. „AtLeast“ anstelle von „at_least“).

• Abs
• Anfügen
• AtLeast
• AtMost
• Capitalize
• Kompakt
• Währung
• Date
• Standard
• DividedBy
• Downcase
• Escape
• First
• H
• Join
• Last (Letzter)
• Lstrip
• Zuordnung
• Subtraktion
• Modulo
• NewlineToBr
• Plus
• Prepend
• Entfernen
• RemoveFirst
• Replace
• ReplaceFirst
• Round
• Rstrip
• Size
• Slice
• Sortieren
• Split
• Strip
• StripHtml
• StripNewlines
• Uhrzeiten
• Truncate
• TruncateWords
• Uniq
• Upcase
• UrlDecode
• UrlEncode

Beispiele

Literaltext

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

Zugriff auf den Text als Zeichenfolge

Der ursprüngliche Anforderungstext wird beibehalten, sodass später in der Pipeline darauf zugegriffen werden kann.

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

Zugriff auf den Text als JObject

Da der ursprüngliche Anforderungstext nicht erhalten bleibt, wird beim späteren Zugriff darauf in der Pipeline eine Ausnahme ausgelöst.

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

Filtern der Antwort basierend auf dem Produkt

In diesem Beispiel wird gezeigt, wie Inhalte gefiltert werden, indem Datenelemente aus der über einen Back-End-Dienst empfangenen Antwort entfernt werden, wenn das Produkt Starter verwendet wird. Die Back-End-Beispielantwort enthält Eigenschaften auf Stammebene, die der OpenWeather One Call-API ähneln.

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

Konvertieren von JSON in SOAP mithilfe einer Liquid-Vorlage

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

Transformieren von JSON mithilfe einer Liquid-Vorlage

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

Zugreifen auf den Text als URL-codierte Formulardaten

Im folgenden Beispiel wird der Ausdruck AsFormUrlEncodedContent() verwendet, um auf den Anforderungstext als URL-codierte Formulardaten (Inhaltstyp application/x-www-form-urlencoded) zuzugreifen. Anschließend wird er in JSON konvertiert. Da der ursprüngliche Anforderungstext nicht erhalten bleibt, wird beim späteren Zugriff darauf in der Pipeline eine Ausnahme ausgelöst.

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

Zugreifen auf den Text und Zurückgeben des Texts als URL-codierte Formulardaten

Im folgenden Beispiel wird der Ausdruck AsFormUrlEncodedContent() verwendet, um auf den Anforderungstext als URL-codierte Formulardaten (Inhaltstyp application/x-www-form-urlencoded) zuzugreifen, Nutzdaten hinzuzufügen und URL-codierte Formulardaten zurückzugeben. Da der ursprüngliche Anforderungstext nicht erhalten bleibt, wird beim späteren Zugriff darauf in der Pipeline eine Ausnahme ausgelöst.

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

Verwandte Richtlinien

• Transformation

Zugehöriger Inhalt

Weitere Informationen zum Arbeiten mit Richtlinien finden Sie hier:

• Tutorial: Transformieren und Schützen Ihrer API
• Unter Richtlinien für die API-Verwaltung finden Sie eine komplette Liste der Richtlinienanweisungen und der zugehörigen Einstellungen.
• Richtlinienausdrücke
• Festlegen oder Bearbeiten von Richtlinien
• Wiederverwenden von Richtlinienkonfigurationen
• Repository für Richtliniencodeausschnitte
• Erstellen von Richtlinien mit Microsoft Copilot für Azure