Come usare i valori denominati nei criteri di Gestione API di AzureHow to use Named Values in Azure API Management policies

I criteri di Gestione API sono una potente funzionalità del sistema che consentono al portale di Azure di modificare il comportamento dell'API tramite la configurazione.API Management policies are a powerful capability of the system that allow the Azure portal to change the behavior of the API through configuration. I criteri sono una raccolta di istruzioni che vengono eseguite in modo sequenziale sulla richiesta o la risposta di un'API.Policies are a collection of statements that are executed sequentially on the request or response of an API. Le istruzioni dei criteri possono essere costruite usando valori di testo letterali, espressioni di criteri e valori denominati.Policy statements can be constructed using literal text values, policy expressions, and named values.

Ogni istanza del servizio Gestione API dispone di una raccolta di proprietà di coppie chiave/valore, chiamate valori denominati, globali per l'istanza del servizio.Each API Management service instance has a properties collection of key/value pairs, which is called Named Values, that are global to the service instance. Questi valori denominati possono essere usati per gestire i valori stringa costanti all'interno dell'intera configurazione e di tutti i criteri delle API.These Named Values can be used to manage constant string values across all API configuration and policies. Ogni proprietà può avere gli attributi seguenti:Each property can have the following attributes:

AttributoAttribute typeType DESCRIZIONEDescription
Nome visualizzatoDisplay name stringastring Stringa alfanumerica usata per fare riferimento alla proprietà nei criteri.Alphanumeric string used for referencing the property in the policies.
ValoreValue stringastring Valore della proprietà.The value of the property. Non può essere vuoto o contenere solo spazi.It may not be empty or consist only of whitespace.
SegretoSecret booleanboolean Determina se il valore è un segreto e se deve essere crittografato.Determines whether the value is a secret and should be encrypted or not.
TagTags matrice di valori stringarray of string Facoltativi. Quando specificati possono essere usati per filtrare l'elenco delle proprietà.Optional tags that when provided can be used to filter the property list.

Valori denominati

I valori delle proprietà possono contenere stringhe letterali ed espressioni di criteri.Property values can contain literal strings and policy expressions. Ad esempio, il valore di ExpressionProperty è un'espressione di criteri che restituisce una stringa contenente la data e l'ora correnti.For example, the value of ExpressionProperty is a policy expression that returns a string containing the current date and time. La proprietà ContosoHeaderValue è contrassegnata come un segreto, quindi il valore corrispondente non viene visualizzato.The property ContosoHeaderValue is marked as a secret, so its value is not displayed.

NOMEName ValoreValue SegretoSecret TagTags
ContosoHeaderContosoHeader TrackingIdTrackingId FalseFalse ContosoContoso
ContosoHeaderValueContosoHeaderValue •••••••••••••••••••••••••••••••••••••••••••• True True ContosoContoso
ExpressionPropertyExpressionProperty @(DateTime.Now.ToString())@(DateTime.Now.ToString()) FalseFalse

Per aggiungere e modificare una proprietàTo add and edit a property

Aggiungi proprietà

  1. Selezionare API in GESTIONE API.Select APIs from under API MANAGEMENT.
  2. Selezionare Valori denominati.Select Named values.
  3. Premere +Aggiungi.Press +Add.

    Nome e Valore sono obbligatori.Name and Value are required values. Se il valore della proprietà è un segreto, selezionare la casella di controllo Questo è un segreto.If this property value is a secret, check the This is a secret checkbox. Immettere uno o più tag facoltativi per organizzare i valori denominati e quindi fare clic su Salva.Enter one or more optional tags to help with organizing your named values, and click Save.

  4. Fare clic su Crea.Click Create.

Dopo aver creato la proprietà, è possibile modificarla facendo clic sulla proprietà.Once the property is created, you can edit it by clicking on the property. Se si modifica il nome della proprietà, tutti i criteri che fanno riferimento a tale proprietà vengono aggiornati automaticamente con il nuovo nome.If you change the property name, any policies that reference that property are automatically updated to use the new name.

Per informazioni sulla modifica di una proprietà tramite l'API REST, vedere la pagina relativa alla modifica di una proprietà tramite l'API REST.For information on editing a property using the REST API, see Edit a property using the REST API.

Per eliminare una proprietàTo delete a property

Per eliminare una proprietà, fare clic su Delete accanto alla proprietà da eliminare.To delete a property, click Delete beside the property to delete.

Importante

Se all'interno di almeno un criterio si fa riferimento alla proprietà, sarà possibile eliminare quest'ultima solo dopo averla rimossa da tutti i criteri che la usano.If the property is referenced by any policies, you will be unable to successfully delete it until you remove the property from all policies that use it.

Per informazioni sull'eliminazione di una proprietà tramite l'API REST, vedere la pagina relativa all'eliminazione di una proprietà tramite l'API REST.For information on deleting a property using the REST API, see Delete a property using the REST API.

Per cercare e filtrare valori denominatiTo search and filter Named Values

La scheda Valori denominati include funzionalità di ricerca e filtro che consentono di gestire i valori denominati.The Named values tab includes searching and filtering capabilities to help you manage your named values. Per filtrare l'elenco delle proprietà in base al nome di queste, immettere un termine di ricerca nella casella di testo di ricerca di proprietà .To filter the property list by property name, enter a search term in the Search property textbox. Per visualizzare tutti i valori denominati, cancellare il contenuto della casella di testo di ricerca di proprietà e premere INVIO.To display all named values, clear the Search property textbox and press enter.

Per filtrare l'elenco delle proprietà in base al valore dei tag, immettere uno o più tag nella casella di testo di filtro in base ai tag .To filter the property list by tag values, enter one or more tags into the Filter by tags textbox. Per visualizzare tutti i valori denominati, cancellare il contenuto della casella di testo di filtro in base ai tag e premere INVIO.To display all named values, clear the Filter by tags textbox and press enter.

Per usare una proprietàTo use a property

Per usare una proprietà di un criterio, inserire il nome della proprietà all'interno di parentesi graffe doppie, ad esempio {{ContosoHeader}}, come illustrato nell'esempio seguente:To use a property in a policy, place the property name inside a double pair of braces like {{ContosoHeader}}, as shown in the following example:

<set-header name="{{ContosoHeader}}" exists-action="override">
  <value>{{ContosoHeaderValue}}</value>
</set-header>

In questo esempio, la proprietà ContosoHeader viene usata come nome di un'intestazione in un criterio set-header e la proprietà ContosoHeaderValue viene usata come valore di tale intestazione.In this example, ContosoHeader is used as the name of a header in a set-header policy, and ContosoHeaderValue is used as the value of that header. Quando questo criterio viene valutato durante una richiesta o una risposta al gateway di Gestione API, {{ContosoHeader}} e {{ContosoHeaderValue}} vengono sostituiti dai valori delle rispettive proprietà.When this policy is evaluated during a request or response to the API Management gateway, {{ContosoHeader}} and {{ContosoHeaderValue}} are replaced with their respective property values.

I valori denominati possono essere usati come valori completi di attributo o di elemento, come illustrato nell'esempio precedente, ma possono anche essere inseriti all'interno di un'espressione di testo o combinati con una parte di un'espressione di testo, come illustrato nell'esempio seguente: <set-header name = "CustomHeader{{ContosoHeader}}" ...>Named values can be used as complete attribute or element values as shown in the previous example, but they can also be inserted into or combined with part of a literal text expression as shown in the following example: <set-header name = "CustomHeader{{ContosoHeader}}" ...>

I valori denominati possono anche contenere espressioni di criteri.Named values can also contain policy expressions. Nell'esempio seguente viene usata la proprietà ExpressionProperty .In the following example, the ExpressionProperty is used.

<set-header name="CustomHeader" exists-action="override">
    <value>{{ExpressionProperty}}</value>
</set-header>

Quando questo criterio viene valutato, {{ExpressionProperty}} viene sostituito dal valore corrispondente: @(DateTime.Now.ToString()).When this policy is evaluated, {{ExpressionProperty}} is replaced with its value: @(DateTime.Now.ToString()). Poiché il valore è un'espressione di criteri, l'espressione viene valutata e il criterio passa alla fase di esecuzione.Since the value is a policy expression, the expression is evaluated and the policy proceeds with its execution.

È possibile eseguirne i test nel portale per sviluppatori chiamando un'operazione il cui ambito contiene criteri con valori denominati.You can test this out in the developer portal by calling an operation that has a policy with named values in scope. Nell'esempio seguente viene chiamata un'operazione che contiene i due criteri di esempio precedenti set-header con valori denominati.In the following example, an operation is called with the two previous example set-header policies with named values. La risposta contiene due intestazioni personalizzate che vengono configurate tramite criteri con valori denominati.Note that the response contains two custom headers that were configured using policies with named values.

Portale per sviluppatori

Se si osserva la traccia di Controllo API relativa a una chiamata che include i due criteri con valori denominati degli esempi precedenti, è possibile vedere i due criteri set-header con i valori delle proprietà inseriti, nonché la valutazione delle espressioni dei criteri per la proprietà che contiene l'espressione.If you look at the API Inspector trace for a call that includes the two previous sample policies with named values, you can see the two set-header policies with the property values inserted as well as the policy expression evaluation for the property that contained the policy expression.

Traccia di Controllo API

Sebbene i valori delle proprietà possano contenere espressioni di criteri, non possono contenere altri valori denominati.While property values can contain policy expressions, property values can't contain other named values. Se il testo che contiene un riferimento a una proprietà viene usato come valore di una proprietà, ad esempio Property value text {{MyProperty}}, tale riferimento alla proprietà non viene sostituito e viene incluso come parte del valore della proprietà.If text containing a property reference is used for a property value, such as Property value text {{MyProperty}}, that property reference won't be replaced and will be included as part of the property value.

Passaggi successiviNext steps