Criteri avanzati di gestione APIAPI Management advanced policies

Questo argomento fornisce un riferimento per i criteri di Gestione API seguenti.This topic provides a reference for the following API Management policies. Per informazioni sull'aggiunta e sulla configurazione dei criteri, vedere Criteri di Gestione API.For information on adding and configuring policies, see Policies in API Management.

Criteri avanzatiAdvanced policies

Flusso di controlloControl flow

Il criterio choose si applica alle istruzioni del criterio incluse in base al risultato della valutazione di espressioni booleane, simili a un costrutto if-then-else o switch in un linguaggio di programmazione.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.

Istruzione del criterioPolicy 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>  

Il criterio del flusso di controllo deve contenere almeno un elemento <when/>.The control flow policy must contain at least one <when/> element. L'elemento <otherwise/> è facoltativo.The <otherwise/> element is optional. Le condizioni negli elementi <when/> vengono valutate in ordine di visualizzazione all'interno del criterio.Conditions in <when/> elements are evaluated in order of their appearance within the policy. Si applicano le istruzioni del criterio incluse all'interno del primo elemento <when/> con attributo di condizione uguale a true.Policy statement(s) enclosed within the first <when/> element with condition attribute equals true will be applied. I criteri inclusi all'interno dell'elemento <otherwise/>, se presente, vengono applicati se tutti gli attributi di condizione dell'elemento <when/> sono false.Policies enclosed within the <otherwise/> element, if present, will be applied if all of the <when/> element condition attributes are false.

EsempiExamples

EsempioExample

L'esempio seguente illustra un criterio set-variable e due criteri di flusso di controllo.The following example demonstrates a set-variable policy and two control flow policies.

Il criterio di impostazione della variabile si trova nella sezione in ingresso e crea isMobile, una variabile di contesto booleana, che è impostata su true se l'intestazione della richiesta User-Agent contiene il testo iPad o 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.

Il primo criterio di flusso di controllo è disponibile anche nella sezione in ingresso e applica in modo condizionale uno dei due criteri Imposta parametro di stringa della query in base al valore della variabile di contesto 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.

Il secondo criterio di flusso di controllo si trova nella sezione in uscita e applica in modo condizionale il criterio Converti XML in JSON quando isMobile è impostato su 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.GetValueOrDefault<bool>("isMobile"))">  
                <xml-to-json kind="direct" apply="always" consider-accept-header="false"/>  
            </when>  
        </choose>  
    </outbound>  
</policies>  

EsempioExample

Questo esempio mostra come eseguire operazioni di filtro sui contenuti rimuovendo elementi di dati dalla risposta ricevuta dal servizio back-end quando si usa il prodotto 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. Per una dimostrazione relativa alla configurazione e all'uso di questo criterio, vedere l'episodio 177 di Cloud Cover su altre funzionalità di Gestione API con Vlad Vinogradsky e passare direttamente al minuto 34:30.For a demonstration of configuring and using this policy, see Cloud Cover Episode 177: More API Management Features with Vlad Vinogradsky and fast-forward to 34:30. Iniziare dal minuto 31:50 per visualizzare una panoramica di The Dark Sky Forecast API, l'API usata in questa dimostrazione.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>  

ElementiElements

ElementoElement DescrizioneDescription ObbligatorioRequired
choosechoose Elemento radice.Root element. Yes
whenwhen La condizione da usare per le parti if o ifelse del criterio choose.The condition to use for the if or ifelse parts of the choose policy. Se il criterio choose ha più sezioni when, vengono valutate in modo sequenziale.If the choose policy has multiple when sections, they are evaluated sequentially. Una volta che la condition di un elemento when risulta true, non vengono valutate altre condizioni when.Once the condition of a when element evaluates to true, no further when conditions are evaluated. Yes
otherwiseotherwise Contiene il frammento di criterio da usare se nessuna delle condizioni when viene valutata true.Contains the policy snippet to be used if none of the when conditions evaluate to true. NoNo

AttributiAttributes

AttributoAttribute DescrizioneDescription ObbligatorioRequired
condition="Boolean expression | Boolean constant"condition="Boolean expression | Boolean constant" La costante o espressione booleana da valutare quando viene valutata l'istruzione del criterio contenente when.The Boolean expression or constant to evaluated when the containing when policy statement is evaluated. Yes

UsoUsage

Questo criterio può essere usato nelle sezioni e negli ambiti del criterio seguenti.This policy can be used in the following policy sections and scopes.

  • Sezioni del criterio:in ingresso, in uscita, back-end, on-errorPolicy sections: inbound, outbound, backend, on-error

  • Ambiti del criterio: tutti gli ambitiPolicy scopes: all scopes

Inoltra richiestaForward request

Il criterio forward-request inoltra la richiesta in ingresso al servizio back-end specificato nel contesto della richiesta.The forward-request policy forwards the incoming request to the backend service specified in the request context. L'URL del servizio back-end è specificato nelle impostazioni API e può essere modificato tramite il criterio imposta servizio back-end.The backend service URL is specified in the API settings and can be changed using the set backend service policy.

Nota

Se questo criterio viene rimosso, la richiesta non viene inoltrata al servizio back-end e i criteri nella sezione in uscita vengono valutati immediatamente dopo il completamento dei criteri nella sezione in ingresso.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.

Istruzione del criterioPolicy statement

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

EsempiExamples

EsempioExample

Il criterio a livello di API seguente inoltra tutte le richieste al servizio back-end con un intervallo di timeout di 60 secondi.The following API level policy forwards all 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>  

EsempioExample

Questo criterio a livello di operazione usa l'elemento base per ereditare il criterio di back-end dall'ambito di livello API padre.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>  

EsempioExample

Questo criterio a livello di operazione inoltra in modo esplicito tutte le richieste al servizio back-end con un timeout di 120 e non eredita il criterio di back-end a livello API padre.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>  

EsempioExample

Questo criterio a livello di operazione non inoltra le richieste al servizio 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>  

ElementiElements

ElementoElement DescrizioneDescription ObbligatorioRequired
forward-requestforward-request Elemento radice.Root element. Yes

AttributiAttributes

AttributoAttribute DescrizioneDescription ObbligatorioRequired DefaultDefault
timeout="integer"timeout="integer" Intervallo di timeout in secondi prima che la chiamata al servizio back-end abbia esito negativo.The timeout interval in seconds before the call to the backend service fails. NoNo No timeoutNo timeout
follow-redirects="true | false"follow-redirects="true | false" Specifica se i reindirizzamenti dal servizio back-end sono seguiti dal gateway o restituiti al chiamante.Specifies whether redirects from the backend service are followed by the gateway or returned to the caller. NoNo falsefalse

UtilizzoUsage

Questo criterio può essere usato nelle sezioni e negli ambiti del criterio seguenti.This policy can be used in the following policy sections and scopes.

  • Sezioni del criterio: back-endPolicy sections: backend
  • Ambiti del criterio: tutti gli ambitiPolicy scopes: all scopes

Limita concorrenzaLimit concurrency

Il criterio limit-concurrency previene ai criteri racchiusi l’esecuzione di un numero maggiore di richieste in un dato momento rispetto a quello specificato.The limit-concurrency policy prevents enclosed policies from executing by more than the specified number of requests at a given time. In caso di superamento di tale numero, le nuove richieste avranno subito esito negativo con codice di stato 429 Troppe richieste.Upon exceeding that number, new requests will fail immediately with 429 Too Many Requests status code.

Istruzione del criterioPolicy statement

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

esempiExamples

EsempioExample

Nell'esempio seguente viene illustrato come limitare il numero di richieste inoltrate a un back-end in base al valore di una variabile di contesto.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>

ElementiElements

ElementoElement DescrizioneDescription ObbligatorioRequired
limita concorrenzalimit-concurrency Elemento radice.Root element. Yes

AttributiAttributes

AttributoAttribute DescrizioneDescription ObbligatorioRequired DefaultDefault
keykey Stringa.A string. Espressione consentita.Expression allowed. Specifica l'ambito di concorrenza.Specifies the concurrency scope. Può essere condivisa da più criteri.Can be shared by multiple policies. Yes N/DN/A
numero maxmax-count Un intero.An integer. Specifica un numero massimo di richieste autorizzate ad accedere al criterio.Specifies a maximum number of requests that are allowed to enter the policy. Yes N/DN/A

UtilizzoUsage

Questo criterio può essere usato nelle sezioni e negli ambiti del criterio seguenti.This policy can be used in the following policy sections and scopes.

  • Sezioni del criterio:in ingresso, in uscita, back-end, on-errorPolicy sections: inbound, outbound, backend, on-error

  • Ambiti del criterio: tutti gli ambitiPolicy scopes: all scopes

Registra in Hub eventiLog to Event Hub

Il criterio log-to-eventhub invia messaggi nel formato specificato a un Hub eventi definito da un'entità Logger.The log-to-eventhub policy sends messages in the specified format to an Event Hub defined by a Logger entity. Come suggerisce il nome, il criterio viene usato per il salvataggio di informazioni selezionate sul contesto di richiesta o risposta per l'analisi online o offline.As its name implies, the policy is used for saving selected request or response context information for online or offline analysis.

Nota

Per una guida dettagliata sulla configurazione di un hub eventi e la registrazione di eventi, vedere Come registrare eventi nell'Hub eventi di Azure in Gestione API di Azure.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.

Istruzione del criterioPolicy 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>  

EsempioExample

È possibile usare qualsiasi stringa come valore da registrare in Hub eventi.Any string can be used as the value to be logged in Event Hubs. In questo esempio la data e l'ora, il nome del servizio di distribuzione, l'ID della richiesta, l'indirizzo IP e il nome dell'operazione per tutte le chiamate in entrata vengono registrati nel Logger dell'hub eventi registrato con l'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>  

ElementiElements

ElementoElement DescrizioneDescription ObbligatorioRequired
log-to-eventhublog-to-eventhub Elemento radice.Root element. Il valore di questo elemento è la stringa per la registrazione all'hub eventi.The value of this element is the string to log to your event hub. Yes

AttributiAttributes

AttributoAttribute DescrizioneDescription ObbligatorioRequired
logger-idlogger-id ID del Logger registrato con il servizio Gestione API.The id of the Logger registered with your API Management service. Yes
partition-idpartition-id Specifica l'indice della partizione a cui i messaggi vengono inviati.Specifies the index of the partition where messages are sent. facoltativo.Optional. Questo attributo non può essere usato se si usa partition-key.This attribute may not be used if partition-key is used.
partition-keypartition-key Specifica il valore usato per l'assegnazione della partizione quando vengono inviati i messaggi.Specifies the value used for partition assignment when messages are sent. facoltativo.Optional. Questo attributo non può essere usato se si usa partition-id.This attribute may not be used if partition-id is used.

UtilizzoUsage

Questo criterio può essere usato nelle sezioni e negli ambiti del criterio seguenti.This policy can be used in the following policy sections and scopes.

  • Sezioni del criterio:in ingresso, in uscita, back-end, on-errorPolicy sections: inbound, outbound, backend, on-error

  • Ambiti del criterio: tutti gli ambitiPolicy scopes: all scopes

Restituisci rispostaMock response

Il criterio mock-response, come implica il nome, viene usato per restituire API e operazioni.The mock-response, as the name implies, is used to mock APIs and operations. Interrompe la normale esecuzione della pipeline e restituisce una risposta fittizia direttamente al chiamante.It aborts normal pipeline execution and returns a mocked response to the caller. Il criterio cerca sempre di restituire risposte della massima fedeltà.The policy always tries to return responses of highest fidelity. Include esempi di contenuto di risposta ogni volta che è possibile.It prefers response content examples, whenever available. Nelle situazioni in cui vengono forniti schemi ma non esempi, genera risposte di esempio dagli schemi.It generates sample responses from schemas, when schemas are provided and examples are not. Se non sono presenti né esempi né schemi, restituisce risposte senza contenuto.If neither examples or schemas are found, responses with no content are returned.

Istruzione del criterioPolicy statement

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

esempiExamples

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

ElementiElements

ElementoElement DescrizioneDescription ObbligatoriaRequired
mock-responsemock-response Elemento radice.Root element. Yes

AttributiAttributes

AttributoAttribute DescrizioneDescription ObbligatorioRequired DefaultDefault
status-codestatus-code Specifica il codice di stato della risposta e viene usato per selezionare l'esempio o lo schema corrispondente.Specifies response status code and is used to select corresponding example or schema. NoNo 200200
content-typecontent-type Specifica il valore di intestazione della risposta Content-Type e viene usato per selezionare l'esempio o lo schema corrispondente.Specifies Content-Type response header value and is used to select corresponding example or schema. NoNo NoneNone

UsoUsage

Questo criterio può essere usato nelle sezioni e negli ambiti del criterio seguenti.This policy can be used in the following policy sections and scopes.

  • Sezioni del criterio: inbound, outbound, on-errorPolicy sections: inbound, outbound, on-error

  • Ambiti del criterio: tutti gli ambitiPolicy scopes: all scopes

RiprovaRetry

Il criterio retry esegue i criteri figlio una volta e quindi ritenta l'esecuzione degli stessi fino a quando il tentativo condition diventa false o fino a esaurimento del tentativo count.The retry policy executes its child policies once and then retries their execution until the retry condition becomes false or retry count is exhausted.

Istruzione del criterioPolicy 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>  

EsempioExample

Nella richiesta di esempio seguente l'inoltro viene ripetuto fino a dieci volte usando un algoritmo di ripetizione esponenziale.In the following example request forewarding is retried up to ten times using exponential retry algorithm. Poiché first-fast-retry è impostato su false, tutti i tentativi sono soggetti all'algoritmo di ripetizione esponenziale.Since first-fast-retry is set to false, all retry attempts are subject to the exponsntial retry algorithm.


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

ElementiElements

ElementoElement DescrizioneDescription ObbligatorioRequired
retryretry Elemento radice.Root element. Può contenere tutti gli altri criteri come elementi figlio.May contain any other policies as its child elements. Yes

AttributiAttributes

AttributoAttribute DescrizioneDescription ObbligatorioRequired DefaultDefault
conditioncondition Valore letterale booleano o espressione che specifica se i tentativi devono essere interrotti (false) o devono continuare (true).A boolean literal or expression specifying if retries should be stopped (false) or continued (true). Yes N/DN/A
countcount Numero positivo che specifica il numero massimo di tentativi da eseguire.A positive number specifying the maximum number of retries to attempt. Yes N/DN/A
intervalinterval Numero positivo in secondi che specifica l'intervallo di attesa tra i tentativi di ripetizione.A positive number in seconds specifying the wait interval between the retry attempts. Yes N/DN/A
max-intervalmax-interval Un numero positivo che specifica l'intervallo di attesa massimo tra i tentativi di ripetizione.A positive number in seconds specifying the maximum wait interval between the retry attempts. Viene usato per implementare un algoritmo di ripetizione esponenziale.It is used to implement an exponential retry algorithm. NoNo N/DN/A
deltadelta Numero positivo in secondi che specifica l'incremento dell'intervallo di attesa.A positive number in seconds specifying the wait interval increment. Viene usato per implementare gli algoritmi di ripetizione lineari ed esponenziali.It is used to implement the linear and exponential retry algorithms. NoNo N/DN/A
first-fast-retryfirst-fast-retry Se impostato su true, il primo tentativo di ripetizione viene eseguito immediatamente.If set to true , the first retry attempt is performed immediately. NoNo false

Nota

Se è specificato solo interval, vengono eseguiti tentativi a intervallo fisso.When only the interval is specified, fixed interval retries are performed.
Se vengono specificati solo interval e delta, viene usato un algoritmo di ripetizione a intervalli lineari, in cui il tempo di attesa tra i tentativi viene calcolato secondo la formula seguente: 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.
Se vengono specificati interval, max-interval e delta,viene applicato un algoritmo di ripetizione a intervalli esponenziali, in cui il tempo di attesa tra i tentativi cresce in modo esponenziale dal valore interval al valore max-interval, secondo la formula seguente: 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 forumula - min(interval + (2^count - 1) * random(delta * 0.8, delta * 1.2), max-interval).

UtilizzoUsage

Questo criterio può essere usato nelle sezioni e negli ambiti del criterio seguenti.This policy can be used in the following policy sections and scopes . Si noti che le restrizioni sull'uso dei criteri figlio verranno ereditate da questo criterio.Note that child policy usage restrictions will be inherited by this policy.

  • Sezioni del criterio:in ingresso, in uscita, back-end, on-errorPolicy sections: inbound, outbound, backend, on-error

  • Ambiti del criterio: tutti gli ambitiPolicy scopes: all scopes

Restituisci rispostaReturn response

Il criterio return-response interrompe l'esecuzione della pipeline e restituisce al chiamante una risposta predefinita o personalizzata.The return-response policy aborts pipeline execution and returns either a default or custom response to the caller. La risposta predefinita è 200 OK, senza corpo.Default response is 200 OK with no body. La risposta personalizzata può essere specificata tramite una variabile di contesto o le istruzioni del criterio.Custom response can be specified via a context variable or policy statements. Quando entrambi sono specificati, la risposta contenuta all'interno della variabile di contesto viene modificata tramite le istruzioni del criterio prima di essere restituita al chiamante.When both are provided, the response contained within the context variable is modified by the policy statements before being returned to the caller.

Istruzione del criterioPolicy statement

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

EsempioExample

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

ElementiElements

ElementoElement DescrizioneDescription ObbligatorioRequired
return-responsereturn-response Elemento radice.Root element. Yes
set-headerset-header Istruzione del criterio.set-header.A set-header policy statement. NoNo
set-bodyset-body Istruzione del criterio.set-body.A set-body policy statement. NoNo
set-statusset-status Istruzione del criterio set-status.A set-status policy statement. NoNo

AttributiAttributes

AttributoAttribute DescrizioneDescription ObbligatorioRequired
response-variable-nameresponse-variable-name Nome della variabile di contesto a cui fa riferimento, ad esempio, un criterio di upstream send-request e contenente un oggetto Response.The name of the context variable referenced from, for example, an upstream send-request policy and containing a Response object facoltativo.Optional.

UtilizzoUsage

Questo criterio può essere usato nelle sezioni e negli ambiti del criterio seguenti.This policy can be used in the following policy sections and scopes.

  • Sezioni del criterio:in ingresso, in uscita, back-end, on-errorPolicy sections: inbound, outbound, backend, on-error

  • Ambiti del criterio: tutti gli ambitiPolicy scopes: all scopes

Invia richiesta unidirezionaleSend one way request

Il criterio send-one-way-request invia la richiesta specificata all'URL specificato senza attendere una risposta.The send-one-way-request policy sends the provided request to the specified URL without waiting for a response.

Istruzione del criterioPolicy statement

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

EsempioExample

Questo criterio di esempio illustra come usare il criterio send-one-way-request per inviare un messaggio a una chat di Slack, se il codice della risposta HTTP è maggiore o uguale 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. Per altre informazioni relative a questo esempio, vedere Uso di servizi esterni dal servizio Gestione API di 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>  

ElementiElements

ElementoElement DescrizioneDescription ObbligatorioRequired
send-one-way-requestsend-one-way-request Elemento radice.Root element. Yes
URLurl URL della richiesta.The URL of the request. No if mode=copy; otherwise yes.No if mode=copy; otherwise yes.
staticomethod Metodo HTTP usato nella richiesta.The HTTP method for the request. No if mode=copy; otherwise yes.No if mode=copy; otherwise yes.
intestazioneheader Intestazione della richiesta.Request header. Usare più elementi di intestazione per più intestazioni della richiesta.Use multiple header elements for multiple request headers. NoNo
bodybody Corpo della richiesta.The request body. NoNo

AttributiAttributes

AttributoAttribute DescrizioneDescription ObbligatorioRequired DefaultDefault
mode="string"mode="string" Determina se questa è una nuova richiesta o una copia della richiesta corrente.Determines whether this is a new request or a copy of the current request. In modalità in uscita, mode=copy non avvia il corpo della richiesta.In outbound mode, mode=copy does not initialize the request body. NoNo NuovoNew
namename Specifica il nome dell'intestazione da impostare.Specifies the name of the header to be set. Yes N/DN/A
exists-actionexists-action Specifica l'azione da eseguire quando l'intestazione è già specificata.Specifies what action to take when the header is already specified. Questo attributo deve avere uno dei valori seguenti.This attribute must have one of the following values.

- override - sostituisce il valore dell'intestazione esistente.- override - replaces the value of the existing header.
- skip - non sostituisce il valore dell'intestazione esistente.- skip - does not replace the existing header value.
- append - aggiunge il valore dell'intestazione esistente.- append - appends the value to the existing header value.
- delete - elimina l'intestazione dalla richiesta.- delete - removes the header from the request.

Se è impostato su override, l'integrazione di più voci con lo stesso nome avrà come risultato l'impostazione dell'intestazione in base a tutte le voci, che saranno elencate più volte. Nel risultato saranno impostati solo i valori elencati.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.
NoNo overrideoverride

UtilizzoUsage

Questo criterio può essere usato nelle sezioni e negli ambiti del criterio seguenti.This policy can be used in the following policy sections and scopes.

  • Sezioni del criterio:in ingresso, in uscita, back-end, on-errorPolicy sections: inbound, outbound, backend, on-error

  • Ambiti del criterio: tutti gli ambitiPolicy scopes: all scopes

Invio richiestaSend request

Il criterio send-request invia la richiesta fornita all'URL specificato, attendendo non oltre il valore di timeout impostato.The send-request policy sends the provided request to the specified URL, waiting no longer than the set timeout value.

Istruzione del criterioPolicy 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>  
</send-request>  

EsempioExample

Questo esempio mostra un metodo per verificare un token di riferimento con un server di autorizzazione.This example shows one way to verify a reference token with an authorization server. Per altre informazioni relative a questo esempio, vedere Uso di servizi esterni dal servizio Gestione API di 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 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>  
  <base />  
</inbound>  

ElementiElements

ElementoElement DescrizioneDescription ObbligatorioRequired
send-requestsend-request Elemento radice.Root element. Yes
URLurl URL della richiesta.The URL of the request. No if mode=copy; otherwise yes.No if mode=copy; otherwise yes.
staticomethod Metodo HTTP usato nella richiesta.The HTTP method for the request. No if mode=copy; otherwise yes.No if mode=copy; otherwise yes.
intestazioneheader Intestazione della richiesta.Request header. Usare più elementi di intestazione per più intestazioni della richiesta.Use multiple header elements for multiple request headers. NoNo
bodybody Corpo della richiesta.The request body. NoNo

AttributiAttributes

AttributoAttribute DescrizioneDescription ObbligatorioRequired DefaultDefault
mode="string"mode="string" Determina se questa è una nuova richiesta o una copia della richiesta corrente.Determines whether this is a new request or a copy of the current request. In modalità in uscita, mode=copy non avvia il corpo della richiesta.In outbound mode, mode=copy does not initialize the request body. NoNo NuovoNew
response-variable-name="string"response-variable-name="string" Se non è presente, viene usato context.Response.If not present, context.Response is used. NoNo N/DN/A
timeout="integer"timeout="integer" Intervallo di timeout in secondi prima che la chiamata all'URL abbia esito negativo.The timeout interval in seconds before the call to the URL fails. NoNo 6060
ignore-errorignore-error Se impostato su true e la richiesta restituisce un errore:If true and the request results in an error:

- Se è stato specificato response-variable-name, questo conterrà un valore null.- If response-variable-name was specified it will contain a null value.
- Se response-variable-name non è stato specificato, context.Request non verrà aggiornato.- If response-variable-name was not specified, context.Request will not be updated.
NoNo falsefalse
namename Specifica il nome dell'intestazione da impostare.Specifies the name of the header to be set. Yes N/DN/A
exists-actionexists-action Specifica l'azione da eseguire quando l'intestazione è già specificata.Specifies what action to take when the header is already specified. Questo attributo deve avere uno dei valori seguenti.This attribute must have one of the following values.

- override - sostituisce il valore dell'intestazione esistente.- override - replaces the value of the existing header.
- skip - non sostituisce il valore dell'intestazione esistente.- skip - does not replace the existing header value.
- append - aggiunge il valore dell'intestazione esistente.- append - appends the value to the existing header value.
- delete - elimina l'intestazione dalla richiesta.- delete - removes the header from the request.

Se è impostato su override, l'integrazione di più voci con lo stesso nome avrà come risultato l'impostazione dell'intestazione in base a tutte le voci, che saranno elencate più volte. Nel risultato saranno impostati solo i valori elencati.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.
NoNo overrideoverride

UtilizzoUsage

Questo criterio può essere usato nelle sezioni e negli ambiti del criterio seguenti.This policy can be used in the following policy sections and scopes.

  • Sezioni del criterio:in ingresso, in uscita, back-end, on-errorPolicy sections: inbound, outbound, backend, on-error

  • Ambiti del criterio: tutti gli ambitiPolicy scopes: all scopes

Impostare il proxy HTTPSet HTTP proxy

Il criterio proxy consente di indirizzare le richieste inoltrate ai back-end tramite un proxy HTTP.The proxy policy allows you to route requests forwarded to backends via an HTTP proxy. È supportato solo HTTP (non HTTPS) tra il gateway e il proxy.Only HTTP (not HTTPS) is supported between the gateway and the proxy. Solo autenticazione Basic e NTLM.Basic and NTLM authentication only.

Istruzione del criterioPolicy statement

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

EsempioExample

Si noti l'utilizzo di proprietà come valori di nome utente e password per evitare di archiviare informazioni riservate nel documento dei criteri.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}} />

ElementiElements

ElementoElement DescrizioneDescription ObbligatorioRequired
proxyproxy Elemento radiceRoot element Yes

AttributiAttributes

AttributoAttribute DescrizioneDescription ObbligatorioRequired DefaultDefault
url="string"url="string" URL del proxy nel formato http://host:port.Proxy URL in the form of http://host:port. Yes N/D N/A
username="string"username="string" Nome utente da usare per l'autenticazione con il proxy.Username to be used for authentication with the proxy. NoNo N/D N/A
password="string"password="string" Password da usare per l'autenticazione con il proxy.Password to be used for authentication with the proxy. NoNo N/D N/A

UtilizzoUsage

Questo criterio può essere usato nelle sezioni e negli ambiti del criterio seguenti.This policy can be used in the following policy sections and scopes.

  • Sezioni del criterio: inboundPolicy sections: inbound

  • Ambiti del criterio: tutti gli ambitiPolicy scopes: all scopes

Impostare il metodo di richiestaSet request method

Il criterio set-method consente di modificare il metodo di richiesta HTTP per una richiesta.The set-method policy allows you to change the HTTP request method for a request.

Istruzione del criterioPolicy statement

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

EsempioExample

Questo criterio di esempio che usa il criterio set-method mostra un esempio di invio di un messaggio a una chat di Slack, se il codice della risposta HTTP è maggiore o uguale 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. Per altre informazioni relative a questo esempio, vedere Uso di servizi esterni dal servizio Gestione API di 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>  

ElementiElements

ElementoElement DescrizioneDescription ObbligatorioRequired
set-methodset-method Elemento radice.Root element. Il valore dell'elemento specifica il metodo HTTP.The value of the element specifies the HTTP method. Yes

UtilizzoUsage

Questo criterio può essere usato nelle sezioni e negli ambiti del criterio seguenti.This policy can be used in the following policy sections and scopes.

  • Sezioni del criterio: inbound, on-errorPolicy sections: inbound, on-error

  • Ambiti del criterio: tutti gli ambitiPolicy scopes: all scopes

Impostare il codice di statoSet status code

Il criterio set-status modifica il codice di stato HTTP sul valore specificato.The set-status policy sets the HTTP status code to the specified value.

Istruzione del criterioPolicy statement

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

EsempioExample

Questo esempio illustra come restituire una risposta 401 se il token di autorizzazione non è valido.This example shows how to return a 401 response if the authorization token is invalid. Per altre informazioni, vedere Uso di servizi esterni dal servizio Gestione API di Azure.For 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>  

ElementiElements

ElementoElement DescrizioneDescription ObbligatorioRequired
set-statusset-status Elemento radice.Root element. Yes

AttributiAttributes

AttributoAttribute DescrizioneDescription ObbligatorioRequired DefaultDefault
code="integer"code="integer" Il codice di stato HTTP da restituire.The HTTP status code to return. Yes N/DN/A
reason="string"reason="string" Descrizione del motivo per la restituzione del codice di stato.A description of the reason for returning the status code. Yes N/DN/A

UtilizzoUsage

Questo criterio può essere usato nelle sezioni e negli ambiti del criterio seguenti.This policy can be used in the following policy sections and scopes.

  • Sezioni del criterio: outbound, backend, on-errorPolicy sections: outbound, backend, on-error
  • Ambiti del criterio: tutti gli ambitiPolicy scopes: all scopes

Impostare una variabileSet variable

Il criterio set-variable dichiara una variabile di contesto e assegna a essa un valore specificato tramite un'espressione o un valore letterale di stringa.The set-variable policy declares a context variable and assigns it a value specified via an expression or a string literal. Se l'espressione contiene un valore letterale, questo verrà convertito in una stringa e il tipo di valore sarà 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.

Istruzione del criterioPolicy statement

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

EsempioExample

L'esempio seguente illustra un criterio di impostazione della variabile nella sezione in ingresso.The following example demonstrates a set variable policy in the inbound section. Il criterio di impostazione della variabile crea isMobile, una variabile di contesto booleana, che è impostata su true se l'intestazione della richiesta User-Agent contiene il testo iPad o 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"))" />  

ElementiElements

ElementoElement DescrizioneDescription ObbligatorioRequired
set-variableset-variable Elemento radice.Root element. Yes

AttributiAttributes

AttributoAttribute DescrizioneDescription ObbligatorioRequired
namename Nome della variabile.The name of the variable. Yes
valuevalue Valore della variabile.The value of the variable. Può essere un'espressione o un valore letterale.This can be an expression or a literal value. Yes

UtilizzoUsage

Questo criterio può essere usato nelle sezioni e negli ambiti del criterio seguenti.This policy can be used in the following policy sections and scopes.

  • Sezioni del criterio:in ingresso, in uscita, back-end, on-errorPolicy sections: inbound, outbound, backend, on-error
  • Ambiti del criterio: tutti gli ambitiPolicy scopes: all scopes

Tipi consentitiAllowed types

Le espressioni usate nel criterio set-variable devono restituire uno dei seguenti tipi di base.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?

TracciaTrace

Il criterio trace aggiunge una stringa nell'output di Controllo API.The trace policy adds a string into the API Inspector output. Il criterio verrà eseguito solo quando la traccia è attivata, ad esempio quando è presente l'intestazione della richiesta Ocp-Apim-Trace ed è impostata su true e quando è presente l'intestazione della richiesta Ocp-Apim-Subscription-Key e contiene una chiave valida associata all'account amministratore.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.

Istruzione del criterioPolicy statement


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

ElementiElements

ElementoElement DescrizioneDescription ObbligatorioRequired
tracetrace Elemento radice.Root element. Yes

AttributiAttributes

AttributoAttribute DescrizioneDescription ObbligatorioRequired DefaultDefault
una sezione sourcesource Valore letterale della stringa significativo per il visualizzatore di tracce e che specifica l'origine del messaggio.String literal meaningful to the trace viewer and specifying the source of the message. Yes N/DN/A

UtilizzoUsage

Questo criterio può essere usato nelle sezioni e negli ambiti del criterio seguenti.This policy can be used in the following policy sections and scopes .

  • Sezioni del criterio:in ingresso, in uscita, back-end, on-errorPolicy sections: inbound, outbound, backend, on-error

  • Ambiti del criterio: tutti gli ambitiPolicy scopes: all scopes

AttesaWait

Il criterio wait esegue i criteri figlio immediati in parallelo e attende che tutti o uno dei relativi criteri figlio immediati vengano completati prima di terminare la sua attività.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. I criteri di attesa possono avere come criteri figlio immediati i criteri Invio della richiesta, Recupero del valore dalla cache e Flusso di controllo.The wait policy can have as its immediate child policies Send request, Get value from cache, and Control flow policies.

Istruzione del criterioPolicy statement

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

EsempioExample

L'esempio seguente contiene due criteri choose come criteri figlio immediato dei criteri wait.In the following example there are two choose policies as immediate child policies of the wait policy. Ognuno di questi criteri choose viene eseguito in parallelo.Each of these choose policies executes in parallel. Ogni criterio choose tenta di recuperare un valore memorizzato nella cache.Each choose policy attempts to retrieve a cached value. Se si verifica un mancato riscontro nella cache, viene chiamato un servizio di back-end per fornire il valore.If there is a cache miss, a backend service is called to provide the value. In questo esempio il criterio wait non si completa fino al completamento di tutti i relativi criteri figlio immediati, poiché l'attributo for è impostato su 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. In questo esempio le variabili di contesto (execute-branch-one, value-one, execute-branch-two e value-two) vengono dichiarate all'esterno dell'ambito di questo criterio di esempio.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>  

ElementiElements

ElementoElement DescrizioneDescription ObbligatorioRequired
waitwait Elemento radice.Root element. Può contenere come elementi figlio solo i criteri send-request, cache-lookup-value e choose.May contain as child elements only send-request, cache-lookup-value, and choose policies. Yes

AttributiAttributes

AttributoAttribute DescrizioneDescription ObbligatorioRequired DefaultDefault
forfor Determina se il criterio wait attende il completamento di tutti o solo uno dei criteri figlio immediati.Determines whether the wait policy waits for all immediate child policies to be completed or just one. I valori consentiti sono i seguenti:Allowed values are:

- all: consente di attendere il completamento di tutti i criteri figlio immediati- all - wait for all immediate child policies to complete
- any: consente di attendere il completamento di uno dei criteri figlio immediati.- any - wait for any immediate child policy to complete. Dopo il completamento del primo criterio figlio immediato, il criterio wait si completa e l'esecuzione di qualsiasi altro criterio figlio immediato viene arrestata.Once the first immediate child policy has completed, the wait policy completes and execution of any other immediate child policies is terminated.
NoNo tuttiall

UtilizzoUsage

Questo criterio può essere usato nelle sezioni e negli ambiti del criterio seguenti.This policy can be used in the following policy sections and scopes.

  • Sezioni del criterio: inbound, outbound, back-endPolicy sections: inbound, outbound, backend
  • Ambiti del criterio: tutti gli ambitiPolicy scopes: all scopes

Passaggi successiviNext steps

Per altre informazioni sull'uso di questi criteri, vedere:For more information working with policies, see: