Esplorare i criteri di Gestione API

Completato

In Gestione API di Azure i criteri consentono al server di pubblicazione di modificare il comportamento dell'API tramite la configurazione. I criteri sono una raccolta di istruzioni che vengono eseguite in modo sequenziale in caso di richiesta o risposta di un'API.

I criteri vengono applicati nel gateway che si trova tra il consumer di API e l'API gestita. Il gateway riceve tutte le richieste e in genere le inoltra invariate all'API sottostante. Tuttavia i criteri possono applicare modifiche sia alla richiesta in ingresso che alla risposta in uscita. Le espressioni di criteri possono essere usate come valori di attributo o valori di testo in uno qualsiasi dei criteri di Gestione API, salvo diversamente specificato dai criteri.

Informazioni sulla configurazione dei criteri

La definizione dei criteri è un semplice documento XML che descrive una sequenza di istruzioni in ingresso e in uscita. Il codice XML può essere modificato direttamente nella finestra di definizione.

La configurazione è divisa in inbound, backend, outbound e on-error. La serie di istruzioni dei criteri specificati viene eseguita in un determinato ordine in relazione a una richiesta e una risposta.

<policies>
  <inbound>
    <!-- statements to be applied to the request go here -->
  </inbound>
  <backend>
    <!-- statements to be applied before the request is forwarded to 
         the backend service go here -->
  </backend>
  <outbound>
    <!-- statements to be applied to the response go here -->
  </outbound>
  <on-error>
    <!-- statements to be applied if there is an error condition go here -->
  </on-error>
</policies>

Se si verifica un errore durante l'elaborazione di una richiesta, tutti i rimanenti passaggi nelle sezioni inbound, backend, o outbound vengono ignoratI e l'esecuzione prosegue con le istruzioni nella sezione on-error. Inserendo istruzioni di criteri nella sezione on-error è possibile rivedere l'errore utilizzando la proprietà context.LastError, esaminare e personalizzare la risposta di errore tramite il criterio set-body e configurare che cosa accade se si verifica un errore.

Espressioni di criteri

A meno che il criterio non specifichi diversamente, le espressioni di criteri possono essere usate come valori di attributo o valori di testo in uno dei criteri di Gestione API. Un'espressione di criteri è:

• un'unica istruzione C# racchiusa in @(expression), o
• un blocco di codice C# con più istruzioni, racchiuso in @{expression}, che restituisce un valore

Ogni espressione ha accesso alla variabile context fornita esplicitamente e a un subset consentito di tipi .NET Framework.

Le espressioni di criteri offrono un mezzo sofisticato per controllare il traffico e modificare il comportamento dell'API senza richiedere di scrivere codice specializzato o modificare i servizi back-end.

Nell'esempio seguente vengono usate espressioni di criteri e i criteri set-header per aggiungere i dati utente alla richiesta in ingresso. L'intestazione aggiunta include l'ID utente associato alla chiave di sottoscrizione nella richiesta e l'area in cui è ospitato il gateway che elabora la richiesta.

<policies>
    <inbound>
        <base />
        <set-header name="x-request-context-data" exists-action="override">
            <value>@(context.User.Id)</value>
            <value>@(context.Deployment.Region)</value>
      </set-header>
    </inbound>
</policies>

Applicare i criteri specificati in ambiti diversi

Se si usano un criterio a livello globale e un criterio configurato per un'API, ogni volta che viene usata quella determinata API vengono applicati entrambi i criteri. Gestione API consente l'ordinamento deterministico delle istruzioni combinate per i criteri attraverso l'elemento di base.

<policies>
    <inbound>
        <cross-domain />
        <base />
        <find-and-replace from="xyz" to="abc" />
    </inbound>
</policies>

Nella definizione dei criteri di esempio precedente, l'istruzione cross-domain viene eseguita prima. I criteri find-and-replace verranno eseguiti dopo qualsiasi criterio in un ambito più ampio.

Filtrare il contenuto della risposta

Il criterio definito nell'esempio seguente Illustra come filtrare elementi dati dal payload della risposta in base al prodotto associato alla richiesta.

Il frammento di codice presuppone che il contenuto della risposta sia formattato come JSON e contenga proprietà a livello radice denominate al minuto, oraria, giornaliera e flag.

<policies>
  <inbound>
    <base />
  </inbound>
  <backend>
    <base />
  </backend>
  <outbound>
    <base />
    <choose>
      <when condition="@(context.Response.StatusCode == 200 && context.Product.Name.Equals("Starter"))">
        <!-- NOTE that we are not using preserveContent=true when deserializing response body stream into a JSON object since we don't intend to access it again. See details on /azure/api-management/api-management-transformation-policies#SetBody -->
        <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>    
  </outbound>
  <on-error>
    <base />
  </on-error>
</policies>