Políticas avançadas de Gerenciamento de API

Este artigo fornece uma referência para políticas avançadas de Gerenciamento de API, como aquelas baseadas em expressões de política.

Para saber mais sobre políticas:

Políticas avançadas

Fluxo de controle

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.

Observação

Defina os elementos da política e os elementos filho na ordem fornecida na declaração da política. Saiba mais sobre como definir e editar as políticas de Gerenciamento de API.

Declaração de política

<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/>. O elemento <otherwise/> é opcional. As condições nos elementos <when/> são avaliadas na ordem de aparecimento na política. As declarações de política incluídas dentro do primeiro elemento <when/> com atributo de condição igual a true serão aplicadas. 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.

Exemplos

Exemplo

O exemplo a seguir demonstra uma política variável definida e duas políticas de fluxo de controle.

A política de definir variável está na seção de entrada e cria uma variável de isMobile booliana isMobile que será definida como true se o cabeçalho da solicitação User-Agent contiver o texto iPad ou 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 .

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 é definida como true.

<policies>
    <inbound>
        <set-variable name="isMobile" value="@(context.Request.Headers.GetValueOrDefault("User-Agent","").Contains("iPad") || context.Request.Headers.GetValueOrDefault("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>

Exemplo

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. A resposta de back-end de exemplo inclui propriedades de nível de raiz semelhantes à API de chamada OpenWeather One.

<!-- Copy this snippet into the outbound section to remove a number of data elements from the response received from the backend service based on the name of the product -->
<choose>
  <when condition="@(context.Response.StatusCode == 200 && context.Product.Name.Equals("Starter"))">
    <set-body>@{
        var response = context.Response.Body.As<JObject>();
        foreach (var key in new [] {"current", "minutely", "hourly", "daily", "alerts"}) {
          response.Property (key).Remove ();
        }
        return response.ToString();
      }
    </set-body>
  </when>
</choose>

Elementos

Elemento Descrição Obrigatório
choose Elemento raiz. Yes
when A condição a ser usada para as partes if ou ifelse da política choose. Se política choose tiver várias seções when, elas serão avaliadas sequencialmente. Uma vez que o condition de um elemento when é avaliado como true, nenhuma outra condição when é avaliada. Yes
otherwise Contém o snippet de código da política a ser usado se nenhuma das condições when for avaliada como true. Não

Atributos

Atributo Descrição Obrigatório
condição ="Expressão booliana | Constante booliana" A constante ou expressão booliana a ser avaliada quando a declaração de política contendo when é avaliada. Yes

Uso

Essa política pode ser usada nas seções e nos escopos da política a seguir.

  • Seções da política: entrada, saída, back-end, em caso de erro

  • Escopos da política: todos os escopos

Encaminhar solicitação

A política forward-request encaminha a solicitação de entrada para o serviço de back-end especificado na variável de forward-request de solicitação. A URL do serviço de back-end é especificada nas configurações de API e pode ser alterada usando a política definir o serviço de back-end.

Importante

  • Essa política é necessária para encaminhar solicitações a um back-end de API. Por padrão, o Gerenciamento de API configura essa política no escopo global.
  • A remoção dessa política faz com que a solicitação não seja encaminhada ao serviço de back-end. As políticas na seção de saída são avaliadas imediatamente mediante a conclusão bem-sucedida das políticas na seção de entrada.

Observação

Defina os elementos da política e os elementos filho na ordem fornecida na declaração da política. Saiba mais sobre como definir e editar as políticas de Gerenciamento de API.

Declaração de política

<forward-request timeout="time in seconds" follow-redirects="false | true" buffer-request-body="false | true" buffer-response="true | false" fail-on-error-status-code="false | true"/>

Exemplos

Exemplo

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.

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

Exemplo

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.

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

Exemplo

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. Se o serviço de back-end responder com um código de status de erro de 400 para 599, inclusive, a seção On-Error será acionada.

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

Exemplo

Essa política de nível de operação não encaminha solicitações para o serviço de back-end.

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

Elementos

Elemento Descrição Obrigatório
forward-request Elemento raiz. Yes

Atributos

Atributo Descrição Obrigatório Padrão
timeout="integer" A quantidade de tempo em segundos a aguardar que os cabeçalhos de resposta HTTP sejam retornados pelo serviço de back-end antes que um erro de tempo esgotado seja gerado. O valor mínimo é 0 segundos. Valores maiores que 240 segundos podem não ser respeitados, pois a infraestrutura de rede subjacente pode descartar conexões ociosas após esse tempo. Não 300
follow-redirects="false | true" Especifica se os redirecionamentos do serviço de back-end são seguidos pelo gateway ou retornados ao chamador. Não false
buffer-request-body="false | true" Quando definido como "true", a solicitação é armazenada em buffer e será reutilizada na nova tentativa. Não false
buffer-response="false | true" Afeta o processamento de respostas em partes. Quando isso é definido como "false", cada parte recebida do back-end é retornada imediatamente para o chamador. Quando definias como "true" as partes são armazenadas em buffer (8 KB, a menos que o final do fluxo seja detectado) e, em seguida, retornadas ao autor da chamada.

Defina essa opção como "false" com back-ends como aqueles que implementam SSE (eventos enviados pelo servidor) que exigem que o conteúdo seja retornado ou transmitido imediatamente para o chamador.
No true
fail-on-error-status-code="false | true" Quando definido como true aciona a seção on-error para códigos de resposta no intervalo de 400 a 599, inclusive. Não false

Uso

Essa política pode ser usada nas seções e nos escopos da política a seguir.

  • Seções de política: back-end
  • Escopos da política: todos os escopos

Incluir fragmento

A política include-fragment insere o conteúdo de um fragmento de política criado anteriormente na definição de política. Um fragmento de política é um snippet de política XML centralmente gerenciado e reutilizável que pode ser incluído em definições de política em sua instância do API Management.

A política insere o fragmento de política no estado em que se encontra no local selecionado na definição de política.

Declaração de política

<include-fragment fragment-id="fragment" />

Exemplo

No exemplo a seguir, o fragmento de política chamado myFragment é adicionado à seção de entrada de uma definição de política.

<inbound>
    <include-fragment fragment-id="myFragment" />
    <base />
</inbound>
[...]

Elementos

Elemento Descrição Necessária
include-fragment Elemento raiz. Yes

Atributos

Atributo Descrição Obrigatório Padrão
fragment-id Uma cadeia de caracteres. Expressão permitida. Especifica o identificador (nome) de um fragmento de política criado na instância do API Management. Sim N/D

Uso

Essa política pode ser usada nas seções e nos escopos da política a seguir.

  • Seções da política: entrada, saída, back-end, em caso de erro

  • Escopos da política: todos os escopos

Simultaneidade de limite

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. Ao exceder esse número, novos pedidos falharão imediatamente com o código de status 429 Número excessivo de solicitações.

Observação

Defina os elementos da política e os elementos filho na ordem fornecida na declaração da política. Saiba mais sobre como definir e editar as políticas de Gerenciamento de API.

Declaração de política

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

Exemplo

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.

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

Elementos

Elemento Descrição Obrigatório
limit-concurrency Elemento raiz. Yes

Atributos

Atributo Descrição Obrigatório Padrão
chave Uma cadeia de caracteres. Expressão permitida. Especifica o escopo de simultaneidade. Pode ser compartilhado por várias políticas. Sim N/D
max-count Um inteiro. Especifica um número máximo de solicitações que são permitidas para inserir a política. Sim N/D

Uso

Essa política pode ser usada nas seções e nos escopos da política a seguir.

  • Seções da política: entrada, saída, back-end, em caso de erro

  • Escopos da política: todos os escopos

Registrar no hub de eventos

A política log-to-eventhub envia mensagens no formato especificado para um hub de eventos definido por uma entidade Logger. 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.
A política não é afetada pela amostragem do Application Insights. Todas as invocações da política serão registradas.

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.

Observação

Defina os elementos da política e os elementos filho na ordem fornecida na declaração da política. Saiba mais sobre como definir e editar as políticas de Gerenciamento de API.

Declaração de política

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

Exemplo

Qualquer cadeia de caracteres pode ser usada como o valor a ser registrado em Hubs de Eventos. Neste exemplo, a data e hora, nome do serviço de implantação, a ID de solicitação, 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.

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

Elementos

Elemento Descrição Obrigatório
log-to-eventhub Elemento raiz. O valor desse elemento é a cadeia de caracteres a ser registrada no seu hub de eventos. Yes

Atributos

Atributo Descrição Obrigatório
logger-id A ID do agente registrada com o serviço de Gerenciamento de API. Yes
partition-id Especifica o índice da partição em que as mensagens são enviadas. Opcional. Esse atributo não poderá ser usado se partition-key for usado.
partition-key Especifica o valor usado para a atribuição de partição quando as mensagens são enviadas. Opcional. Esse atributo não poderá ser usado se partition-id for usado.

Uso

Essa política pode ser usada nas seções e nos escopos da política a seguir.

  • Seções da política: entrada, saída, back-end, em caso de erro

  • Escopos da política: todos os escopos

Emitir métricas

A política emit-metric envia métricas personalizadas no formato especificado para o Application insights.

Observação

Observação

Defina os elementos da política e os elementos filho na ordem fornecida na declaração da política. Saiba mais sobre como definir e editar as políticas de Gerenciamento de API.

Declaração de política

<emit-metric name="name of custom metric" value="value of custom metric" namespace="metric namespace"> 
    <dimension name="dimension name" value="dimension value" /> 
</emit-metric> 

Exemplo

O exemplo a seguir envia uma métrica personalizada para contar o número de solicitações de API junto com a ID de usuário, o IP do cliente e a ID da API como dimensões personalizadas.

<policies>
  <inbound>
    <emit-metric name="Request" value="1" namespace="my-metrics"> 
        <dimension name="User ID" /> 
        <dimension name="Client IP" value="@(context.Request.IpAddress)" /> 
        <dimension name="API ID" /> 
    </emit-metric> 
  </inbound>
  <outbound>
  </outbound>
</policies>

Elementos

Elemento Descrição Obrigatório
emit-metric Elemento raiz. O valor desse elemento é a cadeia de caracteres para emitir sua métrica personalizada. Sim
dimensão Subelemento. Adicione um ou mais desses elementos para cada dimensão incluída na métrica personalizada. Sim

Atributos

emit-metric

Atributo Descrição Obrigatório Type Valor padrão
name Nome da métrica personalizada. Sim cadeia de caracteres, expressão N/D
namespace Namespace da métrica personalizada. Não cadeia de caracteres, expressão Gerenciamento de API
value Valor da métrica personalizada. Não int, expressão 1

dimensão

Atributo Descrição Obrigatório Type Valor padrão
name Nome da dimensão. Sim cadeia de caracteres, expressão N/D
value Valor da dimensão. Só poderá ser omitido se name corresponder a uma das dimensões padrão. Em caso afirmativo, o valor é fornecido de acordo com o nome da dimensão. Não cadeia de caracteres, expressão N/D

Nomes de dimensão padrão que podem ser usados sem valor:

  • ID da API
  • ID da Operação
  • Produto ID
  • ID do Usuário
  • ID da assinatura
  • ID da Localização
  • ID de Gateway

Uso

Essa política pode ser usada nas seções e nos escopos da política a seguir.

  • Seções da política: entrada, saída, back-end, em caso de erro

  • Escopos da política: todos os escopos

Resposta fictícia

O mock-response, como o nome indica, é usado para simular APIs e operações. Ele anula a execução normal de pipeline e retorna uma resposta fictícia ao chamador. A política sempre tenta retornar respostas da mais alta fidelidade. Ela prefere exemplos de conteúdo de resposta, sempre que disponíveis. Ela gera respostas de exemplo com base em esquemas, quando esquemas são fornecidos e exemplos não são fornecidos. Se não forem encontrados exemplos nem esquemas, serão retornadas respostas sem conteúdo.

Observação

Defina os elementos da política e os elementos filho na ordem fornecida na declaração da política. Saiba mais sobre como definir e editar as políticas de Gerenciamento de API.

Declaração de política

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

Exemplos

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

Elementos

Elemento Descrição Obrigatório
mock-response Elemento raiz. Yes

Atributos

Atributo Descrição Obrigatório Padrão
status-code Especifica o código de status da resposta e é usado para selecionar o exemplo ou o esquema correspondente. Não 200
content-type Especifica o valor de cabeçalho da resposta Content-Type e é usado para selecionar o exemplo ou o esquema correspondente. Não Nenhum

Uso

Essa política pode ser usada nas seções e nos escopos da política a seguir.

  • Seções de política: de entrada, de saída, em caso de erro

  • Escopos da política: todos os escopos

Repetir

A política retry executa suas políticas filho uma vez e tenta realizar sua execução novamente até condition da nova tentativa se tornar false ou count da nova tentativa ser esgotada.

Observação

Defina os elementos da política e os elementos filho na ordem fornecida na declaração da política. Saiba mais sobre como definir e editar as políticas de Gerenciamento de API.

Declaração de política


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

Exemplo

No exemplo a seguir o encaminhamento de solicitação será repetido até dez vezes usando o algoritmo de nova tentativa exponencial. Como first-fast-retry está definido como false, todas as tentativas de repetição estão sujeitas a aumentar exponencialmente os tempos de espera da repetição (neste exemplo, aproximadamente 10 segundos, 20 segundos, 40 segundos...) até uma espera máxima de max-interval.


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

Exemplo

No exemplo a seguir, o envio de uma solicitação para uma URL diferente do back-end definido será repetido até três vezes se a conexão for descartada/cronometrada ou a solicitação resultar em um erro do lado do servidor. Como first-fast-retry é definido como true, a primeira repetição é executada imediatamente após a falha da solicitação inicial. Observe que send-request deve definir ignore-error como true para response-variable-name ser nulo no caso de um erro.


<retry
    condition="@(context.Variables["response"] == null || ((IResponse)context.Variables["response"]).StatusCode >= 500)"
    count="3"
    interval="1"
    first-fast-retry="true">
        <send-request 
            mode="new" 
            response-variable-name="response" 
            timeout="3" 
            ignore-error="true">
		        <set-url>https://api.contoso.com/products/5</set-url>
		        <set-method>GET</set-method>
		</send-request>
</retry>

Elementos

Elemento Descrição Obrigatório
tentar novamente Elemento raiz. Pode conter quaisquer outras políticas como seus elementos filho. Yes

Atributos

Atributo Descrição Obrigatório Padrão
condition Uma expressão ou literal booliano especificando se as novas tentativas devem ser paradas () ou continuadas (true). Sim N/D
count Um número positivo que especifica o número máximo de novas tentativas a serem realizadas. Sim N/D
intervalo Um número positivo, em segundos, que especifica o intervalo de espera entre as novas tentativas. Sim N/D
max-interval Um número positivo, em segundos, que especifica o intervalo de espera máximo entre as novas tentativas. Ele é usado para implementar um algoritmo de nova tentativa exponencial. Não N/D
delta Um número positivo, em segundos, que especifica o incremento do intervalo de espera. Ele é usado para implementar algoritmos de nova tentativa exponenciais e lineares. Não N/D
first-fast-retry Se definido como true, a primeira nova tentativa será realizada imediatamente. No false

Tempos de espera de repetição

  • Quando apenas interval for especificado, novas tentativas de intervalo interval serão realizadas.

  • Quando apenas interval e delta são especificados, um algoritmo de repetição com intervalo linear é usado. O tempo de espera entre as repetições aumenta de acordo com a seguinte fórmula: interval + (count - 1)*delta.

  • Quando interval, max-interval e delta são especificados, um algoritmo repetição com intervalo exponencial é aplicado. O tempo de espera entre as repetições aumenta exponencialmente de acordo com a seguinte fórmula: interval + (2^count - 1) * random(delta * 0.8, delta * 1.2), até um intervalo máximo definido por max-interval.

    Por exemplo, quando interval e delta são definidos como 10 segundos e max-interval é de 100 segundos, o tempo de espera aproximado entre as repetições aumenta da seguinte maneira: 10 segundos, 20 segundos, 40 segundos, 80 segundos, com 100 segundos de tempo de espera usado para repetições restantes.

Uso

Essa política pode ser usada nas seções e nos escopos da política a seguir. As restrições de uso de política filho serão herdadas por essa política.

  • Seções da política: entrada, saída, back-end, em caso de erro

  • Escopos da política: todos os escopos

Retornar resposta

A política return-response anula a execução do pipeline e retorna uma resposta padrão ou personalizada para o chamador. A resposta padrão é 200 OK sem corpo. A resposta personalizada pode ser especificada por meio de declarações de política ou variável de contexto. 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.

Observação

Defina os elementos da política e os elementos filho na ordem fornecida na declaração da política. Saiba mais sobre como definir e editar as políticas de Gerenciamento de API.

Declaração de política

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

Exemplo

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

Elementos

Elemento Descrição Obrigatório
return-response Elemento raiz. Yes
set-header Uma declaração de política set-header. Não
set-body Uma declaração de política set-body. Não
set-status Uma declaração de política set-status. Não

Atributos

Atributo Descrição Obrigatório
response-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 Opcional.

Uso

Essa política pode ser usada nas seções e nos escopos da política a seguir.

  • Seções da política: entrada, saída, back-end, em caso de erro

  • Escopos da política: todos os escopos

Enviar solicitação unidirecional

A política send-one-way-request envia a solicitação fornecida para a URL especificada sem aguardar uma resposta.

Observação

Defina os elementos da política e os elementos filho na ordem fornecida na declaração da política. Saiba mais sobre como definir e editar as políticas de Gerenciamento de API.

Declaração de política

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

Exemplo

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. Para obter mais informações sobre esse exemplo, consulte Uso dos serviços externos do serviço de Gerenciamento de API do Azure.

<choose>
    <when condition="@(context.Response.StatusCode >= 500)">
      <send-one-way-request mode="new">
        <set-url>https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX</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>

Elementos

Elemento Descrição Obrigatório
send-one-way-request Elemento raiz. Sim
set-url A URL da solicitação. Não se mode=copy, caso contrário, sim.
method O método HTTP para a solicitação. Não se mode=copy, caso contrário, sim.
header Cabeçalho da solicitação. Use vários elementos de cabeçalho para vários cabeçalhos de solicitação. Não
body O corpo da solicitação. Não
authentication-certificate Certificado a ser usado para autenticação de cliente Não

Atributos

Atributo Descrição Obrigatório Padrão
mode="string" Determina se esta é uma nova solicitação ou uma cópia da solicitação atual. No modo de saída, mode=copy não inicializa o corpo da solicitação. Não Novo
name Especifica o nome do cabeçalho a ser definido. Sim N/D
exists-action Especifica a ação a ser adotada quando o cabeçalho já foi especificado. Este atributo deve ter um dos valores a seguir.

- override - substitui o valor do cabeçalho existente.
- skip - não substitui o valor do cabeçalho existente.
- append - acrescenta o valor ao valor do cabeçalho existente.
- delete - remove o cabeçalho da solicitação.

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.
Não override

Uso

Essa política pode ser usada nas seções e nos escopos da política a seguir.

  • Seções da política: entrada, saída, back-end, em caso de erro

  • Escopos da política: todos os escopos

Enviar solicitação

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.

Observação

Defina os elementos da política e os elementos filho na ordem fornecida na declaração da política. Saiba mais sobre como definir e editar as políticas de Gerenciamento de API.

Declaração de política

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

Exemplo

Este exemplo mostra uma maneira de verificar um token de referência com um servidor de autorização. Para obter mais informações sobre esse exemplo, consulte Uso dos serviços externos do serviço de Gerenciamento de API do Azure.

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

Elementos

Elemento Descrição Obrigatório
send-request Elemento raiz. Sim
url A URL da solicitação. Não se mode=copy, caso contrário, sim.
method O método HTTP para a solicitação. Não se mode=copy, caso contrário, sim.
header Cabeçalho da solicitação. Use vários elementos de cabeçalho para vários cabeçalhos de solicitação. Não
body O corpo da solicitação. Não
authentication-certificate Certificado a ser usado para autenticação de cliente Não

Atributos

Atributo Descrição Obrigatório Padrão
mode="string" Determina se esta é uma nova solicitação ou uma cópia da solicitação atual. No modo de saída, mode=copy não inicializa o corpo da solicitação. Não Novo
response-variable-name="string" O nome da variável de contexto que receberá um objeto de resposta. 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. Sim N/D
timeout="integer" O intervalo de tempo limite em segundos antes de a chamada para a URL falhar. Não 60
ignore-error Se isso for verdadeiro e a solicitação resultar em um erro, o erro será ignorado e a variável de resposta conterá um valor nulo. No false
name Especifica o nome do cabeçalho a ser definido. Sim N/D
exists-action Especifica a ação a ser adotada quando o cabeçalho já foi especificado. Este atributo deve ter um dos valores a seguir.

- override - substitui o valor do cabeçalho existente.
- skip - não substitui o valor do cabeçalho existente.
- append - acrescenta o valor ao valor do cabeçalho existente.
- delete - remove o cabeçalho da solicitação.

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.
Não override

Uso

Essa política pode ser usada nas seções e nos escopos da política a seguir.

  • Seções da política: entrada, saída, back-end, em caso de erro

  • Escopos da política: todos os escopos

Definir proxy HTTP

A política proxy permite reencaminhar, por meio de um proxy HTTP, as solicitações encaminhadas aos back-ends. Entre o gateway e o proxy, há suporte apenas para HTTP (e não para HTTPS). Somente autenticação básica e NTLM.

Observação

Defina os elementos da política e os elementos filho na ordem fornecida na declaração da política. Saiba mais sobre como definir e editar as políticas de Gerenciamento de API.

Declaração de política

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

Exemplo

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.

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

Elementos

Elemento Descrição Obrigatório
proxy Elemento raiz Yes

Atributos

Atributo Descrição Obrigatório Padrão
url="string" URL do proxy no formato http://host:port. Sim N/D
username="string" Nome de usuário a ser usado para autenticação com o proxy. Não N/D
password="string" Senha a ser usada para autenticação com o proxy. Não N/D

Uso

Essa política pode ser usada nas seções e nos escopos da política a seguir.

  • Seções de política: de entrada

  • Escopos da política: todos os escopos

Definir método de solicitação

A política set-method permite alterar o método de solicitação HTTP de uma solicitação.

Observação

Defina os elementos da política e os elementos filho na ordem fornecida na declaração da política. Saiba mais sobre como definir e editar as políticas de Gerenciamento de API.

Declaração de política

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

Exemplo

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. Para obter mais informações sobre esse exemplo, consulte Uso dos serviços externos do serviço de Gerenciamento de API do Azure.

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

Elementos

Elemento Descrição Obrigatório
set-method Elemento raiz. O valor do elemento especifica o método HTTP. Yes

Uso

Essa política pode ser usada nas seções e nos escopos da política a seguir.

  • Seções de política: entrada, em caso de erro

  • Escopos da política: todos os escopos

Definir código de status

A política set-status define o código de status HTTP para o valor especificado.

Observação

Defina os elementos da política e os elementos filho na ordem fornecida na declaração da política. Saiba mais sobre como definir e editar as políticas de Gerenciamento de API.

Declaração de política

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

Exemplo

Este exemplo mostra como retornar uma resposta 401, se o token de autorização for inválido. Para obter mais informações, consulte Uso dos serviços externos do serviço de Gerenciamento de API do Azure

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

Elementos

Elemento Descrição Obrigatório
set-status Elemento raiz. Yes

Atributos

Atributo Descrição Obrigatório Padrão
code="integer" O código de status HTTP a ser retornado. Sim N/D
reason="string" Uma descrição do motivo para retornar o código de status. Sim N/D

Uso

Essa política pode ser usada nas seções e nos escopos da política a seguir.

  • Seções da política: entrada, saída, back-end, em caso de erro
  • Escopos da política: todos os escopos

Definir variável

A política set-variable declara uma variável de set-variable e atribui a ela um valor especificado por meio de uma expressão ou literal de cadeia de caracteres. Se a expressão contiver um literal ele será convertido em uma cadeia de caracteres e o tipo do valor será System.String.

Observação

Defina os elementos da política e os elementos filho na ordem fornecida na declaração da política. Saiba mais sobre como definir e editar as políticas de Gerenciamento de API.

Declaração de política

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

Exemplo

O exemplo a seguir demonstra uma política de definir a variável na seção de entrada. Essa política de definir variável cria uma variável de isMobile booliana isMobile que será definida como true se o cabeçalho da solicitação User-Agent contiver o texto iPad ou iPhone.

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

Elementos

Elemento Descrição Obrigatório
set-variable Elemento raiz. Yes

Atributos

Atributo Descrição Obrigatório
name O nome da variável. Yes
valor O valor da variável. Isso pode ser uma expressão ou um valor literal. Yes

Uso

Essa política pode ser usada nas seções e nos escopos da política a seguir.

  • Seções da política: entrada, saída, back-end, em caso de erro
  • Escopos da política: todos os escopos

Tipos permitidos

As expressões usadas na política set-variable devem retornar um dos seguintes tipos básicos.

  • System.Boolean
  • System.SByte
  • System.Byte
  • System.UInt16
  • System.UInt32
  • System.UInt64
  • System.Int16
  • System.Int32
  • System.Int64
  • System.Decimal
  • System.Single
  • System.Double
  • System.Guid
  • System.String
  • System.Char
  • System.DateTime
  • System.TimeSpan
  • System.Byte?
  • System.UInt16?
  • System.UInt32?
  • System.UInt64?
  • System.Int16?
  • System.Int32?
  • System.Int64?
  • System.Decimal?
  • System.Single?
  • System.Double?
  • System.Guid?
  • System.String?
  • System.Char?
  • System.DateTime?

Trace

A política trace adiciona um rastreamento personalizado na saída do Inspetor de API, telemetrias do Application insights e logs de recursos.

  • A política adiciona um rastreamento personalizado à saída do Inspetor de API quando o rastreamento é disparado, ou seja, o cabeçalho da solicitação está presente e definido como true e o cabeçalho da solicitação Ocp-Apim-Subscription-Key está presente e contém uma chave válida que permite o rastreamento.
  • A política cria uma telemetria de rastreamento no Application insights, quando a integração do Application Insights está habilitada e o especificado na política é igual ou maior que o especificado na configuração de diagnóstico.
  • A política adiciona uma propriedade na entrada de log quando os logs de recursos estão habilitados e o nível de severidade especificado na política é ou superior ao nível de detalhes especificado na configuração de diagnóstico.
  • A política não é afetada pela amostragem do Application Insights. Todas as invocações da política serão registradas.

Observação

Defina os elementos da política e os elementos filho na ordem fornecida na declaração da política. Saiba mais sobre como definir e editar as políticas de Gerenciamento de API.

Declaração de política


<trace source="arbitrary string literal" severity="verbose|information|error">
    <message>String literal or expressions</message>
    <metadata name="string literal or expressions" value="string literal or expressions"/>
</trace>

Exemplo

<trace source="PetStore API" severity="verbose">
    <message>@((string)context.Variables["clientConnectionID"])</message>
    <metadata name="Operation Name" value="New-Order"/>
</trace>

Elementos

Elemento Descrição Obrigatório
rastreamento Elemento raiz. Yes
message Uma cadeia de caracteres ou expressão a ser registrada. Yes
metadata Adiciona uma propriedade personalizada à telemetria de rastreamento do Application Insights. Não

Atributos

Atributo Descrição Obrigatório Padrão
source Literal de cadeia de caracteres significativo para o visualizador de rastreamento e especificando a fonte da mensagem. Sim N/D
severidade Especifica o nível de gravidade do rastreamento. Os valores permitidos são verbose, information, error (do mais baixo ao mais alto). Não Detalhado
name Nome da propriedade. Sim N/D
valor Valor da propriedade. Sim N/D

Uso

Essa política pode ser usada nas seções e nos escopos da política a seguir.

  • Seções da política: entrada, saída, back-end, em caso de erro

  • Escopos da política: todos os escopos

Aguarde

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

Observação

Defina os elementos da política e os elementos filho na ordem fornecida na declaração da política. Saiba mais sobre como definir e editar as políticas de Gerenciamento de API.

Declaração de política

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

Exemplo

No exemplo a seguir há duas políticas choose como políticas filho imediatas da política wait. Cada uma dessas políticas choose executadas em paralelo. Cada política choose tenta recuperar um valor em cache. Se houver uma perda no cache, um serviço de back-end será chamado para fornecer o valor. 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. 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.

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

Elementos

Elemento Descrição Obrigatório
wait Elemento raiz. Pode conter como elementos filho somente as políticas send-request, cache-lookup-value e choose. Yes

Atributos

Atributo Descrição Obrigatório Padrão
para Determina se a política wait aguarda todas as políticas filho imediatas a serem concluídas ou apenas uma. Valores permitidos são:

- all – aguarda todas as políticas filho imediatas serem concluídas
- any - aguarda todas as políticas filho imediatas serem concluídas. 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.
Não all

Uso

Essa política pode ser usada nas seções e nos escopos da política a seguir.

  • Seções de política: entrada, saída, back-end
  • Escopos da política: todos os escopos

Próximas etapas

Para obter mais informações sobre como trabalhar com políticas, consulte: