Políticas avançadas de Gerenciamento de APIAPI Management advanced 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 avançadasAdvanced policies

Controlar fluxoControl flow

A política choose aplica declarações de política embutidas com base no resultado da avaliação de expressões boolianas, semelhantes a um if-then-else ou a um constructo de opção em uma linguagem de programação.The choose policy applies enclosed policy statements based on the outcome of evaluation of Boolean expressions, similar to an if-then-else or a switch construct in a programming language.

Declaração de políticaPolicy statement

<choose>
    <when condition="Boolean expression | Boolean constant">
        <!— one or more policy statements to be applied if the above condition is true  -->
    </when>
    <when condition="Boolean expression | Boolean constant">
        <!— one or more policy statements to be applied if the above condition is true  -->
    </when>
    <otherwise>
        <!— one or more policy statements to be applied if none of the above conditions are true  -->
</otherwise>
</choose>

A política de fluxo de controle deve conter pelo menos um elemento <when/>.The control flow policy must contain at least one <when/> element. O elemento <otherwise/> é opcional.The <otherwise/> element is optional. As condições nos elementos <when/> são avaliadas na ordem de aparecimento na política.Conditions in <when/> elements are evaluated in order of their appearance within the policy. As declarações de política incluídas dentro do primeiro elemento <when/> com atributo de condição igual a true serão aplicadas.Policy statement(s) enclosed within the first <when/> element with condition attribute equals true will be applied. As políticas incluídas dentro do elemento <otherwise/>, se estiverem presentes, serão aplicadas se todos os atributos de condição do elemento <when/> forem false.Policies enclosed within the <otherwise/> element, if present, will be applied if all of the <when/> element condition attributes are false.

ExemplosExamples

ExemploExample

O exemplo a seguir demonstra uma política set-variable e duas políticas de fluxo de controle.The following example demonstrates a set-variable policy and two control flow policies.

A política de definir variável está na seção de entrada e cria uma variável de contexto booliana isMobile que será definida como true se o cabeçalho da solicitação User-Agent contiver o texto iPad ou iPhone.The set variable policy is in the inbound section and creates an isMobile Boolean context variable that is set to true if the User-Agent request header contains the text iPad or iPhone.

A primeira política de fluxo de controle também está na seção de entrada e aplica condicionalmente uma de duas políticas Definir parâmetro de cadeia de caracteres de consulta dependendo do valor da variável de contexto isMobile.The first control flow policy is also in the inbound section, and conditionally applies one of two Set query string parameter policies depending on the value of the isMobile context variable.

A segunda política de fluxo de controle está na seção de saída e aplica condicionalmente a política Converter XML para JSON quando isMobile é definida como true.The second control flow policy is in the outbound section and conditionally applies the Convert XML to JSON policy when isMobile is set to true.

<policies>
    <inbound>
        <set-variable name="isMobile" value="@(context.Request.Headers["User-Agent"].Contains("iPad") || context.Request.Headers["User-Agent"].Contains("iPhone"))" />
        <base />
        <choose>
            <when condition="@(context.Variables.GetValueOrDefault<bool>("isMobile"))">
                <set-query-parameter name="mobile" exists-action="override">
                    <value>true</value>
                </set-query-parameter>
            </when>
            <otherwise>
                <set-query-parameter name="mobile" exists-action="override">
                    <value>false</value>
                </set-query-parameter>
            </otherwise>
        </choose>
    </inbound>
    <outbound>
        <base />
        <choose>
            <when condition="@(context.Variables.GetValueOrDefault<bool>("isMobile"))">
                <xml-to-json kind="direct" apply="always" consider-accept-header="false"/>
            </when>
        </choose>
    </outbound>
</policies>

ExemploExample

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 ver uma visão geral das escuro céu de previsão com a API da 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>

ElementosElements

ElementoElement DESCRIÇÃODescription ObrigatórioRequired
choosechoose Elemento raiz.Root element. SimYes
whenwhen A condição a ser usada para as partes if ou ifelse da política choose.The condition to use for the if or ifelse parts of the choose policy. Se política choose tiver várias seções when, elas serão avaliadas sequencialmente.If the choose policy has multiple when sections, they are evaluated sequentially. Uma vez que o condition de um elemento when é avaliado como true, nenhuma outra condição when é avaliada.Once the condition of a when element evaluates to true, no further when conditions are evaluated. SimYes
otherwiseotherwise Contém o snippet de código da política a ser usado se nenhuma das condições when for avaliada como true.Contains the policy snippet to be used if none of the when conditions evaluate to true. NãoNo

AtributosAttributes

AtributoAttribute DESCRIÇÃODescription ObrigatórioRequired
condition="Boolean expression | Boolean constant"condition="Boolean expression | Boolean constant" A constante ou expressão booliana a ser avaliada quando a declaração de política contendo when é avaliada.The Boolean expression or constant to evaluated when the containing when policy statement is evaluated. 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 da política: entrada, saída, back-end, em caso de erroPolicy sections: inbound, outbound, backend, on-error

  • Escopos da política: todos os escoposPolicy scopes: all scopes

Encaminhar solicitaçãoForward request

A política forward-request encaminha a solicitação de entrada para o serviço de back-end especificado na variável de contexto de solicitação.The forward-request policy forwards the incoming request to the backend service specified in the request context. A URL do serviço de back-end é especificada na API as configurações e pode ser alterado usando o definir serviço de back-end política.The backend service URL is specified in the API settings and can be changed using the set backend service policy.

Observação

A remoção dessa política resulta na solicitação não ser encaminhada para o serviço de back-end e as políticas na seção de saída serem avaliadas imediatamente após a conclusão bem-sucedida das políticas na seção de entrada.Removing this policy results in the request not being forwarded to the backend service and the policies in the outbound section are evaluated immediately upon the successful completion of the policies in the inbound section.

Declaração de políticaPolicy statement

<forward-request timeout="time in seconds" follow-redirects="true | false" buffer-request-body="true | false" />

ExemplosExamples

ExemploExample

A política de nível de API a seguir encaminha todas as solicitações de API para o serviço de back-end com um intervalo de tempo limite de 60 segundos.The following API level policy forwards all API requests to the backend service with a timeout interval of 60 seconds.

<!-- api level -->
<policies>
    <inbound>
        <base/>
    </inbound>
    <backend>
        <forward-request timeout="60"/>
    </backend>
    <outbound>
        <base/>
    </outbound>
</policies>

ExemploExample

Esta política de nível de operação usa o elemento base para herdar a política de back-end do escopo de nível de API pai.This operation level policy uses the base element to inherit the backend policy from the parent API level scope.

<!-- operation level -->
<policies>
    <inbound>
        <base/>
    </inbound>
    <backend>
        <base/>
    </backend>
    <outbound>
        <base/>
    </outbound>
</policies>

ExemploExample

Essa política de nível de operação explicitamente encaminha todas as solicitações para o serviço de back-end com um tempo limite de 120 e não herda a política de back-end do nível da API pai.This operation level policy explicitly forwards all requests to the backend service with a timeout of 120 and does not inherit the parent API level backend policy.

<!-- operation level -->
<policies>
    <inbound>
        <base/>
    </inbound>
    <backend>
        <forward-request timeout="120"/>
        <!-- effective policy. note the absence of <base/> -->
    </backend>
    <outbound>
        <base/>
    </outbound>
</policies>

ExemploExample

Essa política de nível de operação não encaminha solicitações para o serviço de back-end.This operation level policy does not forward requests to the backend service.

<!-- operation level -->
<policies>
    <inbound>
        <base/>
    </inbound>
    <backend>
        <!-- no forwarding to backend -->
    </backend>
    <outbound>
        <base/>
    </outbound>
</policies>

ElementosElements

ElementoElement DESCRIÇÃODescription ObrigatórioRequired
forward-requestforward-request Elemento raiz.Root element. SimYes

AtributosAttributes

AtributoAttribute DESCRIÇÃODescription ObrigatórioRequired PadrãoDefault
timeout="integer"timeout="integer" A quantidade de tempo em segundos a esperar para os cabeçalhos de resposta HTTP a ser retornado pelo serviço de back-end antes de um erro de tempo limite é gerada.The amount of time in seconds to wait for the HTTP response headers to be returned by the backend service before a timeout error is raised. Valor mínimo é 0 segundos.Minimum value is 0 seconds. Valores superiores a 240 segundos não podem ser considerados como a infraestrutura de rede subjacente podem descartar conexões ociosas após esse período.Values greater than 240 seconds may not be honored as the underlying network infrastructure can drop idle connections after this time. NãoNo NenhumNone
follow-redirects="true | false"follow-redirects="true | false" Especifica se os redirecionamentos do serviço de back-end são seguidos pelo gateway ou retornados ao chamador.Specifies whether redirects from the backend service are followed by the gateway or returned to the caller. NãoNo falsofalse
buffer-request-body="true | false"buffer-request-body="true | false" Quando definido como "true" solicitação é armazenada em buffer e será reutilizado na Repita.When set to "true" request is buffered and will be reused on retry. NãoNo falsofalse

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: back-endPolicy sections: backend
  • Escopos da política: todos os escoposPolicy scopes: all scopes

Simultaneidade de limiteLimit concurrency

A política limit-concurrency impede que políticas fechadas sejam executadas por mais do que o número especificado de solicitações a qualquer momento.The limit-concurrency policy prevents enclosed policies from executing by more than the specified number of requests at any time. Ao exceder esse número, novos pedidos falharão imediatamente com o código de status 429 Número excessivo de solicitações.Upon exceeding that number, new requests will fail immediately with 429 Too Many Requests status code.

Declaração de políticaPolicy statement

<limit-concurrency key="expression" max-count="number">
        <!— nested policy statements -->
</limit-concurrency>

ExemplosExamples

ExemploExample

O exemplo a seguir demonstra como limitar o número de solicitações encaminhadas a um back-end com base no valor de uma variável de contexto.The following example demonstrates how to limit number of requests forwarded to a backend based on the value of a context variable.

<policies>
  <inbound>…</inbound>
  <backend>
    <limit-concurrency key="@((string)context.Variables["connectionId"])" max-count="3">
      <forward-request timeout="120"/>
    <limit-concurrency/>
  </backend>
  <outbound>…</outbound>
</policies>

ElementosElements

ElementoElement DESCRIÇÃODescription ObrigatórioRequired
limit-concurrencylimit-concurrency Elemento raiz.Root element. SimYes

AtributosAttributes

AtributoAttribute DESCRIÇÃODescription ObrigatórioRequired PadrãoDefault
chavekey Uma cadeia de caracteres.A string. Expressão permitida.Expression allowed. Especifica o escopo de simultaneidade.Specifies the concurrency scope. Pode ser compartilhado por várias políticas.Can be shared by multiple policies. SimYes N/DN/A
max-countmax-count Um inteiro.An integer. Especifica um número máximo de solicitações que são permitidas para inserir a política.Specifies a maximum number of requests that are allowed to enter the policy. 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 da política: todos os escoposPolicy scopes: all scopes

Registrar no Hub de EventosLog to Event Hub

A política log-to-eventhub envia mensagens no formato especificado para um Hub de Eventos definido por uma entidade Logger.The log-to-eventhub policy sends messages in the specified format to an Event Hub defined by a Logger entity. Como o nome sugere, a política é usada para salvar informações de contexto de solicitação ou de resposta solicitadas para a análise online ou offline.As its name implies, the policy is used for saving selected request or response context information for online or offline analysis.

Observação

Para obter um guia passo a passo sobre como configurar um hub de eventos e registrar eventos, consulte Como registrar eventos em log para Hubs de Eventos do Azure no Gerenciamento de API.For a step-by-step guide on configuring an event hub and logging events, see How to log API Management events with Azure Event Hubs.

Declaração de políticaPolicy statement

<log-to-eventhub logger-id="id of the logger entity" partition-id="index of the partition where messages are sent" partition-key="value used for partition assignment">
  Expression returning a string to be logged
</log-to-eventhub>

ExemploExample

Qualquer cadeia de caracteres pode ser usada como o valor a ser registrado em Hubs de Eventos.Any string can be used as the value to be logged in Event Hubs. Neste exemplo, a data e hora, nome do serviço de implantação, a ID de solicitação, endereço IP e o nome da operação para todas as chamadas de entrada são registrados no agente do hub de eventos registrado com a ID contoso-logger.In this example the date and time, deployment service name, request id, ip address, and operation name for all inbound calls are logged to the event hub Logger registered with the contoso-logger id.

<policies>
  <inbound>
    <log-to-eventhub logger-id ='contoso-logger'>
      @( string.Join(",", DateTime.UtcNow, context.Deployment.ServiceName, context.RequestId, context.Request.IpAddress, context.Operation.Name) )
    </log-to-eventhub>
  </inbound>
  <outbound>
  </outbound>
</policies>

ElementosElements

ElementoElement DESCRIÇÃODescription ObrigatórioRequired
log-to-eventhublog-to-eventhub Elemento raiz.Root element. O valor desse elemento é a cadeia de caracteres a ser registrada no seu hub de eventos.The value of this element is the string to log to your event hub. SimYes

AtributosAttributes

AtributoAttribute DESCRIÇÃODescription ObrigatórioRequired
logger-idlogger-id A ID do agente registrada com o serviço de Gerenciamento de API.The id of the Logger registered with your API Management service. SimYes
partition-idpartition-id Especifica o índice da partição em que as mensagens são enviadas.Specifies the index of the partition where messages are sent. Opcional.Optional. Esse atributo não poderá ser usado se partition-key for usado.This attribute may not be used if partition-key is used.
partition-keypartition-key Especifica o valor usado para a atribuição de partição quando as mensagens são enviadas.Specifies the value used for partition assignment when messages are sent. Opcional.Optional. Esse atributo não poderá ser usado se partition-id for usado.This attribute may not be used if partition-id is used.

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 da política: todos os escoposPolicy scopes: all scopes

Resposta fictíciaMock response

O mock-response, como o nome indica, é usado para simular APIs e operações.The mock-response, as the name implies, is used to mock APIs and operations. Ele anula a execução normal de pipeline e retorna uma resposta fictícia ao chamador.It aborts normal pipeline execution and returns a mocked response to the caller. A política sempre tenta retornar respostas da mais alta fidelidade.The policy always tries to return responses of highest fidelity. Ela prefere exemplos de conteúdo de resposta, sempre que disponíveis.It prefers response content examples, whenever available. Ela gera respostas de exemplo com base em esquemas, quando esquemas são fornecidos e exemplos não são fornecidos.It generates sample responses from schemas, when schemas are provided and examples are not. Se não forem encontrados exemplos nem esquemas, serão retornadas respostas sem conteúdo.If neither examples or schemas are found, responses with no content are returned.

Declaração de políticaPolicy statement

<mock-response status-code="code" content-type="media type"/>

ExemplosExamples

<!-- Returns 200 OK status code. Content is based on an example or schema, if provided for this
status code. First found content type is used. If no example or schema is found, the content is empty. -->
<mock-response/>

<!-- Returns 200 OK status code. Content is based on an example or schema, if provided for this
status code and media type. If no example or schema found, the content is empty. -->
<mock-response status-code='200' content-type='application/json'/>

ElementosElements

ElementoElement DESCRIÇÃODescription ObrigatórioRequired
mock-responsemock-response Elemento raiz.Root element. SimYes

AtributosAttributes

AtributoAttribute DESCRIÇÃODescription ObrigatórioRequired PadrãoDefault
status-codestatus-code Especifica o código de status da resposta e é usado para selecionar o exemplo ou o esquema correspondente.Specifies response status code and is used to select corresponding example or schema. NãoNo 200200
content-typecontent-type Especifica o valor de cabeçalho da resposta Content-Type e é usado para selecionar o exemplo ou o esquema correspondente.Specifies Content-Type response header value and is used to select corresponding example or schema. NãoNo NenhumNone

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 da política: todos os escoposPolicy scopes: all scopes

RepetirRetry

O retry diretiva executa suas políticas filho uma vez e, em seguida, tenta realizar sua execução até a repetição condition se torna false ou repita count esgotado.The retry policy executes its child policies once and then retries their execution until the retry condition becomes false or retry count is exhausted.

Declaração de políticaPolicy statement


<retry
    condition="boolean expression or literal"
    count="number of retry attempts"
    interval="retry interval in seconds"
    max-interval="maximum retry interval in seconds"
    delta="retry interval delta in seconds"
    first-fast-retry="boolean expression or literal">
        <!-- One or more child policies. No restrictions -->
</retry>

ExemploExample

No exemplo a seguir o encaminhamento de solicitação será repetido até dez vezes usando o algoritmo de nova tentativa exponencial.In the following example, request forwarding is retried up to ten times using an exponential retry algorithm. Uma vez que first-fast-retry é definido como false, todas novas tentativas estão sujeitas ao algoritmo de nova tentativa exponencial.Since first-fast-retry is set to false, all retry attempts are subject to the exponential retry algorithm.


<retry
    condition="@(context.Response.StatusCode == 500)"
    count="10"
    interval="10"
    max-interval="100"
    delta="10"
    first-fast-retry="false">
        <forward-request buffer-request-body="true" />
</retry>

ElementosElements

ElementoElement DESCRIÇÃODescription ObrigatórioRequired
tentar novamenteretry Elemento raiz.Root element. Pode conter quaisquer outras políticas como seus elementos filho.May contain any other policies as its child elements. SimYes

AtributosAttributes

AtributoAttribute DESCRIÇÃODescription ObrigatórioRequired PadrãoDefault
conditioncondition Uma expressão ou literal booliano especificando se as novas tentativas devem ser paradas (false) ou continuadas (true).A boolean literal or expression specifying if retries should be stopped (false) or continued (true). SimYes N/DN/A
countcount Um número positivo que especifica o número máximo de novas tentativas a serem realizadas.A positive number specifying the maximum number of retries to attempt. SimYes N/DN/A
intervalointerval Um número positivo, em segundos, que especifica o intervalo de espera entre as novas tentativas.A positive number in seconds specifying the wait interval between the retry attempts. SimYes N/DN/A
max-intervalmax-interval Um número positivo, em segundos, que especifica o intervalo de espera máximo entre as novas tentativas.A positive number in seconds specifying the maximum wait interval between the retry attempts. Ele é usado para implementar um algoritmo de nova tentativa exponencial.It is used to implement an exponential retry algorithm. NãoNo N/DN/A
deltadelta Um número positivo, em segundos, que especifica o incremento do intervalo de espera.A positive number in seconds specifying the wait interval increment. Ele é usado para implementar algoritmos de nova tentativa exponenciais e lineares.It is used to implement the linear and exponential retry algorithms. NãoNo N/DN/A
first-fast-retryfirst-fast-retry Se definido como true , a primeira tentativa de repetição é executada imediatamente.If set to true , the first retry attempt is performed immediately. NãoNo false

Observação

Quando apenas interval for especificado, novas tentativas de intervalo fixo serão realizadas.When only the interval is specified, fixed interval retries are performed. Quando apenas interval e delta forem especificados, um algoritmo de nova tentativa de intervalo linear será usado, em que o tempo de espera entre as novas tentativas é calculado de acordo com a seguinte fórmula – interval + (count - 1)*delta.When only the interval and delta are specified, a linear interval retry algorithm is used, where wait time between retries is calculated according the following formula - interval + (count - 1)*delta. Quando interval, max-interval e delta forem especificados, o algoritmo de nova tentativa de intervalo exponencial será aplicado, em que o tempo de espera entre as novas tentativas aumenta exponencialmente do valor de interval até o valor de max-interval de acordo com a seguinte fórmula – min(interval + (2^count - 1) * random(delta * 0.8, delta * 1.2), max-interval).When the interval, max-interval and delta are specified, exponential interval retry algorithm is applied, where the wait time between the retries is growing exponentially from the value of interval to the value max-interval according to the following formula - min(interval + (2^count - 1) * random(delta * 0.8, delta * 1.2), max-interval).

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 . Observe que as restrições de uso de política filho serão herdadas por essa política.Note that child policy usage restrictions will be inherited by this policy.

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

  • Escopos da política: todos os escoposPolicy scopes: all scopes

Retornar respostaReturn response

A política return-response anula a execução do pipeline e retorna uma resposta padrão ou personalizada para o chamador.The return-response policy aborts pipeline execution and returns either a default or custom response to the caller. A resposta padrão é 200 OK sem corpo.Default response is 200 OK with no body. A resposta personalizada pode ser especificada por meio de declarações de política ou variável de contexto.Custom response can be specified via a context variable or policy statements. Quando ambas são fornecidas, a resposta contida na variável de contexto é modificada pelas instruções de política antes de ser retornada para o chamador.When both are provided, the response contained within the context variable is modified by the policy statements before being returned to the caller.

Declaração de políticaPolicy statement

<return-response response-variable-name="existing context variable">
  <set-header/>
  <set-body/>
  <set-status/>
</return-response>

ExemploExample

<return-response>
   <set-status code="401" reason="Unauthorized"/>
   <set-header name="WWW-Authenticate" exists-action="override">
      <value>Bearer error="invalid_token"</value>
   </set-header>
</return-response>

ElementosElements

ElementoElement DESCRIÇÃODescription ObrigatórioRequired
return-responsereturn-response Elemento raiz.Root element. SimYes
set-headerset-header Uma declaração de política set-header.A set-header policy statement. NãoNo
set-bodyset-body Uma declaração de política set-body.A set-body policy statement. NãoNo
set-statusset-status Uma declaração de política set-status.A set-status policy statement. NãoNo

AtributosAttributes

AtributoAttribute DESCRIÇÃODescription ObrigatórioRequired
response-variable-nameresponse-variable-name O nome da variável de contexto referenciada de, por exemplo, uma política send-request upstream e que contém um objeto ResponseThe name of the context variable referenced from, for example, an upstream send-request policy and containing a Response object Opcional.Optional.

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 da política: todos os escoposPolicy scopes: all scopes

Enviar solicitação unidirecionalSend one way request

A política send-one-way-request envia a solicitação fornecida para a URL especificada sem aguardar uma resposta.The send-one-way-request policy sends the provided request to the specified URL without waiting for a response.

Declaração de políticaPolicy statement

<send-one-way-request mode="new | copy">
  <url>...</url>
  <method>...</method>
  <header name="" exists-action="override | skip | append | delete">...</header>
  <body>...</body>
  <authentication-certificate thumbprint="thumbprint" />
</send-one-way-request>

ExemploExample

Essa política de exemplo mostra um exemplo de uso da política send-one-way-request para enviar uma mensagem para uma sala de chat do Slack se o código de resposta HTTP for maior ou igual a 500.This sample policy shows an example of using the send-one-way-request policy to send a message to a Slack chat room if the HTTP response code is greater than or equal to 500. Para obter mais informações sobre esse exemplo, consulte Uso dos serviços externos do serviço de Gerenciamento de API do Azure.For more information on this sample, see Using external services from the Azure API Management service.

<choose>
    <when condition="@(context.Response.StatusCode >= 500)">
      <send-one-way-request mode="new">
        <set-url>https://hooks.slack.com/services/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</set-url>
        <set-method>POST</set-method>
        <set-body>@{
                return new JObject(
                        new JProperty("username","APIM Alert"),
                        new JProperty("icon_emoji", ":ghost:"),
                        new JProperty("text", String.Format("{0} {1}\nHost: {2}\n{3} {4}\n User: {5}",
                                                context.Request.Method,
                                                context.Request.Url.Path + context.Request.Url.QueryString,
                                                context.Request.Url.Host,
                                                context.Response.StatusCode,
                                                context.Response.StatusReason,
                                                context.User.Email
                                                ))
                        ).ToString();
            }</set-body>
      </send-one-way-request>
    </when>
</choose>

ElementosElements

ElementoElement DESCRIÇÃODescription ObrigatórioRequired
send-one-way-requestsend-one-way-request Elemento raiz.Root element. SimYes
urlurl A URL da solicitação.The URL of the request. Não se mode=copy, caso contrário, sim.No if mode=copy; otherwise yes.
methodmethod O método HTTP para a solicitação.The HTTP method for the request. Não se mode=copy, caso contrário, sim.No if mode=copy; otherwise yes.
cabeçalhoheader Cabeçalho da solicitação.Request header. Use vários elementos de cabeçalho para vários cabeçalhos de solicitação.Use multiple header elements for multiple request headers. NãoNo
bodybody O corpo da solicitação.The request body. NãoNo
authentication-certificateauthentication-certificate Certificado a ser usado para autenticação de clienteCertificate to use for client authentication NãoNo

AtributosAttributes

AtributoAttribute DESCRIÇÃODescription ObrigatórioRequired PadrãoDefault
mode="string"mode="string" Determina se esta é uma nova solicitação ou uma cópia da solicitação atual.Determines whether this is a new request or a copy of the current request. No modo de saída, mode=copy não inicializa o corpo da solicitação.In outbound mode, mode=copy does not initialize the request body. NãoNo NovoNew
namename Especifica o nome do cabeçalho a ser definido.Specifies the name of the header to be set. SimYes N/DN/A
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

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 da política: todos os escoposPolicy scopes: all scopes

Enviar solicitaçãoSend request

A política send-request envia a solicitação fornecida para a URL especificada, aguardando não mais do que o valor de tempo limite definido.The send-request policy sends the provided request to the specified URL, waiting no longer than the set timeout value.

Declaração de políticaPolicy statement

<send-request mode="new|copy" response-variable-name="" timeout="60 sec" ignore-error
="false|true">
  <set-url>...</set-url>
  <set-method>...</set-method>
  <set-header name="" exists-action="override|skip|append|delete">...</set-header>
  <set-body>...</set-body>
  <authentication-certificate thumbprint="thumbprint" />
</send-request>

ExemploExample

Este exemplo mostra uma maneira de verificar um token de referência com um servidor de autorização.This example shows one way to verify a reference token with an authorization server. Para obter mais informações sobre esse exemplo, consulte Uso dos serviços externos do serviço de Gerenciamento de API do Azure.For more information on this sample, see Using external services from the Azure API Management service.

<inbound>
  <!-- Extract Token from Authorization header parameter -->
  <set-variable name="token" value="@(context.Request.Headers.GetValueOrDefault("Authorization","scheme param").Split(' ').Last())" />

  <!-- Send request to Token Server to validate token (see RFC 7662) -->
  <send-request mode="new" response-variable-name="tokenstate" timeout="20" ignore-error="true">
    <set-url>https://microsoft-apiappec990ad4c76641c6aea22f566efc5a4e.azurewebsites.net/introspection</set-url>
    <set-method>POST</set-method>
    <set-header name="Authorization" exists-action="override">
      <value>basic dXNlcm5hbWU6cGFzc3dvcmQ=</value>
    </set-header>
    <set-header name="Content-Type" exists-action="override">
      <value>application/x-www-form-urlencoded</value>
    </set-header>
    <set-body>@($"token={(string)context.Variables["token"]}")</set-body>
  </send-request>

  <choose>
        <!-- Check active property in response -->
        <when condition="@((bool)((IResponse)context.Variables["tokenstate"]).Body.As<JObject>()["active"] == false)">
            <!-- Return 401 Unauthorized with http-problem payload -->
            <return-response>
                <set-status code="401" reason="Unauthorized" />
                <set-header name="WWW-Authenticate" exists-action="override">
                    <value>Bearer error="invalid_token"</value>
                </set-header>
            </return-response>
        </when>
    </choose>
  <base />
</inbound>

ElementosElements

ElementoElement DESCRIÇÃODescription ObrigatórioRequired
send-requestsend-request Elemento raiz.Root element. SimYes
urlurl A URL da solicitação.The URL of the request. Não se mode=copy, caso contrário, sim.No if mode=copy; otherwise yes.
methodmethod O método HTTP para a solicitação.The HTTP method for the request. Não se mode=copy, caso contrário, sim.No if mode=copy; otherwise yes.
cabeçalhoheader Cabeçalho da solicitação.Request header. Use vários elementos de cabeçalho para vários cabeçalhos de solicitação.Use multiple header elements for multiple request headers. NãoNo
bodybody O corpo da solicitação.The request body. NãoNo
authentication-certificateauthentication-certificate Certificado a ser usado para autenticação de clienteCertificate to use for client authentication NãoNo

AtributosAttributes

AtributoAttribute DESCRIÇÃODescription ObrigatórioRequired PadrãoDefault
mode="string"mode="string" Determina se esta é uma nova solicitação ou uma cópia da solicitação atual.Determines whether this is a new request or a copy of the current request. No modo de saída, mode=copy não inicializa o corpo da solicitação.In outbound mode, mode=copy does not initialize the request body. NãoNo NovoNew
response-variable-name="string"response-variable-name="string" O nome da variável de contexto que receberá um objeto de resposta.The name of context variable that will receive a response object. Se a variável não existir, ela será criada após a execução bem-sucedida da política e ficará acessível através da coleção context.Variable.If the variable doesn't exist, it will be created upon successful execution of the policy and will become accessible via context.Variable collection. SimYes N/DN/A
timeout="integer"timeout="integer" O intervalo de tempo limite em segundos antes de a chamada para a URL falhar.The timeout interval in seconds before the call to the URL fails. NãoNo 6060
ignore-errorignore-error Se for true e a solicitação resultar em um erro:If true and the request results in an error:

– Se response-variable-name foi especificado, ele conterá um valor nulo.- If response-variable-name was specified it will contain a null value.
– Se response-variable-name não foi especificada, contexto. Solicitação não será atualizada.- If response-variable-name was not specified, context.Request will not be updated.
NãoNo falsofalse
namename Especifica o nome do cabeçalho a ser definido.Specifies the name of the header to be set. SimYes N/DN/A
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

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 da política: todos os escoposPolicy scopes: all scopes

Definir proxy HTTPSet HTTP proxy

A política proxy permite reencaminhar, por meio de um proxy HTTP, as solicitações encaminhadas aos back-ends.The proxy policy allows you to route requests forwarded to backends via an HTTP proxy. Entre o gateway e o proxy, há suporte apenas para HTTP (e não para HTTPS).Only HTTP (not HTTPS) is supported between the gateway and the proxy. Somente autenticação básica e NTLM.Basic and NTLM authentication only.

Declaração de políticaPolicy statement

<proxy url="http://hostname-or-ip:port" username="username" password="password" />

ExemploExample

Observe o uso de propriedades como valores de nome de usuário e senha para evitar armazenar informações confidenciais no documento de política.Note the use of properties as values of the username and password to avoid storing sensitive information in the policy document.

<proxy url="http://192.168.1.1:8080" username={{username}} password={{password}} />

ElementosElements

ElementoElement DESCRIÇÃODescription ObrigatórioRequired
proxyproxy Elemento raizRoot element SimYes

AtributosAttributes

AtributoAttribute DESCRIÇÃODescription ObrigatórioRequired PadrãoDefault
url="string"url="string" URL do proxy no formato de http://host:port.Proxy URL in the form of http://host:port. SimYes N/DN/A
username="string"username="string" Nome de usuário a ser usado para autenticação com o proxy.Username to be used for authentication with the proxy. NãoNo N/DN/A
password="string"password="string" Senha a ser usada para autenticação com o proxy.Password to be used for authentication with the proxy. 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 entradaPolicy sections: inbound

  • Escopos da política: todos os escoposPolicy scopes: all scopes

Definir método de solicitaçãoSet request method

A política set-method permite alterar o método de solicitação HTTP de uma solicitação.The set-method policy allows you to change the HTTP request method for a request.

Declaração de políticaPolicy statement

<set-method>METHOD</set-method>

ExemploExample

Essa política de exemplo que usa a política set-method mostra um exemplo de envio de uma mensagem para uma sala de chat do Slack se o código de resposta HTTP for maior ou igual a 500.This sample policy that uses the set-method policy shows an example of sending a message to a Slack chat room if the HTTP response code is greater than or equal to 500. Para obter mais informações sobre esse exemplo, consulte Uso dos serviços externos do serviço de Gerenciamento de API do Azure.For more information on this sample, see Using external services from the Azure API Management service.

<choose>
    <when condition="@(context.Response.StatusCode >= 500)">
      <send-one-way-request mode="new">
        <set-url>https://hooks.slack.com/services/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</set-url>
        <set-method>POST</set-method>
        <set-body>@{
                return new JObject(
                        new JProperty("username","APIM Alert"),
                        new JProperty("icon_emoji", ":ghost:"),
                        new JProperty("text", String.Format("{0} {1}\nHost: {2}\n{3} {4}\n User: {5}",
                                                context.Request.Method,
                                                context.Request.Url.Path + context.Request.Url.QueryString,
                                                context.Request.Url.Host,
                                                context.Response.StatusCode,
                                                context.Response.StatusReason,
                                                context.User.Email
                                                ))
                        ).ToString();
            }</set-body>
      </send-one-way-request>
    </when>
</choose>

ElementosElements

ElementoElement DESCRIÇÃODescription ObrigatórioRequired
set-methodset-method Elemento raiz.Root element. O valor do elemento especifica o método HTTP.The value of the element specifies the HTTP method. 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: entrada, em caso de erroPolicy sections: inbound, on-error

  • Escopos da política: todos os escoposPolicy scopes: all scopes

Definir código de statusSet status code

A política set-status define o código de status HTTP para o valor especificado.The set-status policy sets the HTTP status code to the specified value.

Declaração de políticaPolicy statement

<set-status code="" reason=""/>

ExemploExample

Este exemplo mostra como retornar uma resposta 401, se o token de autorização for inválido.This example shows how to return a 401 response if the authorization token is invalid. Para obter mais informações, consulte Uso dos serviços externos do serviço de Gerenciamento de API do AzureFor more information, see Using external services from the Azure API Management service

<choose>
  <when condition="@((bool)((IResponse)context.Variables["tokenstate"]).Body.As<JObject>()["active"] == false)">
    <return-response response-variable-name="existing response variable">
      <set-status code="401" reason="Unauthorized" />
      <set-header name="WWW-Authenticate" exists-action="override">
        <value>Bearer error="invalid_token"</value>
      </set-header>
    </return-response>
  </when>
</choose>

ElementosElements

ElementoElement DESCRIÇÃODescription ObrigatórioRequired
set-statusset-status Elemento raiz.Root element. SimYes

AtributosAttributes

AtributoAttribute DESCRIÇÃODescription ObrigatórioRequired PadrãoDefault
code="integer"code="integer" O código de status HTTP a ser retornado.The HTTP status code to return. SimYes N/DN/A
reason="string"reason="string" Uma descrição do motivo para retornar o código de status.A description of the reason for returning the status code. 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: saída, back-end, em caso de erroPolicy sections: outbound, backend, on-error
  • Escopos da política: todos os escoposPolicy scopes: all scopes

Definir variávelSet variable

A política set-variable declara uma variável de contexto e atribui a ela um valor especificado por meio de uma expressão ou literal de cadeia de caracteres.The set-variable policy declares a context variable and assigns it a value specified via an expression or a string literal. Se a expressão contiver um literal ele será convertido em uma cadeia de caracteres e o tipo do valor será System.String.if the expression contains a literal it will be converted to a string and the type of the value will be System.String.

Declaração de políticaPolicy statement

<set-variable name="variable name" value="Expression | String literal" />

ExemploExample

O exemplo a seguir demonstra uma política de definir a variável na seção de entrada.The following example demonstrates a set variable policy in the inbound section. Essa política de definir variável cria uma variável de contexto booliana isMobile que será definida como true se o cabeçalho da solicitação User-Agent contiver o texto iPad ou iPhone.This set variable policy creates an isMobile Boolean context variable that is set to true if the User-Agent request header contains the text iPad or iPhone.

<set-variable name="IsMobile" value="@(context.Request.Headers["User-Agent"].Contains("iPad") || context.Request.Headers["User-Agent"].Contains("iPhone"))" />

ElementosElements

ElementoElement DESCRIÇÃODescription ObrigatórioRequired
set-variableset-variable Elemento raiz.Root element. SimYes

AtributosAttributes

AtributoAttribute DESCRIÇÃODescription ObrigatórioRequired
namename O nome da variável.The name of the variable. SimYes
valorvalue O valor da variável.The value of the variable. Isso pode ser uma expressão ou um valor literal.This can be an expression or a literal value. 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 da política: entrada, saída, back-end, em caso de erroPolicy sections: inbound, outbound, backend, on-error
  • Escopos da política: todos os escoposPolicy scopes: all scopes

Tipos permitidosAllowed types

As expressões usadas na política set-variable devem retornar um dos seguintes tipos básicos.Expressions used in the set-variable policy must return one of the following basic types.

  • System.BooleanSystem.Boolean
  • System.SByteSystem.SByte
  • System.ByteSystem.Byte
  • System.UInt16System.UInt16
  • System.UInt32System.UInt32
  • System.UInt64System.UInt64
  • System.Int16System.Int16
  • System.Int32System.Int32
  • System.Int64System.Int64
  • System.DecimalSystem.Decimal
  • System.SingleSystem.Single
  • System.DoubleSystem.Double
  • System.GuidSystem.Guid
  • System.StringSystem.String
  • System.CharSystem.Char
  • System.DateTimeSystem.DateTime
  • System.TimeSpanSystem.TimeSpan
  • System.Byte?System.Byte?
  • System.UInt16?System.UInt16?
  • System.UInt32?System.UInt32?
  • System.UInt64?System.UInt64?
  • System.Int16?System.Int16?
  • System.Int32?System.Int32?
  • System.Int64?System.Int64?
  • System.Decimal?System.Decimal?
  • System.Single?System.Single?
  • System.Double?System.Double?
  • System.Guid?System.Guid?
  • System.String?System.String?
  • System.Char?System.Char?
  • System.DateTime?System.DateTime?

RastreamentoTrace

O trace diretiva adiciona uma cadeia de caracteres para o Inspetor de API saída.The trace policy adds a string into the API Inspector output. A política será executada somente quando o rastreamento for disparado, ou seja, o cabeçalho de solicitação Ocp-Apim-Trace está presente e definido como true e o cabeçalho de solicitação Ocp-Apim-Subscription-Key está presente e contém uma chave válida associada à conta do administrador.The policy will execute only when tracing is triggered, i.e. Ocp-Apim-Trace request header is present and set to true and Ocp-Apim-Subscription-Key request header is present and holds a valid key associated with the admin account.

Declaração de políticaPolicy statement


<trace source="arbitrary string literal">
    <!-- string expression or literal -->
</trace>

ElementosElements

ElementoElement DESCRIÇÃODescription ObrigatórioRequired
tracetrace Elemento raiz.Root element. SimYes

AtributosAttributes

AtributoAttribute DESCRIÇÃODescription ObrigatórioRequired PadrãoDefault
fontesource Literal de cadeia de caracteres significativo para o visualizador de rastreamento e especificando a fonte da mensagem.String literal meaningful to the trace viewer and specifying the source of the message. 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 da política: todos os escoposPolicy scopes: all scopes

AguardarWait

A política wait executa suas políticas filho imediatas em paralelo e aguarda que todas ou uma das políticas filho imediatas sejam concluídas antes de ser concluída.The wait policy executes its immediate child policies in parallel, and waits for either all or one of its immediate child policies to complete before it completes. A política de espera pode ter como suas políticas de filho imediatas as políticas de Enviar solicitação, Obter valor do cache e Controlar fluxo.The wait policy can have as its immediate child policies Send request, Get value from cache, and Control flow policies.

Declaração de políticaPolicy statement

<wait for="all|any">
  <!--Wait policy can contain send-request, cache-lookup-value,
        and choose policies as child elements -->
</wait>

ExemploExample

No exemplo a seguir há duas políticas choose como políticas filho imediatas da política wait.In the following example there are two choose policies as immediate child policies of the wait policy. Cada uma dessas políticas choose executadas em paralelo.Each of these choose policies executes in parallel. Cada política choose tenta recuperar um valor em cache.Each choose policy attempts to retrieve a cached value. Se houver uma perda no cache, um serviço de back-end será chamado para fornecer o valor.If there is a cache miss, a backend service is called to provide the value. Neste exemplo a política wait não é concluída até todas as políticas filho imediatas serem concluídas, porque o atributo for está definido como all.In this example the wait policy does not complete until all of its immediate child policies complete, because the for attribute is set to all. Neste exemplo as variáveis de contexto (execute-branch-one, value-one, execute-branch-two e value-two) são declaradas fora do escopo desta política de exemplo.In this example the context variables (execute-branch-one, value-one, execute-branch-two, and value-two) are declared outside of the scope of this example policy.

<wait for="all">
  <choose>
    <when condition="@((bool)context.Variables["execute-branch-one="])">
      <cache-lookup-value key="key-one" variable-name="value-one" />
      <choose>
        <when condition="@(!context.Variables.ContainsKey("value-one="))">
          <send-request mode="new" response-variable-name="value-one">
            <set-url>https://backend-one</set-url>
            <set-method>GET</set-method>
          </send-request>
        </when>
      </choose>
    </when>
  </choose>
  <choose>
    <when condition="@((bool)context.Variables["execute-branch-two="])">
      <cache-lookup-value key="key-two" variable-name="value-two" />
      <choose>
        <when condition="@(!context.Variables.ContainsKey("value-two="))">
          <send-request mode="new" response-variable-name="value-two">
            <set-url>https://backend-two</set-url>
            <set-method>GET</set-method>
          </send-request>
        </when>
      </choose>
    </when>
  </choose>
</wait>

ElementosElements

ElementoElement DESCRIÇÃODescription ObrigatórioRequired
waitwait Elemento raiz.Root element. Pode conter como elementos filho somente as políticas send-request, cache-lookup-value e choose.May contain as child elements only send-request, cache-lookup-value, and choose policies. SimYes

AtributosAttributes

AtributoAttribute DESCRIÇÃODescription ObrigatórioRequired PadrãoDefault
forfor Determina se a política wait aguarda todas as políticas filho imediatas a serem concluídas ou apenas uma.Determines whether the wait policy waits for all immediate child policies to be completed or just one. Valores permitidos são:Allowed values are:

- all – aguarda todas as políticas filho imediatas serem concluídas- all - wait for all immediate child policies to complete
– any – aguarda qualquer política filho imediata ser concluída.- any - wait for any immediate child policy to complete. Concluída a primeira política filho imediata, a política wait é concluída e a execução de qualquer outra política filho imediata é encerrada.Once the first immediate child policy has completed, the wait policy completes and execution of any other immediate child policies is terminated.
NãoNo tudoall

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 da política: todos os escoposPolicy scopes: all scopes

Próximas etapasNext steps

Para obter mais informações sobre como trabalhar com políticas, consulte:For more information working with policies, see: