Políticas de transformação de Gerenciamento de APIAPI Management transformation policies

Este tópico fornece uma referência para as políticas de Gerenciamento de API a seguir.This topic provides a reference for the following API Management policies. Para obter mais informações sobre como adicionar e configurar políticas, consulte Políticas de Gerenciamento de API.For information on adding and configuring policies, see Policies in API Management.

Políticas de transformaçãoTransformation policies

Converter JSON para XMLConvert JSON to XML

A política json-to-xml converte o corpo da solicitação ou da resposta de JSON para XML.The json-to-xml policy converts a request or response body from JSON to XML.

Declaração de políticaPolicy statement

<json-to-xml apply="always | content-type-json" consider-accept-header="true | false" parse-date="true | false"/>

ExemploExample

<policies>
    <inbound>
        <base />
    </inbound>
    <outbound>
        <base />
        <json-to-xml apply="always" consider-accept-header="false" parse-date="false"/>
    </outbound>
</policies>

ElementosElements

NOMEName DESCRIÇÃODescription ObrigatórioRequired
json-to-xmljson-to-xml Elemento raiz.Root element. SimYes

AtributosAttributes

NOMEName DESCRIÇÃODescription ObrigatórioRequired PadrãoDefault
aplicarapply O atributo deve ser definido como um dos valores a seguir.The attribute must be set to one of the following values.

– always – sempre aplicar conversão.- always - always apply conversion.
– content-type-json – converter somente se o cabeçalho Content-Type da resposta indica a presença de JSON.- content-type-json - convert only if response Content-Type header indicates presence of JSON.
SimYes N/DN/A
consider-accept-headerconsider-accept-header O atributo deve ser definido como um dos valores a seguir.The attribute must be set to one of the following values.

– true – aplica conversão se JSON é solicitado no cabeçalho Accept da solicitação.- true - apply conversion if JSON is requested in request Accept header.
– false – sempre aplicar conversão.- false -always apply conversion.
NãoNo verdadeirotrue
parse-dateparse-date Quando definido como false, os valores de data são simplesmente copiados durante a transformaçãoWhen set to false date values are simply copied during transformation NãoNo verdadeirotrue

UsoUsage

Essa política pode ser usada nas seções e nos escopos da política a seguir.This policy can be used in the following policy sections and scopes.

  • Seções de política: de entrada, de saída, em caso de erroPolicy sections: inbound, outbound, on-error

  • Escopos de política: global, produto, API, operaçãoPolicy scopes: global, product, API, operation

Converter XML para JSONConvert XML to JSON

A política xml-to-json converte o corpo da solicitação ou da resposta de XML para JSON.The xml-to-json policy converts a request or response body from XML to JSON. Esta política pode ser usada para modernizar APIs baseadas em serviços Web de back-end somente XML.This policy can be used to modernize APIs based on XML-only backend web services.

Declaração de políticaPolicy statement

<xml-to-json kind="javascript-friendly | direct" apply="always | content-type-xml" consider-accept-header="true | false"/>

ExemploExample

<policies>
    <inbound>
        <base />
    </inbound>
    <outbound>
        <base />
        <xml-to-json kind="direct" apply="always" consider-accept-header="false" />
    </outbound>
</policies>

ElementosElements

NOMEName DESCRIÇÃODescription ObrigatórioRequired
xml-to-jsonxml-to-json Elemento raiz.Root element. SimYes

AtributosAttributes

NOMEName DESCRIÇÃODescription ObrigatórioRequired PadrãoDefault
kindkind O atributo deve ser definido como um dos valores a seguir.The attribute must be set to one of the following values.

– javascript-friendly – o JSON convertido tem um formato amigável para desenvolvedores de JavaScript.- javascript-friendly - the converted JSON has a form friendly to JavaScript developers.
– direct – o JSON convertido reflete a estrutura do documento XML original.- direct - the converted JSON reflects the original XML document's structure.
SimYes N/DN/A
aplicarapply O atributo deve ser definido como um dos valores a seguir.The attribute must be set to one of the following values.

– always – converter sempre.- always - convert always.
– content-type-xml – converter somente se o cabeçalho Content-Type da resposta indica a presença de XML.- content-type-xml - convert only if response Content-Type header indicates presence of XML.
SimYes N/DN/A
consider-accept-headerconsider-accept-header O atributo deve ser definido como um dos valores a seguir.The attribute must be set to one of the following values.

– true – aplica conversão se XML é solicitado no cabeçalho Accept da solicitação.- true - apply conversion if XML is requested in request Accept header.
– false – sempre aplicar conversão.- false -always apply conversion.
NãoNo verdadeirotrue

UsoUsage

Essa política pode ser usada nas seções e nos escopos da política a seguir.This policy can be used in the following policy sections and scopes.

  • Seções de política: de entrada, de saída, em caso de erroPolicy sections: inbound, outbound, on-error

  • Escopos de política: global, produto, API, operaçãoPolicy scopes: global, product, API, operation

Localizar e substituir cadeia de caracteres no corpoFind and replace string in body

A política find-and-replace Encontra uma subcadeia de caracteres de uma solicitação ou resposta e a substitui por outra subcadeia de caracteres.The find-and-replace policy finds a request or response substring and replaces it with a different substring.

Declaração de políticaPolicy statement

<find-and-replace from="what to replace" to="replacement" />

ExemploExample

<find-and-replace from="notebook" to="laptop" />

ElementosElements

NOMEName DESCRIÇÃODescription ObrigatórioRequired
find-and-replacefind-and-replace Elemento raiz.Root element. SimYes

AtributosAttributes

NOMEName DESCRIÇÃODescription ObrigatórioRequired PadrãoDefault
fromfrom A cadeia a ser pesquisada.The string to search for. SimYes N/DN/A
parato A cadeia de caracteres de substituição.The replacement string. Especifique uma cadeia de substituição de comprimento zero para remover a cadeia de caracteres de pesquisa.Specify a zero length replacement string to remove the search string. SimYes N/DN/A

UsoUsage

Essa política pode ser usada nas seções e nos escopos da política a seguir.This policy can be used in the following policy sections and scopes.

  • Seções da política: entrada, saída, back-end, em caso de erroPolicy sections: inbound, outbound, backend, on-error

  • Escopos de política: global, produto, API, operaçãoPolicy scopes: global, product, API, operation

Mascarar URLs no conteúdoMask URLs in content

A política redirect-content-urls reescreve (mascara) os links no corpo da resposta para que eles apontem para o link equivalente por meio do gateway.The redirect-content-urls policy re-writes (masks) links in the response body so that they point to the equivalent link via the gateway. Use na seção de saída para regravar links de corpo da resposta para que apontem para o gateway.Use in the outbound section to re-write response body links to make them point to the gateway. Use na seção de entrada para obter um efeito oposto.Use in the inbound section for an opposite effect.

Observação

Essa política não altera nenhum valor de cabeçalho como cabeçalhos Location.This policy does not change any header values such as Location headers. Para alterar valores de cabeçalho, use a política set-header.To change header values, use the set-header policy.

Declaração de políticaPolicy statement

<redirect-content-urls />

ExemploExample

<redirect-content-urls />

ElementosElements

NOMEName DESCRIÇÃODescription ObrigatórioRequired
redirect-content-urlsredirect-content-urls Elemento raiz.Root element. SimYes

UsoUsage

Essa política pode ser usada nas seções e nos escopos da política a seguir.This policy can be used in the following policy sections and scopes.

  • Seções de política: de entrada, de saídaPolicy sections: inbound, outbound

  • Escopos de política: global, produto, API, operaçãoPolicy scopes: global, product, API, operation

Definir o serviço de back-endSet backend service

Use a política set-backend-service para redirecionar uma solicitação de entrada para um back-end diferente daquele especificado nas configurações de API para essa operação.Use the set-backend-service policy to redirect an incoming request to a different backend than the one specified in the API settings for that operation. Essa política altera a URL base do serviço de back-end da solicitação de entrada para aquele especificado na política.This policy changes the backend service base URL of the incoming request to the one specified in the policy.

Declaração de políticaPolicy statement

<set-backend-service base-url="base URL of the backend service" />

ou oor

<set-backend-service backend-id="identifier of the backend entity specifying base URL of the backend service" />

Observação

Entidades de back-end podem ser gerenciadas por meio do gerenciamento API e PowerShell.Backend entities can be managed via management API and PowerShell.

ExemploExample

<policies>
    <inbound>
        <choose>
            <when condition="@(context.Request.Url.Query.GetValueOrDefault("version") == "2013-05")">
                <set-backend-service base-url="http://contoso.com/api/8.2/" />
            </when>
            <when condition="@(context.Request.Url.Query.GetValueOrDefault("version") == "2014-03")">
                <set-backend-service base-url="http://contoso.com/api/9.1/" />
            </when>
        </choose>
        <base />
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>

Neste exemplo, a política de serviço de back-end do conjunto roteia solicitações com base no valor da versão passado na cadeia de consulta para um serviço de back-end diferente daquele especificado na API.In this example the set backend service policy routes requests based on the version value passed in the query string to a different backend service than the one specified in the API.

Inicialmente, a URL base do serviço de back-end é derivada das configurações de API.Initially the backend service base URL is derived from the API settings. Assim, a URL da solicitação https://contoso.azure-api.net/api/partners/15?version=2013-05&subscription-key=abcdef se torna http://contoso.com/api/10.4/partners/15?version=2013-05&subscription-key=abcdef em que http://contoso.com/api/10.4/ é a URL do serviço de back-end especificada nas configurações de API.So the request URL https://contoso.azure-api.net/api/partners/15?version=2013-05&subscription-key=abcdef becomes http://contoso.com/api/10.4/partners/15?version=2013-05&subscription-key=abcdef where http://contoso.com/api/10.4/ is the backend service URL specified in the API settings.

Quando a instrução de política <choose> é aplicada, a URL base do serviço de back-end pode se alterar novamente para http://contoso.com/api/8.2 ou http://contoso.com/api/9.1, dependendo do valor do parâmetro de consulta de solicitação de versão.When the <choose> policy statement is applied the backend service base URL may change again either to http://contoso.com/api/8.2 or http://contoso.com/api/9.1, depending on the value of the version request query parameter. Por exemplo, se o valor for "2013-15", a URL da solicitação final se tornará http://contoso.com/api/8.2/partners/15?version=2013-05&subscription-key=abcdef.For example, if the value is "2013-15" the final request URL becomes http://contoso.com/api/8.2/partners/15?version=2013-05&subscription-key=abcdef.

Se ainda mais transformação da solicitação for desejada, outras políticas de transformação poderão ser usadas.If further transformation of the request is desired, other Transformation policies can be used. Por exemplo, para remover o parâmetro de consulta de versão agora que a solicitação está sendo roteada para um back-end específico da versão, a política Definir parâmetro de cadeia de caracteres de consulta pode ser usada para remover o atributo de versão agora redundante.For example, to remove the version query parameter now that the request is being routed to a version specific backend, the Set query string parameter policy can be used to remove the now redundant version attribute.

ExemploExample

<policies>
    <inbound>
        <set-backend-service backend-id="my-sf-service" sf-partition-key="@(context.Request.Url.Query.GetValueOrDefault("userId","")" sf-replica-type="primary" />
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>

Neste exemplo, a política encaminha a solicitação para um back-end de Service Fabric usando a cadeia de caracteres de consulta userId como a chave de partição e usando a réplica primária da partição.In this example the policy routes the request to a service fabric backend, using the userId query string as the partition key and using the primary replica of the partition.

ElementosElements

NOMEName DESCRIÇÃODescription ObrigatórioRequired
set-backend-serviceset-backend-service Elemento raiz.Root element. SimYes

AtributosAttributes

NOMEName DESCRIÇÃODescription ObrigatórioRequired PadrãoDefault
base-urlbase-url Nova URL base do serviço de back-end.New backend service base URL. Um dos base-url ou backend-id deve estar presente.One of base-url or backend-id must be present. N/DN/A
backend-idbackend-id Identificador do back-end para o qual encaminhar.Identifier of the backend to route to. (Entidades de back-end são gerenciadas por meio API e PowerShell.)(Backend entities are managed via API and PowerShell.) Um dos base-url ou backend-id deve estar presente.One of base-url or backend-id must be present. N/DN/A
sf-partition-keysf-partition-key Aplicável somente quando o back-end é um serviço do Service Fabric e é especificado usando 'backend-id'.Only applicable when the backend is a Service Fabric service and is specified using 'backend-id'. Usado para resolver uma partição específica do serviço de resolução de nome.Used to resolve a specific partition from the name resolution service. NãoNo N/DN/A
sf-replica-typesf-replica-type Aplicável somente quando o back-end é um serviço do Service Fabric e é especificado usando 'backend-id'.Only applicable when the backend is a Service Fabric service and is specified using 'backend-id'. Controla se a solicitação deve ir para a réplica primária ou secundária de uma partição.Controls if the request should go to the primary or secondary replica of a partition. NãoNo N/DN/A
sf-resolve-conditionsf-resolve-condition Aplicável somente quando o back-end é um serviço do Service Fabric.Only applicable when the backend is a Service Fabric service. Condição que identifica se a chamada para o back-end do Service Fabric deve ser repetida com a nova resolução.Condition identifying if the call to Service Fabric backend has to be repeated with new resolution. NãoNo N/DN/A
sf-service-instance-namesf-service-instance-name Aplicável somente quando o back-end é um serviço do Service Fabric.Only applicable when the backend is a Service Fabric service. Permite alterar as instâncias de serviço em tempo de execução.Allows to change service instances at runtime. NãoNo N/DN/A
sf-listener-namesf-listener-name Aplicável somente quando o back-end é um serviço do Service Fabric e é especificado usando "backend-id".Only applicable when the backend is a Service Fabric service and is specified using ‘backend-id’. O Reliable Services do Service Fabric permite que você crie vários ouvintes em um serviço.Service Fabric Reliable Services allows you to create multiple listeners in a service. Este atributo é usado para selecionar um ouvinte específico quando um Reliable Service de back-end tiver mais de um ouvinte.This attribute is used to select a specific listener when a backend Reliable Service has more than one listener. Se esse atributo não for especificado, o Gerenciamento de API tentará usar um ouvinte sem nome.If this attribute is not specified, API Management will attempt to use a listener without a name. Um ouvinte sem nome é comum para o Reliable Services, que têm apenas um ouvinte.A listener without a name is typical for Reliable Services that have only one listener. NãoNo N/DN/A

UsoUsage

Essa política pode ser usada nas seções e nos escopos da política a seguir.This policy can be used in the following policy sections and scopes.

  • Seções de política: de entrada, back-endPolicy sections: inbound, backend

  • Escopos de política: global, produto, API, operaçãoPolicy scopes: global, product, API, operation

Definir corpoSet body

Use a política set-body para definir o corpo da mensagem para solicitações de entrada e saída.Use the set-body policy to set the message body for incoming and outgoing requests. Para acessar o corpo da mensagem, você pode usar a propriedade context.Request.Body ou a context.Response.Body, dependendo da seção em que a política está: de entrada ou de saída.To access the message body you can use the context.Request.Body property or the context.Response.Body, depending on whether the policy is in the inbound or outbound section.

Importante

Observe que, por padrão, quando você acessa o corpo da mensagem usando context.Request.Body ou context.Response.Body, o corpo da mensagem original é perdido e deve ser definido por meio do retorno do corpo de volta na expressão.Note that by default when you access the message body using context.Request.Body or context.Response.Body, the original message body is lost and must be set by returning the body back in the expression. Para preservar o conteúdo do corpo, defina o parâmetro preserveContent para true ao acessar a mensagem.To preserve the body content, set the preserveContent parameter to true when accessing the message. Se preserveContent é definido para true e um corpo diferente é retornado pela expressão, o corpo retornado é usado.If preserveContent is set to true and a different body is returned by the expression, the returned body is used.

Observe as seguintes considerações ao usar a política set-body.Please note the following considerations when using the set-body policy.

  • Se você estiver usando a política set-body para retornar um corpo novo ou atualizado, você não precisará definir preserveContent para true porque você estará fornecendo explicitamente o novo conteúdo do corpo.If you are using the set-body policy to return a new or updated body you don't need to set preserveContent to true because you are explicitly supplying the new body contents.
    • Preservar o conteúdo de uma resposta no pipeline de entrada não faz sentido, porque ainda não há nenhuma resposta.Preserving the content of a response in the inbound pipeline doesn't make sense because there is no response yet.
    • Preservar o conteúdo de uma solicitação no pipeline de saída não faz sentido porque nesse momento a solicitação já foi enviada para o back-end.Preserving the content of a request in the outbound pipeline doesn't make sense because the request has already been sent to the backend at this point.
    • Se essa política é usada quando não há nenhum corpo da mensagem, por exemplo em um GET de entrada, uma exceção é lançada.If this policy is used when there is no message body, for example in an inbound GET, an exception is thrown.

Para obter mais informações, consulte as seções context.Request.Body, context.Response.Body e IMessage na tabela Variável de contexto.For more information, see the context.Request.Body, context.Response.Body, and the IMessage sections in the Context variable table.

Declaração de políticaPolicy statement

<set-body>new body value as text</set-body>

ExemplosExamples

Exemplo de texto literalLiteral text example

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

Exemplo de acesso ao corpo como uma cadeia de caracteres.Example accessing the body as a string. Observe que estamos preservando o corpo da solicitação original, de forma que possamos acessá-lo mais tarde no pipeline.Note that we are preserving the original request body so that we can access it later in the pipeline.

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

Exemplo de acesso ao corpo como um JObject.Example accessing the body as a JObject. Observe que, como não estamos reservando o corpo da solicitação original, acessá-lo mais tarde no pipeline resultará em uma exceção.Note that since we are not reserving the original request body, accessing it later in the pipeline will result in an exception.

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

Resposta de filtro com base no produtoFilter response based on product

Este exemplo mostra como executar a filtragem de conteúdo removendo elementos de dados da resposta recebida do serviço de back-end ao usar o produto Starter.This example shows how to perform content filtering by removing data elements from the response received from the backend service when using the Starter product. Para obter uma demonstração de como configurar e usar essa política, assista ao vídeo Cloud Cover Episode 177: More API Management Features with Vlad Vinogradsky (Cloud Cover, episódio 3430: Mais recursos de Gerenciamento de API com Vlad Vinogradsky) e avance para 34min30s.For a demonstration of configuring and using this policy, see Cloud Cover Episode 177: More API Management Features with Vlad Vinogradsky and fast-forward to 34:30. Inicie em 31:50 para uma visão geral da API da Previsão de Céu Escuro usada para esta demonstração.Start at 31:50 to see an overview of The Dark Sky Forecast API used for this demo.

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

Usando modelos Líquidos com o corpo definidoUsing Liquid templates with set body

A política set-body pode ser configurada para usar a linguagem de modelagem Líquida para transformar o corpo de uma solicitação ou resposta.The set-body policy can be configured to use the Liquid templating language to transform the body of a request or response. Isso poderá ser muito eficaz se você precisar remodelar por completo o formato da mensagem.This can be very effective if you need to completely reshape the format of your message.

Importante

A implementação de Líquido usado na política set-body é configurada no “modo C#”.The implementation of Liquid used in the set-body policy is configured in 'C# mode'. Isso é particularmente importante ao executar ações como filtragem.This is particularly important when doing things such as filtering. Por exemplo, o uso de um filtro de data exige o uso de maiúsculas Pascal e da formatação das datas do C#, por exemplo:As an example, using a date filter requires the use of Pascal casing and C# date formatting e.g.:

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

Importante

Para associar corretamente a um corpo XML usando o modelo Líquido, use uma política set-header para definir Content-Type como application/xml, text/xml (ou qualquer tipo que termina com +xml); para um corpo JSON, ele deve ser application/json, text/json (ou qualquer tipo que termina com +json).In order to correctly bind to an XML body using the Liquid template, use a set-header policy to set Content-Type to either application/xml, text/xml (or any type ending with +xml); for a JSON body, it must be application/json, text/json (or any type ending with +json).

Converter JSON em SOAP usando um modelo LíquidoConvert JSON to SOAP using a Liquid template

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

Transformar JSON usando um modelo líquidoTransform JSON using a Liquid template

{
"order": {
    "id": "{{body.customer.purchase.identifier}}",
    "summary": "{{body.customer.purchase.orderShortDesc}}"
    }
}

ElementosElements

NOMEName DESCRIÇÃODescription ObrigatórioRequired
set-bodyset-body Elemento raiz.Root element. Contém o texto do corpo ou expressões que retornam um corpo.Contains the body text or an expressions that returns a body. SimYes

propriedadesProperties

NOMEName DESCRIÇÃODescription ObrigatórioRequired PadrãoDefault
templatetemplate Usado para alterar o modo de modelagem no qual a política de corpo definida será executada.Used to change the templating mode that the set body policy will run in. Atualmente, o único valor aceito é:Currently the only supported value is:

- liquid – a política de corpo definida usará o mecanismo de modelagem líquida- liquid - the set body policy will use the liquid templating engine
NãoNo

Para acessar informações sobre a solicitação e a resposta, o modelo Líquido pode ser associado a um objeto de contexto com as seguintes propriedades:For accessing information about the request and response, the Liquid template can bind to a context object with the following properties:

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

UsoUsage

Essa política pode ser usada nas seções e nos escopos da política a seguir.This policy can be used in the following policy sections and scopes.

  • Seções de política: entrada, saída, back-endPolicy sections: inbound, outbound, backend

  • Escopos de política: global, produto, API, operaçãoPolicy scopes: global, product, API, operation

Definir cabeçalho HTTPSet HTTP header

A política set-header atribui um valor a uma resposta e/ou cabeçalho de resposta existente ou adiciona uma nova resposta e/ou cabeçalho de resposta.The set-header policy assigns a value to an existing response and/or request header or adds a new response and/or request header.

Insere uma lista de cabeçalhos HTTP em uma mensagem HTTP.Inserts a list of HTTP headers into an HTTP message. Quando colocada em um pipeline de entrada, esta política define os cabeçalhos HTTP para a solicitação que está sendo passada para o serviço alvo.When placed in an inbound pipeline, this policy sets the HTTP headers for the request being passed to the target service. Quando colocada em um pipeline de saída, esta política define os cabeçalhos HTTP para a resposta que está sendo passada para o cliente do gateway.When placed in an outbound pipeline, this policy sets the HTTP headers for the response being sent to the gateway’s client.

Declaração de políticaPolicy statement

<set-header name="header name" exists-action="override | skip | append | delete">
    <value>value</value> <!--for multiple headers with the same name add additional value elements-->
</set-header>

ExemplosExamples

ExemploExample

<set-header name="some header name" exists-action="override">
    <value>20</value>
</set-header>

Encaminhar informações de contexto para o serviço de back-endForward context information to the backend service

Este exemplo mostra como aplicar a política no nível da API para fornecer informações de contexto para o serviço de back-end.This example shows how to apply policy at the API level to supply context information to the backend service. Para obter uma demonstração de como configurar e usar essa política, assista ao vídeo Cloud Cover Episode 177: Mais recursos de Gerenciamento de API com Vlad Vinogradsky e avance para 10:30.For a demonstration of configuring and using this policy, see Cloud Cover Episode 177: More API Management Features with Vlad Vinogradsky and fast-forward to 10:30. Em 12:10, há uma demonstração de chamada de uma operação no portal do desenvolvedor na qual você pode ver a política em ação.At 12:10 there is a demo of calling an operation in the developer portal where you can see the policy at work.

<!-- Copy this snippet into the inbound element to forward some context information, user id and the region the gateway is hosted in, to the backend service for logging or evaluation -->
<set-header name="x-request-context-data" exists-action="override">
  <value>@(context.User.Id)</value>
  <value>@(context.Deployment.Region)</value>
</set-header>

Para obter mais informações, veja Expressões de política e Variável de contexto.For more information, see Policy expressions and Context variable.

Observação

Vários valores de um cabeçalho são concatenados em uma cadeia de caracteres CSV, por exemplo: headerName: value1,value2,value3Multiple values of a header are concatenated to a CSV string, for example: headerName: value1,value2,value3

As exceções incluem cabeçalhos padronizados, cujos valores:Exceptions include standardized headers, which values:

  • podem conter vírgulas (User-Agent, WWW-Authenticate, Proxy-Authenticate),may contain commas (User-Agent, WWW-Authenticate, Proxy-Authenticate),
  • podem conter a data (Cookie, Set-Cookie, Warning),may contain date (Cookie, Set-Cookie, Warning),
  • contêm a data (Date, Expires, If-Modified-Since, If-Unmodified-Since, Last-Modified, Retry-After).contain date (Date, Expires, If-Modified-Since, If-Unmodified-Since, Last-Modified, Retry-After).

No caso de exceções, vários valores de cabeçalho não serão concatenados em uma cadeia de caracteres e serão passados como cabeçalhos separados, por exemplo: User-Agent: value1 User-Agent: value2 User-Agent: value3In case of those exceptions, multiple header values will not be concatenated into one string and will be passed as separate headers, for example: User-Agent: value1 User-Agent: value2 User-Agent: value3

ElementosElements

NOMEName DESCRIÇÃODescription ObrigatórioRequired
set-headerset-header Elemento raiz.Root element. SimYes
valuevalue Especifica o valor do cabeçalho a ser definido.Specifies the value of the header to be set. Para adicionar vários cabeçalhos com o mesmo nome, adicione elementos value adicionais.For multiple headers with the same name add additional value elements. SimYes

propriedadesProperties

NOMEName DESCRIÇÃODescription ObrigatórioRequired PadrãoDefault
exists-actionexists-action Especifica a ação a ser adotada quando o cabeçalho já foi especificado.Specifies what action to take when the header is already specified. Este atributo deve ter um dos valores a seguir.This attribute must have one of the following values.

– override – substitui o valor do cabeçalho existente.- override - replaces the value of the existing header.
– skip – não substitui o valor do cabeçalho existente.- skip - does not replace the existing header value.
– append – acrescenta o valor ao valor do cabeçalho existente.- append - appends the value to the existing header value.
– delete – remove o cabeçalho da solicitação.- delete - removes the header from the request.

Quando definido como override, listar diversas entradas com o mesmo nome faz com que o cabeçalho seja definido de acordo com todas as entradas (que serão listadas várias vezes); somente valores listados serão definidos no resultado.When set to override enlisting multiple entries with the same name results in the header being set according to all entries (which will be listed multiple times); only listed values will be set in the result.
NãoNo overrideoverride
namename Especifica o nome do cabeçalho a ser definido.Specifies name of the header to be set. SimYes N/DN/A

UsoUsage

Essa política pode ser usada nas seções e nos escopos da política a seguir.This policy can be used in the following policy sections and scopes.

  • Seções da política: entrada, saída, back-end, em caso de erroPolicy sections: inbound, outbound, backend, on-error

  • Escopos de política: global, produto, API, operaçãoPolicy scopes: global, product, API, operation

Definir parâmetro de cadeia de consultaSet query string parameter

A política set-query-parameter adiciona, substitui o valor ou exclui parâmetros de cadeias de consulta de solicitação.The set-query-parameter policy adds, replaces value of, or deletes request query string parameter. Pode ser usada para transmitir parâmetros de consulta esperados pelo serviço de back-end que são opcionais ou nunca estão presentes na solicitação.Can be used to pass query parameters expected by the backend service which are optional or never present in the request.

Declaração de políticaPolicy statement

<set-query-parameter name="param name" exists-action="override | skip | append | delete">
    <value>value</value> <!--for multiple parameters with the same name add additional value elements-->
</set-query-parameter>

ExemplosExamples

ExemploExample


<set-query-parameter>
  <parameter name="api-key" exists-action="skip">
    <value>12345678901</value>
  </parameter>
  <!-- for multiple parameters with the same name add additional value elements -->
</set-query-parameter>

Encaminhar informações de contexto para o serviço de back-endForward context information to the backend service

Este exemplo mostra como aplicar a política no nível da API para fornecer informações de contexto para o serviço de back-end.This example shows how to apply policy at the API level to supply context information to the backend service. Para obter uma demonstração de como configurar e usar essa política, assista ao vídeo Cloud Cover Episode 177: Mais recursos de Gerenciamento de API com Vlad Vinogradsky e avance para 10:30.For a demonstration of configuring and using this policy, see Cloud Cover Episode 177: More API Management Features with Vlad Vinogradsky and fast-forward to 10:30. Em 12:10, há uma demonstração de chamada de uma operação no portal do desenvolvedor na qual você pode ver a política em ação.At 12:10 there is a demo of calling an operation in the developer portal where you can see the policy at work.

<!-- Copy this snippet into the inbound element to forward a piece of context, product name in this example, to the backend service for logging or evaluation -->
<set-query-parameter name="x-product-name" exists-action="override">
  <value>@(context.Product.Name)</value>
</set-query-parameter>

Para obter mais informações, veja Expressões de política e Variável de contexto.For more information, see Policy expressions and Context variable.

ElementosElements

NOMEName DESCRIÇÃODescription ObrigatórioRequired
set-query-parameterset-query-parameter Elemento raiz.Root element. SimYes
valuevalue Especifica o valor do parâmetro de consulta a ser definido.Specifies the value of the query parameter to be set. Para adicionar vários parâmetros de consulta com o mesmo nome, adicione elementos value adicionais.For multiple query parameters with the same name add additional value elements. SimYes

propriedadesProperties

NOMEName DESCRIÇÃODescription ObrigatórioRequired PadrãoDefault
exists-actionexists-action Especifica a ação a ser adotada quando o parâmetro de consulta já foi especificado.Specifies what action to take when the query parameter is already specified. Este atributo deve ter um dos valores a seguir.This attribute must have one of the following values.

– override – substitui o valor do parâmetro existente.- override - replaces the value of the existing parameter.
– skip – não substitui o valor do parâmetro de consulta existente.- skip - does not replace the existing query parameter value.
– append – acrescenta o valor ao valor do parâmetro de consulta existente.- append - appends the value to the existing query parameter value.
– delete – remove o parâmetro de consulta da solicitação.- delete - removes the query parameter from the request.

Quando definido como override, listar diversas entradas com o mesmo nome faz com que o parâmetro de consulta seja definido de acordo com todas as entradas (que serão listadas várias vezes); somente valores listados serão definidos no resultado.When set to override enlisting multiple entries with the same name results in the query parameter being set according to all entries (which will be listed multiple times); only listed values will be set in the result.
NãoNo overrideoverride
namename Especifica o nome do parâmetro de consulta a ser definido.Specifies name of the query parameter to be set. SimYes N/DN/A

UsoUsage

Essa política pode ser usada nas seções e nos escopos da política a seguir.This policy can be used in the following policy sections and scopes.

  • Seções de política: de entrada, back-endPolicy sections: inbound, backend

  • Escopos de política: global, produto, API, operaçãoPolicy scopes: global, product, API, operation

Reescrever URLRewrite URL

A política rewrite-uri converte a URL de uma solicitação de sua forma pública para a forma esperada pelo serviço Web, conforme mostrado no exemplo a seguir.The rewrite-uri policy converts a request URL from its public form to the form expected by the web service, as shown in the following example.

  • URL pública – http://api.example.com/storenumber/ordernumberPublic URL - http://api.example.com/storenumber/ordernumber

  • URL de Solicitação – http://api.example.com/v2/US/hardware/storenumber&ordernumber?City&StateRequest URL - http://api.example.com/v2/US/hardware/storenumber&ordernumber?City&State

    Essa política pode ser usada quando uma URL simplificada para humanos e/ou navegadores precisar ser transformado na URL esperada pelo serviço Web.This policy can be used when a human and/or browser-friendly URL should be transformed into the URL format expected by the web service. Essa política só precisa ser aplicada ao expor um formato de URL alternativo como URLs limpas, URLs RESTful, URLs simplificadas para usuários ou para URLs amigáveis ao SEO que são URLs puramente estruturais que não contêm uma cadeia de consulta, contendo somente o caminho do recurso (após o esquema e autoridade).This policy only needs to be applied when exposing an alternative URL format, such as clean URLs, RESTful URLs, user-friendly URLs or SEO-friendly URLs that are purely structural URLs that do not contain a query string and instead contain only the path of the resource (after the scheme and the authority). Frequentemente, isso é feito para fins estéticos, de usabilidade ou de otimização do mecanismo de pesquisa (SEO).This is often done for aesthetic, usability, or search engine optimization (SEO) purposes.

Observação

Você pode adicionar somente parâmetros de cadeia de consulta usando a política.You can only add query string parameters using the policy. Você não pode adicionar parâmetros de caminho do modelo extra à URL reescrita.You cannot add extra template path parameters in the rewrite URL.

Declaração de políticaPolicy statement

<rewrite-uri template="uri template" copy-unmatched-params="true | false" />

ExemploExample

<policies>
    <inbound>
        <base />
        <rewrite-uri template="/v2/US/hardware/{storenumber}&{ordernumber}?City=city&State=state" />
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>
<!-- Assuming incoming request is /get?a=b&c=d and operation template is set to /get?a={b} -->
<policies>
    <inbound>
        <base />
        <rewrite-uri template="/put" />
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>
<!-- Resulting URL will be /put?c=d -->
<!-- Assuming incoming request is /get?a=b&c=d and operation template is set to /get?a={b} -->
<policies>
    <inbound>
        <base />
        <rewrite-uri template="/put" copy-unmatched-params="false" />
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>
<!-- Resulting URL will be /put -->

ElementosElements

NOMEName DESCRIÇÃODescription ObrigatórioRequired
rewrite-urirewrite-uri Elemento raiz.Root element. SimYes

AtributosAttributes

AtributoAttribute DESCRIÇÃODescription ObrigatórioRequired PadrãoDefault
templatetemplate A URL real do serviço Web com quaisquer parâmetros de cadeia de consulta.The actual web service URL with any query string parameters. Ao usar expressões, o valor inteiro deve ser uma expressão.When using expressions, the whole value must be an expression. SimYes N/DN/A
copy-unmatched-paramscopy-unmatched-params Especifica se os parâmetros de consulta na solicitação de entrada não presentes no modelo de URL original são adicionados à URL definida pelo modelo reescritoSpecifies whether query parameters in the incoming request not present in the original URL template are added to the URL defined by the re-write template NãoNo verdadeirotrue

UsoUsage

Essa política pode ser usada nas seções e nos escopos da política a seguir.This policy can be used in the following policy sections and scopes.

  • Seções de política: de entradaPolicy sections: inbound

  • Escopos de política: global, produto, API, operaçãoPolicy scopes: global, product, API, operation

Transformar XML usando um XSLTTransform XML using an XSLT

A política Transform XML using an XSLT aplica uma transformação XSL para XML no corpo da solicitação ou da resposta.The Transform XML using an XSLT policy applies an XSL transformation to XML in the request or response body.

Declaração de políticaPolicy statement

<xsl-transform>
    <parameter name="User-Agent">@(context.Request.Headers.GetValueOrDefault("User-Agent","non-specified"))</parameter>
    <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
        <xsl:output method="xml" indent="yes" />
        <xsl:param name="User-Agent" />
        <xsl:template match="* | @* | node()">
            <xsl:copy>
                <xsl:if test="self::* and not(parent::*)">
                    <xsl:attribute name="User-Agent">
                        <xsl:value-of select="$User-Agent" />
                    </xsl:attribute>
                </xsl:if>
                <xsl:apply-templates select="* | @* | node()" />
            </xsl:copy>
        </xsl:template>
    </xsl:stylesheet>
  </xsl-transform>

ExemploExample

<policies>
  <inbound>
      <base />
  </inbound>
  <outbound>
      <base />
      <xsl-transform>
        <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
            <xsl:output omit-xml-declaration="yes" method="xml" indent="yes" />
            <!-- Copy all nodes directly-->
            <xsl:template match="node()| @*|*">
                <xsl:copy>
                    <xsl:apply-templates select="@* | node()|*" />
                </xsl:copy>
            </xsl:template>
        </xsl:stylesheet>
    </xsl-transform>
  </outbound>
</policies>

ElementosElements

NOMEName DESCRIÇÃODescription ObrigatórioRequired
xsl-transformxsl-transform Elemento raiz.Root element. SimYes
parâmetroparameter Usado para definir as variáveis usadas na transformaçãoUsed to define variables used in the transform NãoNo
xsl:stylesheetxsl:stylesheet Elemento de folha de estilos de raiz.Root stylesheet element. Todos os elementos e atributos definidos dentro dele seguem o padrão especificação XSLTAll elements and attributes defined within follow the standard XSLT specification SimYes

UsoUsage

Essa política pode ser usada nas seções e nos escopos da política a seguir.This policy can be used in the following policy sections and scopes.

  • Seções de política: de entrada, de saídaPolicy sections: inbound, outbound

  • Escopos de política: global, produto, API, operaçãoPolicy scopes: global, product, API, operation

Próximas etapasNext steps

Para mais informações, consulte os seguintes tópicos:For more information, see the following topics: