Come usare le proprietà nei criteri di Gestione API di AzureHow to use properties in Azure API Management policies

I criteri di Gestione API sono una potente funzionalità del sistema che consentono all'entità di pubblicazione di modificare il comportamento dell'API tramite la configurazione.API Management policies are a powerful capability of the system that allow the publisher 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. Per creare istruzioni dei criteri è possibile usare valori di testo, espressioni di criteri e proprietà.Policy statements can be constructed using literal text values, policy expressions, and properties.

Ogni istanza del servizio Gestione API dispone di una raccolta di proprietà di coppie chiave/valore globali per l'istanza stessa.Each API Management service instance has a properties collection of key/value pairs that are global to the service instance. Queste proprietà possono essere usate per gestire i valori stringa costanti all'interno dell'intera configurazione e di tutti i criteri delle API.These properties can be used to manage constant string values across all API configuration and policies. Ogni proprietà ha gli attributi seguenti.Each property has the following attributes.

AttributoAttribute TipoType DescrizioneDescription
NameName stringastring Nome della proprietà.The name of the property. Può contenere solo lettere, cifre, punti, trattini e caratteri di sottolineatura.It may contain only letters, digits, period, dash, and underscore characters.
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.

Le proprietà vengono configurate nel portale di pubblicazione nella scheda Properties . Nell'esempio seguente, sono configurate tre proprietà.Properties are configured in the publisher portal on the Properties tab. In the following example, three properties are configured.

Properties

I valori delle proprietà possono contenere stringhe letterali ed espressioni di criteri.Property values can contain literal strings and policy expressions. Nella tabella seguente sono mostrate le tre proprietà di esempio precedenti e i relativi attributi.The following table shows the previous three sample properties and their attributes. Il valore di ExpressionProperty è un'espressione di criteri che restituisce una stringa contenente la data e l'ora correnti.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.

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

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.

Le proprietà possono essere usate come valori completi di attributo o di elemento, come illustrato nell'esempio precedente, ma possono anche essere inserite all'interno di un'espressione di testo o combinate con una parte di un'espressione di testo, come illustrato nell'esempio seguente: <set-header name = "CustomHeader{{ContosoHeader}}" ...>Properties 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}}" ...>

Le proprietà possono anche contenere espressioni di criteri.Properties 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 eseguire un test nel portale per sviluppatori chiamando un'operazione il cui ambito contiene un criterio con proprietà.You can test this out in the developer portal by calling an operation that has a policy with properties in scope. Nell'esempio seguente viene chiamata un'operazione che contiene i due criteri di esempio precedenti set-header con proprietà.In the following example, an operation is called with the two previous example set-header policies with properties. Si noti che la risposta contiene due intestazioni personalizzate configurate tramite criteri con proprietà.Note that the response contains two custom headers that were configured using policies with properties.

Portale per sviluppatori

Se si osserva la traccia di Controllo API relativa a una chiamata che include i due criteri con proprietà 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 properties, 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

Si noti che mentre i valori delle proprietà possono contenere espressioni di criteri, i valori delle proprietà non possono contenere altre proprietà.Note that while property values can contain policy expressions, property values can't contain other properties. 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.

Per creare una proprietàTo create a property

Per creare una proprietà, fare clic su Aggiungi proprietà nella scheda Proprietà.To create a property, click Add property on the Properties tab.

Aggiungi proprietà

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

Aggiungi proprietà

Quando si salva una nuova proprietà, la casella di testo di ricerca di proprietà viene popolata con il nome della nuova proprietà e la nuova proprietà viene visualizzata.When a new property is saved, the Search property textbox is populated with the name of the new property and the new property is displayed. Per visualizzare tutte le proprietà, cancellare il contenuto della casella di testo di ricerca di proprietà e premere INVIO.To display all properties, clear the Search property textbox and press enter.

Properties

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

Per modificare una proprietàTo edit a property

Per modificare una proprietà, fare clic su Edit accanto alla proprietà da modificare.To edit a property, click Edit beside the property to edit.

Modifica proprietà

Apportare le modifiche desiderate e fare clic su Save.Make any desired changes, and click Save. 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.

Modifica proprietà

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.

Elimina proprietà

Fare clic su Sì, elimina per confermare.Click Yes, delete it to confirm.

Conferma dell'eliminazione

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 proprietàTo search and filter properties

La scheda Properties include funzionalità di ricerca e filtro che consentono di gestire le proprietà.The Properties tab includes searching and filtering capabilities to help you manage your properties. 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 tutte le proprietà, cancellare il contenuto della casella di testo di ricerca di proprietà e premere INVIO.To display all properties, clear the Search property textbox and press enter.

Search

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 tutte le proprietà, cancellare il contenuto della casella di testo di filtro in base ai tag e premere INVIO.To display all properties, clear the Filter by tags textbox and press enter.

Filtro

Passaggi successiviNext steps

Guardare un video introduttivoWatch a video overview