본문 설정

적용 대상: 모든 API Management 계층

set-body 정책을 사용하여 요청 또는 응답에 대한 메시지 본문을 설정합니다. 메시지 본문에 액세스하려면 정책이 inbound 또는 outbound 섹션에 있는지에 따라 context.Request.Body 또는 context.Response.Body 속성을 사용할 수 있습니다.

Important

기본적으로 context.Request.Body 또는 context.Response.Body를 사용하여 메시지 본문에 액세스하면 원래 메시지 본문이 손실되며 해당 본문을 식으로 다시 반환하여 설정해야 합니다. 본문 내용을 보존하려면 메시지에 액세스할 때 preserveContent 매개 변수를 true로 설정합니다. preserveContent가 true로 설정되고 식에서 다른 본문이 반환되면 반환된 본문을 사용합니다.

참고 항목

정책 문에 제공된 순서대로 정책의 요소 및 자식 요소를 설정합니다. API Management 정책을 설정하거나 편집하는 방법에 대해 자세히 알아봅니다.

정책 문

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

특성

특성	설명	필수 항목	기본값
템플릿	set-body 정책이 실행될 템플릿 모드를 변경하는 데 사용됩니다. 현재 지원되는 유일한 값: - liquid - set-body 정책은 liquid 템플릿 엔진을 사용합니다.	아니요	해당 없음
xsi-nil	xsi:nil="true"로 표시된 요소가 XML 페이로드에 표시되는 방식을 제어하는 데 사용됩니다. 를 다음 값 중 하나로 설정합니다. - blank - nil이 빈 문자열로 표시됩니다. - null - nil이 null 값으로 표시됩니다. 정책 식은 허용되지 않습니다.	아니요	blank
parse-date	부울입니다. 날짜 형식 문자열(예 "/Date(1198908717056)/", "2012-03-21T05:40Z")이 System.DateTime(mm/dd/yyyy hh:mm:ss)으로 구문 분석되는지 여부를 지정합니다. false로 설정하면 날짜 값이 복사됩니다. 정책 식은 허용되지 않습니다.	아니요	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

사용

• 정책 섹션: inbound, outbound, backend
• 정책 범위: 전역, 작업 영역, 제품, API, 작업
• 게이트웨이: 클래식, v2, 사용량, 자체 호스팅, 작업 영역

사용법 참고 사항

• set-body 정책을 사용하여 새 본문 또는 업데이트된 본문을 반환하는 경우 명시적으로 새 본문 내용을 제공하므로 preserveContent를 true로 설정할 필요가 없습니다.
• 인바운드 파이프라인에서 응답 내용을 보존하는 것은 아직 응답이 없기 때문에 이치에 맞지 않습니다.
• 아웃바운드 파이프라인에서 요청 내용을 보존하는 것은 이 시점에서 요청을 이미 백 엔드로 보냈기 때문에 이치에 맞지 않습니다.
• 인바운드 GET에서와 같이 메시지 본문이 없을 때 이 정책을 사용하면 예외가 발생합니다.

자세한 내용은 컨텍스트 변수 표의 context.Request.Body, context.Response.Body 및 IMessageBody 섹션을 참조하세요.

본문이 설정된 Liquid 템플릿 사용

Liquid 템플릿 언어를 사용하여 요청 또는 응답의 본문을 변환하도록 set-body 정책을 구성할 수 있습니다. 이 방법은 메시지 형식을 완전히 바꾸어야 하는 경우에 효과적일 수 있습니다.

Important

set-body 정책에 사용되는 Liquid 구현은 'C# 모드'로 구성됩니다. 이러한 방식은 필터링과 같은 작업을 수행하는 경우에 특히 중요합니다. 예를 들어 날짜 필터를 사용하려면 다음과 같이 파스칼식 대/소문자 및 C# 날짜 형식을 사용해야 합니다.

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

Important

Liquid 템플릿을 사용하여 XML 본문에 올바르게 바인딩하려면 set-header 정책을 사용하여 Content-Type을 application/xml, text/xml(또는 +xml로 끝나는 임의 형식)로 설정하세요. JSON 본문의 경우에는 application/json, text/json(또는 +json으로 끝나는 임의 형식)이어야 합니다.

Important

Liquid 템플릿은 현재 실행 파이프라인의 요청/응답 본문을 입력으로 사용합니다. 따라서 return-response 정책 내에서 사용할 경우 liquid 템플릿이 작동하지 않습니다. return-response 정책은 현재 실행 파이프라인을 취소하고 요청/응답 본문을 제거합니다. 따라서 return-response 내에서 사용되는 모든 Liquid 템플릿은 입력으로 빈 문자열을 수신하고 예상 출력을 생성하지 않습니다.

지원되는 Liquid 필터

다음 Liquid 필터는 set-body 정책에서 지원됩니다. 필터 예제는 Liquid 설명서를 참조하세요.

참고 항목

정책에는 Liquid 필터 이름에 대한 파스칼 대/소문자(예: "at_least" 대신 "AtLeast")가 필요합니다.

• Abs
• 추가
• AtLeast
• AtMost
• 대문자로 시작
• Compact
• 통화
• 날짜
• 기본값
• DividedBy
• 다운케이스
• Esc
• First
• H
• Join
• 마지막
• Lstrip
• 지도
• 빼기
• 모듈로
• NewlineToBr
• +
• 추가
• 제거
• RemoveFirst
• 바꾸기
• ReplaceFirst
• Round
• Rstrip
• 크기
• 조각
• 정렬
• 분할
• 스트립
• StripHtml
• StripNewlines
• 시간
• Truncate
• TruncateWords
• 유니크(동음이의)
• 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 Call 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>

관련 정책

• 변환

관련 콘텐츠

정책 작업에 대한 자세한 내용은 다음을 참조하세요.

• 자습서: API 변환 및 보호
• 정책 문 및 해당 설정에 대한 전체 목록에 대한 정책 참조
• 정책 식
• 정책 설정 또는 편집
• 정책 구성 재사용
• 정책 코드 조각 리포지토리
• Azure의 Microsoft Copilot을 사용하는 작성자 정책