設定本文

發行項
03/28/2024

適用於：所有 API 管理層

使用 set-body 原則來設定要求或回應的訊息本文。若要存取訊息本文，您可以使用 context.Request.Body 屬性或 context.Response.Body，取決於原則是在輸入或輸出區段中。

重要

根據預設，當您使用 context.Request.Body 或 context.Response.Body 存取訊息本文，原始訊息本文會遺失，且必須在運算式中傳回本文加以設定。若要保留本文內容，存取訊息時將 preserveContent 參數設為 true。如果 preserveContent 設為 true，且運算式傳回不同的本文，則會使用傳回的本文。

注意

請依照原則陳述式中提供的順序，來設定原則的元素和子元素。深入了解如何設定或編輯 APIM 原則。

原則陳述式

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

屬性

屬性	描述	是必要欄位	預設
template	用於變更要執行 `set-body` 原則的範本化模式。目前唯一支援的值為： - `liquid` - `set-body` 原則會使用 Liquid 範本化引擎	No	N/A
xsi-nil	用於控制如何在 XML 承載中表示以 `xsi:nil="true"` 標記的元素，將設定為下列其中一個值： - `blank` - `nil` 以空白字串表示。 - `null` - `nil` 以 null 值表示。不允許使用原則運算式。	No	`blank`
剖析日期	布林值。指定日期格式字串 (例如，`"/Date(1198908717056)/"`、`"2012-03-21T05:40Z"`) 是否剖析為 System.DateTime (`mm/dd/yyyy hh:mm:ss`)。設定為 `false` 時，只會複製日期值。不允許使用原則運算式。	No	`true`

為了存取要求與回應的相關資訊，Liquid 範本可以繫結至具有下列屬性的內容物件：

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

使用方式

原則區段︰輸入、輸出、後端
原則範圍︰全域、工作區、產品、API、作業
閘道： 傳統、v2、耗用量、自我裝載

使用注意事項

如果您使用 set-body 原則來傳回新的或更新的本文，您不需要將 preserveContent 設為 true，因為您已明確地提供新的本文內容。
在輸入管線中保留回應的內容沒有意義，因為尚無回應。
在輸出管線中保留要求的內容沒有意義，因為此時要求已傳送至後端。
如果在沒有任何訊息本文時使用此原則 (例如輸入 GET)，會擲回例外狀況。

如需詳細資訊，請參閱內容變數表中 context.Request.Body、context.Response.Body、IMessageBody 的部分。

使用 Liquid 範本搭配 set-body

您可以設定讓 set-body 原則使用 Liquid 範本化語言來轉換要求或回應的本文。如果您需要完全重設訊息的格式，這很有效。

重要

set-body 原則中使用的 Liquid 實作是在「 C# 模式」下設定。這在進行篩選之類的操作時尤其重要。舉例來說，使用日期篩選需要使用 Pascal 大小寫慣例和 C# 日期格是，例如：

重要

為了使用 Liquid 範本來正確地繫結至 XML 主體，請使用 set-header 原則將 Content-Type 設定為 application/xml、text/xml (或任何結尾為 +xml 的類型)；如果是 JSON 主體，則必須是 application/json、text/json (或任何結尾為 +json 的類型)。

重要

Liquid 範本會使用目前執行管線中的要求/回應本文作為其輸入。因此，在 return-response 原則內使用 Liquid 範本時無法運作。 return-response 原則會取消目前的執行管線，並移除要求/回應本文。因此，return-response 內使用的任何 Liquid 範本都會接收空字串作為其輸入，而且不會產生預期的輸出。

支援的 Liquid 篩選條件

原則支援 set-body 下列 Liquid 篩選條件。如需篩選條件範例，請參閱 Liquid 文件。

注意

此原則需要 Liquid 篩選條件名稱的 Pascal 大小寫 (例如「AtLeast」，而不是「at_least」)。

Abs
附加
AtLeast
AtMost
Capitalize
Compact
貨幣
Date
預設
DividedBy
Downcase
ESC 鍵
First
H
聯結
姓氏
Lstrip
地圖
Minus
模數
NewlineToBr
Plus
Prepend
移除
RemoveFirst
Replace
ReplaceFirst
Round
Rstrip
大小
配量
Sort
份額
Strip
StripHtml
StripNewlines
Times
Truncate
TruncateWords
Uniq
Upcase
UrlDecode
UrlEncode

範例

常值文字

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

以字串存取本文

我們會保留原始要求本文，如此便能稍後於管線中存取。

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

以 JObject 存取本文

由於我們不會保留原始要求本文，若稍後於管線中存取則會導致例外狀況。

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

根據產品篩選回應

這個範例示範如何在使用 Starter 產品時，移除從後端服務收到的回應中的資料元素，藉此執行內容篩選。範例後端回應包含類似 OpenWeather One 呼叫 API的根層級屬性。

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

使用 Liquid 範本將 JSON 轉換成 SOAP

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

使用 Liquid 範本轉換 JSON

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

以 URL 編碼的表單資料存取本文

下列範例會使用 AsFormUrlEncodedContent() 運算式，以 URL 編碼的表單資料存取要求本文 (內容類型 application/x-www-form-urlencoded)，然後將它轉換成 JSON。由於我們不會保留原始要求本文，若稍後於管線中存取則會導致例外狀況。

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

以 URL 編碼的表單資料存取並傳回本文

下列範例會使用 AsFormUrlEncodedContent() 運算式，以 URL 編碼的表單資料存取要求本文 (內容類型 application/x-www-form-urlencoded)，將資料新增至承載，並傳回 URL 編碼的表單資料。由於我們不會保留原始要求本文，若稍後於管線中存取則會導致例外狀況。

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

轉型

如需使用原則的詳細資訊，請參閱：