Criteri di trasformazione di Gestione APIAPI Management transformation 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 di trasformazione Transformation policies

  • json-to-xml : converte il corpo della richiesta o della risposta da JSON a XML.Convert JSON to XML - Converts request or response body from JSON to XML.

  • xml-to-json : converte il corpo della richiesta o della risposta da XML a JSON.Convert XML to JSON - Converts request or response body from XML to JSON.

  • find-and-replace : trova una sottostringa di richiesta o risposta e la sostituisce con una sottostringa diversa.Find and replace string in body - Finds a request or response substring and replaces it with a different substring.

  • Maschera URL nel contenuto : riscrive (maschera) i collegamenti nel corpo della risposta, in modo che facciano riferimento al collegamento equivalente tramite il gateway.Mask URLs in content - Re-writes (masks) links in the response body so that they point to the equivalent link via the gateway.

  • set-backend-service : consente di cambiare il servizio back-end per una richiesta in ingresso.Set backend service - Changes the backend service for an incoming request.

  • set-body : consente di impostare il corpo del messaggio per richieste in ingresso e in uscita.Set body - Sets the message body for incoming and outgoing requests.

  • Imposta intestazione HTTP : assegna un valore a una intestazione di risposta e/o di richiesta esistente oppure aggiunge una nuova intestazione di risposta e/o di richiesta.Set HTTP header - Assigns a value to an existing response and/or request header or adds a new response and/or request header.

  • Imposta parametro di stringa della query : aggiunge, sostituisce il valore di o elimina il parametro di stringa della query di richiesta.Set query string parameter - Adds, replaces value of, or deletes request query string parameter.

  • rewrite-uri : converte un URL di richiesta dal formato pubblico al formato previsto dal servizio Web.Rewrite URL - Converts a request URL from its public form to the form expected by the web service.

  • Trasforma XML usando una trasformazione XSLT - applica una trasformazione da XSL a XML nel corpo della richiesta o della risposta.Transform XML using an XSLT - Applies an XSL transformation to XML in the request or response body.

Converti JSON in XML Convert JSON to XML

Il criterio json-to-xml converte il corpo della richiesta o della risposta da JSON a XML.The json-to-xml policy converts a request or response body from JSON to XML.

Istruzione del criterioPolicy statement

<json-to-xml apply="always | content-type-json" consider-accept-header="true | false"/>  

EsempioExample

<policies>  
    <inbound>  
        <base />  
    </inbound>  
    <outbound>  
        <base />  
        <json-to-xml apply="always" consider-accept-header="false" />  
    </outbound>  
</policies>  

ElementiElements

NomeName DescrizioneDescription ObbligatorioRequired
json-to-xmljson-to-xml Elemento radice.Root element. Yes

AttributiAttributes

NomeName DescrizioneDescription ObbligatorioRequired DefaultDefault
applyapply Questo attributo deve essere impostato su uno dei valori seguenti.The attribute must be set to one of the following values.

- always - applica sempre la conversione.- always - always apply conversion.
- content-type-json - applica la conversione solo se l'intestazione Content-Type della risposta indica la presenza di JSON.- content-type-json - convert only if response Content-Type header indicates presence of JSON.
Yes N/DN/A
consider-accept-headerconsider-accept-header Questo attributo deve essere impostato su uno dei valori seguenti.The attribute must be set to one of the following values.

- true - applica la conversione se JSON è richiesto nell'intestazione Accept della richiesta.- true - apply conversion if JSON is requested in request Accept header.
- false - applica sempre la conversione.- false -always apply conversion.
NoNo truetrue

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, on-errorPolicy sections: inbound, outbound, on-error

  • Ambiti del criterio: globale, prodotto, API, operazionePolicy scopes: global, product, API, operation

Converti XML in JSON Convert XML to JSON

Il criterio xml-to-json converte il corpo della richiesta o della risposta da XML a JSON.The xml-to-json policy converts a request or response body from XML to JSON. Il criterio può essere applicato per modernizzare le API basate su servizi Web back-end solo di tipo XML.This policy can be used to modernize APIs based on XML-only backend web services.

Istruzione del criterioPolicy statement

<xml-to-json kind="javascript-friendly | direct" apply="always | content-type-xml" consider-accept-header="true | false"/>  

EsempioExample

<policies>  
    <inbound>  
        <base />  
    </inbound>  
    <outbound>  
        <base />  
        <xml-to-json kind="direct" apply="always" consider-accept-header="false" />  
    </outbound>  
</policies>  

ElementiElements

NomeName DescrizioneDescription ObbligatorioRequired
xml-to-jsonxml-to-json Elemento radice.Root element. Yes

AttributiAttributes

NomeName DescrizioneDescription ObbligatorioRequired DefaultDefault
kindkind Questo attributo deve essere impostato su uno dei valori seguenti.The attribute must be set to one of the following values.

- javascript-friendly - il JSON convertito ha un formato intuitivo per gli sviluppatori JavaScript.- javascript-friendly - the converted JSON has a form friendly to JavaScript developers.
- direct - il JSON convertito riflette la struttura del documento XML originario.- direct - the converted JSON reflects the original XML document's structure.
Yes N/DN/A
applyapply Questo attributo deve essere impostato su uno dei valori seguenti.The attribute must be set to one of the following values.

- always - esegue sempre la conversione.- always - convert always.
- content-type-xml - applica la conversione solo se l'intestazione Content-Type della risposta indica la presenza di XML.- content-type-xml - convert only if response Content-Type header indicates presence of XML.
Yes N/DN/A
consider-accept-headerconsider-accept-header Questo attributo deve essere impostato su uno dei valori seguenti.The attribute must be set to one of the following values.

- true - applica la conversione se XML è richiesto nell'intestazione Accept della richiesta.- true - apply conversion if XML is requested in request Accept header.
- false - applica sempre la conversione.- false -always apply conversion.
NoNo truetrue

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, on-errorPolicy sections: inbound, outbound, on-error

  • Ambiti del criterio: globale, prodotto, API, operazionePolicy scopes: global, product, API, operation

Trova e sostituisci stringa nel corpo Find and replace string in body

Il criterio find-and-replace trova una sottostringa di richiesta o risposta e la sostituisce con una sottostringa diversa.The find-and-replace policy finds a request or response substring and replaces it with a different substring.

Istruzione del criterioPolicy statement

<find-and-replace from="what to replace" to="replacement" />  

EsempioExample

<find-and-replace from="notebook" to="laptop" />  

ElementiElements

NomeName DescrizioneDescription ObbligatorioRequired
find-and-replacefind-and-replace Elemento radice.Root element. Yes

AttributiAttributes

NomeName DescrizioneDescription ObbligatorioRequired DefaultDefault
fromfrom Stringa da cercare.The string to search for. Yes N/DN/A
toto La stringa di sostituzione.The replacement string. Specificare una stringa di sostituzione con lunghezza zero per rimuovere la stringa di ricerca.Specify a zero length replacement string to remove the search string. 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: globale, prodotto, API, operazionePolicy scopes: global, product, API, operation

Maschera URL nel contenuto Mask URLs in content

Il criterio redirect-content-urls riscrive (maschera) i collegamenti nel corpo della risposta, in modo che facciano riferimento al collegamento equivalente tramite il gateway.The redirect-content-urls policy re-writes (masks) links in the response body so that they point to the equivalent link via the gateway. Usare la sezione outbound per riscrivere i collegamenti al corpo della risposta affinché facciano riferimento al gateway.Use in the outbound section to re-write response body links to make them point to the gateway. Usare la sezione inbound per ottenere l'effetto opposto.Use in the inbound section for an opposite effect.

Nota

Questo criterio non modifica i valori delle intestazioni, ad esempio le intestazioni Location.This policy does not change any header values such as Location headers. Per modificare i valori delle intestazioni, usare il criterio set-header.To change header values, use the set-header policy.

Istruzione del criterioPolicy statement

<redirect-content-urls />  

EsempioExample

<redirect-content-urls />  

ElementiElements

NomeName DescrizioneDescription ObbligatorioRequired
redirect-content-urlsredirect-content-urls Elemento radice.Root element. 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, outboundPolicy sections: inbound, outbound

  • Ambiti del criterio: globale, prodotto, API, operazionePolicy scopes: global, product, API, operation

Imposta servizio back-end Set backend service

Usare il criterio set-backend-service per reindirizzare una richiesta in ingresso a un back-end diverso da quello specificato nelle impostazioni dell'API per l'operazione.Use the set-backend-service policy to redirect an incoming request to a different backend than the one specified in the API settings for that operation. Questo criterio cambia l'URL di base del servizio back-end della richiesta in arrivo con quello specificato nel criterio.This policy changes the backend service base URL of the incoming request to the one specified in the policy.

Istruzione del criterioPolicy statement

<set-backend-service base-url="base URL of the backend service" />  

EsempioExample

<policies>  
    <inbound>  
        <choose>  
            <when condition="@(context.Request.Url.Query.GetValueOrDefault("version") == "2013-05")">  
                <set-backend-service base-url="http://contoso.com/api/8.2/" />  
            </when>  
            <when condition="@(context.Request.Url.Query.GetValueOrDefault("version") == "2014-03")">  
                <set-backend-service base-url="http://contoso.com/api/9.1/" />  
            </when>  
        </choose>  
        <base />  
    </inbound>  
    <outbound>  
        <base />  
    </outbound>  
</policies>  

In questo esempio il criterio del servizio back-end indirizza le richieste in base al valore di versione passato nella stringa di query a un servizio back-end diverso rispetto a quello specificato nell'API.In this example the set backend service policy routes requests based on the version value passed in the query string to a different backend service than the one specified in the API.

Inizialmente l'URL di base del servizio back-end è quello specificato nelle impostazioni dell'API.Initially the backend service base URL is derived from the API settings. Pertanto, l'URL della richiesta https://contoso.azure-api.net/api/partners/15?version=2013-05&subscription-key=abcdef diventa http://contoso.com/api/10.4/partners/15?version=2013-05&subscription-key=abcdef dove http://contoso.com/api/10.4/ è l'URL del servizio back-end specificato nelle impostazioni dell'API.So the request URL https://contoso.azure-api.net/api/partners/15?version=2013-05&subscription-key=abcdef becomes http://contoso.com/api/10.4/partners/15?version=2013-05&subscription-key=abcdef where http://contoso.com/api/10.4/ is the backend service URL specified in the API settings.

Quando viene applicata l'istruzione del criterio <choose>, l'URL di base del servizio back-end può essere di nuovo modificato in http://contoso.com/api/8.2 o http://contoso.com/api/9.1, a seconda del valore del parametro della query versione richiesta.When the <choose> policy statement is applied the backend service base URL may change again either to http://contoso.com/api/8.2 or http://contoso.com/api/9.1, depending on the value of the version request query parameter. Se, ad esempio, il valore è "2013-15", l'URL della richiesta finale sarà http://contoso.com/api/8.2/partners/15?version=2013-05&subscription-key=abcdef.For example, if the value is "2013-15" the final request URL becomes http://contoso.com/api/8.2/partners/15?version=2013-05&subscription-key=abcdef.

Se occorre un'ulteriore trasformazione della richiesta, è possibile usare altri criteri di trasformazione.If further transformation of the request is desired, other Transformation policies can be used. Ad esempio, per rimuovere il parametro della query di versione una volta instradata la richiesta verso un back-end specifico, ad esempio, è possibile usare il criterio Imposta parametro della stringa di query per rimuovere l'attributo della versione divenuta ridondante.For example, to remove the version query parameter now that the request is being routed to a version specific backend, the Set query string parameter policy can be used to remove the now redundant version attribute.

EsempioExample

<policies>  
    <inbound>  
        <set-backend-service backend-id="my-sf-service" sf-partition-key="@(context.Request.Url.Query.GetValueOrDefault("userId","")" sf-replica-type="primary" /> 
    </inbound>  
    <outbound>  
        <base />  
    </outbound>  
</policies>  

In questo esempio il criterio indirizza la richiesta a un back-end dell'infrastruttura del servizio tramite la stringa di query dell'ID utente come chiave di partizione e tramite la replica della partizione primaria.In this example the policy routes the request to a service fabric backend, using the userId query string as the partition key and using the primary replica of the partition.

ElementiElements

NomeName DescrizioneDescription ObbligatorioRequired
set-backend-serviceset-backend-service Elemento radice.Root element. Yes

AttributiAttributes

NomeName DescrizioneDescription ObbligatorioRequired DefaultDefault
base-urlbase-url Nuovo URL di base del servizio back-end.New backend service base URL. NoNo N/DN/A
backend-idbackend-id Identificatore del back-end verso cui avviene il routing.Identifier of the backend to route to. NoNo N/DN/A
sf-partition-keysf-partition-key Applicabile solo quando il back-end è un servizio di Service Fabric e viene specificato tramite "backend-id".Only applicable when the backend is a Service Fabric service and is specified using 'backend-id'. Usato per risolvere una partizione specifica dal servizio di risoluzione del nome.Used to resolve a specific partition from the name resolution service. NoNo N/DN/A
sf-replica-typesf-replica-type Applicabile solo quando il back-end è un servizio di Service Fabric e viene specificato tramite "backend-id".Only applicable when the backend is a Service Fabric service and is specified using 'backend-id'. Controlla se la richiesta deve passare alla replica primaria o secondaria di una partizione.Controls if the request should go to the primary or secondary replica of a partition. NoNo N/DN/A
sf-resolve-conditionsf-resolve-condition Applicabile solo quando il back-end è un servizio di Service Fabric.Only applicable when the backend is a Service Fabric service. Condizione che identifica se la chiamata al back-end di Service Fabric deve essere ripetuta con una nuova risoluzione.Condition identifying if the call to Service Fabric backend has to be repeated with new resolution. NoNo N/DN/A
sf-service-instance-namesf-service-instance-name Applicabile solo quando il back-end è un servizio di Service Fabric.Only applicable when the backend is a Service Fabric service. Consente di modificare le istanze del servizio durante il runtime.Allows to change service instances at runtime. 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: inbound, backendPolicy sections: inbound, backend

  • Ambiti del criterio: globale, prodotto, API, operazionePolicy scopes: global, product, API, operation

Imposta corpo Set body

Il criterio set-body consente di impostare il corpo del messaggio per le richieste in ingresso e in uscita.Use the set-body policy to set the message body for incoming and outgoing requests. Per accedere al corpo del messaggio è possibile usare la proprietà context.Request.Body o context.Response.Body, a seconda che il criterio sia nella sezione inbound o outbound.To access the message body you can use the context.Request.Body property or the context.Response.Body, depending on whether the policy is in the inbound or outbound section.

Importante

Si noti che, per impostazione predefinita, quando si accede al corpo del messaggio con context.Request.Body o context.Response.Body, il corpo del messaggio originale viene perso e deve essere impostato riportandolo nell'espressione.Note that by default when you access the message body using context.Request.Body or context.Response.Body, the original message body is lost and must be set by returning the body back in the expression. Per mantenere il contenuto del corpo, impostare il parametro preserveContent su true quando si accede al messaggio.To preserve the body content, set the preserveContent parameter to true when accessing the message. Se preserveContent è impostato su true e l'espressione restituisce un corpo diverso, viene usato il corpo restituito.If preserveContent is set to true and a different body is returned by the expression, the returned body is used.

Tenere presente le considerazioni seguenti quando si usa il criterio set-body.Please note the following considerations when using the set-body policy.

  • Se il criterio set-body viene usato per restituire un corpo nuovo o aggiornato non è necessario impostare preserveContent su true, perché il nuovo contenuto del corpo viene fornito in modo esplicito.If you are using the set-body policy to return a new or updated body you don't need to set preserveContent to true because you are explicitly supplying the new body contents.
    • Non ha senso mantenere il contenuto di una risposta nella pipeline in ingresso, poiché non è ancora stata ricevuta alcuna risposta.Preserving the content of a response in the inbound pipeline doesn't make sense because there is no response yet.
    • Non ha senso neanche mantenere il contenuto di una risposta nella pipeline in uscita perché a questo punto la richiesta è già stata inviata al back-end.Preserving the content of a request in the outbound pipeline doesn't make sense because the request has already been sent to the backend at this point.
    • Se questo criterio viene usato quando non vi è alcun corpo del messaggio, ad esempio in un'operazione GET in ingresso, viene generata un'eccezione.If this policy is used when there is no message body, for example in an inbound GET, an exception is thrown.

Per altre informazioni, vedere le sezioni context.Request.Body, context.Response.Bodye IMessage nella tabella Variabile di contesto.For more information, see the context.Request.Body, context.Response.Body, and the IMessage sections in the Context variable table.

Istruzione del criterioPolicy statement

<set-body>new body value as text</set-body>  

EsempiExamples

Esempio di testo letteraleLiteral text example

<set-body>Hello world!</set-body>  

Esempio di accesso al corpo come stringa.Example accessing the body as a string. Si noti che il corpo della richiesta originale viene mantenuto per potervi accedere più avanti nella pipeline.Note that we are preserving the original request body so that we can access it later in the pipeline.

<set-body>  
@{   
    string inBody = context.Request.Body.As<string>(preserveContent: true);   
    if (inBody[0] =='c') {   
        inBody[0] = 'm';   
    }   
    return inBody;   
}  
</set-body>  

Esempio di accesso al corpo come JObject.Example accessing the body as a JObject. Si noti che il corpo della richiesta originale non viene mantenuto e l'accesso a tale corpo più avanti nella pipeline genererà un'eccezione.Note that since we are not reserving the original request body, accesing it later in the pipeline will result in an exception.

<set-body>   
@{   
    JObject inBody = context.Request.Body.As<JObject>();   
    if (inBody.attribute == <tag>) {   
        inBody[0] = 'm';   
    }   
    return inBody.ToString();   
}   
</set-body>  

Filtrare la risposta in base al prodottoFilter response based on product

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>  

Uso di modelli Liquid con set bodyUsing Liquid templates with set body

Il criterio set-body può essere configurato per l'uso del linguaggio di modellazione Liquid per trasformare il corpo di una richiesta o di una risposta.The set-body policy can be configured to use the Liquid templating language to transfom the body of a request or response. Può essere molto efficace se si desidera modificare completamente il formato del messaggio.This can be very effective if you need to completely reshape the format of your message.

Importante

L'implementazione di Liquid usato nel criterio set-body è configurato in "modalità C#".The implementation of Liquid used in the set-body policy is configured in 'C# mode'. Questo è particolarmente importante quando si eseguono operazioni quali l'applicazione del filtro.This is particularly important when doing things such as filtering. Ad esempio, l'uso di un filtro data richiede l'uso della convenzione Pascal e della formattazione delle date C#, ad esempio:As an example, using a date filter requires the use of Pascal casing and C# date formatting e.g.:

{{body.foo.startDateTime| Data:"yyyyMMddTHH:mm:ddZ"}}{{body.foo.startDateTime| Date:"yyyyMMddTHH:mm:ddZ"}}

Importante

Per eseguire correttamente l'associazione a un corpo XML utilizzando il modello Liquid, usare un criterio set-header per impostare il tipo di contenuto su application/xml, text/xml (o su qualsiasi tipo che termini con +xml); per un corpo JSON, deve essere application/json, testo/json (o qualsiasi tipo che termini con +json).In order to correctly bind to an XML body using the Liquid template, use a set-header policy to set Content-Type to either application/xml, text/xml (or any type ending with +xml); for a JSON body, it must be application/json, text/json (or any type ending with +json).

Convertire JSON in SOAP usando un modello LiquidConvert JSON to SOAP using a Liquid template

<set-body template="liquid">
    <soap:Envelope xmlns="http://tempuri.org/" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
        <soap:Body>
            <GetOpenOrders>
                <cust>{{body.getOpenOrders.cust}}</cust>
            </GetOpenOrders>
        </soap:Body>
    </soap:Envelope>
</set-body>

Trasformare JSON usando un modello LiquidTranform JSON using a Liquid template

{
"order": {
    "id": "{{body.customer.purchase.identifier}}",
    "summary": "{{body.customer.purchase.orderShortDesc}}"
    }
}

ElementiElements

NomeName DescrizioneDescription ObbligatorioRequired
set-bodyset-body Elemento radice.Root element. Contiene il testo del corpo o un'espressione che restituisce un corpo.Contains the body text or an expressions that returns a body. Yes

ProprietàProperties

NomeName DescrizioneDescription ObbligatorioRequired DefaultDefault
templatetemplate Consente di modificare la modalità di modello in cui verrà eseguito il criterio del corpo impostato.Used to change the templating mode that the set body policy will run in. Al momento, l'unico valore supportato è:Currently the only supported value is:

-liquid - i criteri del corpo impostati useranno il motore del modello liquidi- liquid - the set body policy will use the liquid templating engine
NoNo liquidliquid

Per accedere alle informazioni sulla richiesta e la risposta, il modello Liquid può essere associato a un oggetto di contesto con le proprietà seguenti:For accessing information about the request and response, the Liquid template can bind to a context object with the following properties:

context.
    Request.
        Url
        Method
        OriginalMethod
        OriginalUrl
        IpAddress
        MatchedParameters
        HasBody
        ClientCertificates
        Headers

    Response.
        StatusCode
        Method
        Headers
Url.
    Scheme
    Host
    Port
    Path
    Query
    QueryString
    ToUri
    ToString

OriginalUrl.
    Scheme
    Host
    Port
    Path
    Query
    QueryString
    ToUri
    ToString

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: globale, prodotto, API, operazionePolicy scopes: global, product, API, operation

Imposta intestazione HTTP Set HTTP header

Il criterio set-header assegna un valore a un'intestazione di risposta e/o di richiesta esistente oppure aggiunge una nuova intestazione di risposta e/o di richiesta.The set-header policy assigns a value to an existing response and/or request header or adds a new response and/or request header.

Inserisce un elenco di intestazioni HTTP in un messaggio HTTP.Inserts a list of HTTP headers into an HTTP message. Se inserito in una pipeline in entrata, questo criterio imposta le intestazioni HTTP per la richiesta passata al servizio di destinazione.When placed in an inbound pipeline, this policy sets the HTTP headers for the request being passed to the target service. Se inserito in una pipeline in uscita, questo criterio imposta le intestazioni HTTP per la risposta inviata al client del gateway.When placed in an outbound pipeline, this policy sets the HTTP headers for the response being sent to the gateway’s client.

Istruzione del criterioPolicy statement

<set-header name="header name" exists-action="override | skip | append | delete">  
    <value>value</value> <!--for multiple headers with the same name add additional value elements-->  
</set-header>  

EsempiExamples

EsempioExample

<set-header name="some header name" exists-action="override">  
    <value>20</value>   
</set-header>  

Inoltro di informazioni di contesto al servizio back-endForward context information to the backend service

Questo esempio illustra come applicare criteri a livello di API per fornire informazioni di contesto al servizio back-end.This example shows how to apply policy at the API level to supply context information to the backend service. 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 10: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 10:30. Al minuto 12:10 è illustrato come richiamare un'operazione nel portale per sviluppatori, dove è possibile vedere all'opera il criterio in questione.At 12:10 there is a demo of calling an operation in the developer portal where you can see the policy at work.

<!-- Copy this snippet into the inbound element to forward some context information, user id and the region the gateway is hosted in, to the backend service for logging or evaluation -->  
<set-header name="x-request-context-data" exists-action="override">  
  <value>@(context.User.Id)</value>  
  <value>@(context.Deployment.Region)</value>  
</set-header>  

Per altre informazioni, vedere Espressioni di criteri e Variabile di contesto.For more information, see Policy expressions and Context variable.

ElementiElements

NomeName DescrizioneDescription ObbligatorioRequired
set-headerset-header Elemento radice.Root element. Yes
valuevalue Specifica il valore dell'intestazione da impostare.Specifies the value of the header to be set. Se occorrono più intestazioni con lo stesso nome, aggiungere altri elementi value.For multiple headers with the same name add additional value elements. Yes

ProprietàProperties

NomeName DescrizioneDescription ObbligatorioRequired DefaultDefault
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
namename Specifica il nome dell'intestazione da impostare.Specifies name of the header to be set. 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: globale, prodotto, API, operazionePolicy scopes: global, product, API, operation

Imposta parametro di stringa della query Set query string parameter

Il criterio set-query-parameter aggiunge, sostituisce il valore di o elimina il parametro di stringa della query di richiesta.The set-query-parameter policy adds, replaces value of, or deletes request query string parameter. Può essere usato per passare i parametri di query previsti dal servizio back-end che sono facoltativi o non sono mai presenti nella richiesta.Can be used to pass query parameters expected by the backend service which are optional or never present in the request.

Istruzione del criterioPolicy statement

<set-query-parameter name="param name" exists-action="override | skip | append | delete">  
    <value>value</value> <!--for multiple parameters with the same name add additional value elements-->  
</set-query-parameter>  

EsempiExamples

EsempioExample


<set-query-parameter>  
  <parameter name="api-key" exists-action="skip">  
    <value>12345678901</value>  
  </parameter>  
  <!-- for multiple parameters with the same name add additional value elements -->  
</set-query-parameter>  

Inoltro di informazioni di contesto al servizio back-endForward context information to the backend service

Questo esempio illustra come applicare criteri a livello di API per fornire informazioni di contesto al servizio back-end.This example shows how to apply policy at the API level to supply context information to the backend service. 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 10: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 10:30. Al minuto 12:10 è illustrato come richiamare un'operazione nel portale per sviluppatori, dove è possibile vedere all'opera il criterio in questione.At 12:10 there is a demo of calling an operation in the developer portal where you can see the policy at work.

<!-- Copy this snippet into the inbound element to forward a piece of context, product name in this example, to the backend service for logging or evaluation -->  
<set-query-parameter name="x-product-name" exists-action="override">  
  <value>@(context.Product.Name)</value>  
</set-query-parameter>  

Per altre informazioni, vedere Espressioni di criteri e Variabile di contesto.For more information, see Policy expressions and Context variable.

ElementiElements

NomeName DescrizioneDescription ObbligatorioRequired
set-query-parameterset-query-parameter Elemento radice.Root element. Yes
valuevalue Specifica il valore del parametro di query da impostare.Specifies the value of the query parameter to be set. Se occorrono più parametri di query con lo stesso nome, aggiungere altri elementi value.For multiple query parameters with the same name add additional value elements. Yes

ProprietàProperties

NomeName DescrizioneDescription ObbligatorioRequired DefaultDefault
exists-actionexists-action Specifica l'azione da eseguire quando il parametro di query è già specificato.Specifies what action to take when the query parameter is already specified. Questo attributo deve avere uno dei valori seguenti.This attribute must have one of the following values.

- override - sostituisce il valore del parametro esistente.- override - replaces the value of the existing parameter.
- skip - non sostituisce il valore del parametro di query esistente.- skip - does not replace the existing query parameter value.
- append - aggiunge il valore del parametro di query esistente.- append - appends the value to the existing query parameter value.
- delete - elimina il parametro di query dalla richiesta.- delete - removes the query parameter from the request.

Se è impostato su override, l'integrazione di più voci con lo stesso nome avrà come risultato l'impostazione del parametro di query 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 query parameter being set according to all entries (which will be listed multiple times); only listed values will be set in the result.
NoNo overrideoverride
namename Specifica il nome del parametro di query da impostare.Specifies name of the query parameter to be set. 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: inbound, backendPolicy sections: inbound, backend

  • Ambiti del criterio: globale, prodotto, API, operazionePolicy scopes: global, product, API, operation

Riscrivi URL Rewrite URL

Il criterio rewrite-uri converte un URL di richiesta dal formato pubblico al formato previsto dal servizio Web, come mostrato nell'esempio seguente.The rewrite-uri policy converts a request URL from its public form to the form expected by the web service, as shown in the following example.

  • URL pubblico - http://api.example.com/storenumber/ordernumberPublic URL - http://api.example.com/storenumber/ordernumber

  • URL richiesta - http://api.example.com/v2/US/hardware/storenumber&ordernumber?City&StateRequest URL - http://api.example.com/v2/US/hardware/storenumber&ordernumber?City&State

    Il criterio può essere usato quando un URL ideale per utenti e/o per il browser deve essere trasformato nel formato di URL previsto dal servizio Web.This policy can be used when a human and/or browser-friendly URL should be transformed into the URL format expected by the web service. Il criterio deve essere applicato soltanto quando viene esposto un formato di URL alternativo, ad esempio URL semplici, URL RESTful, URL ideali per gli utenti o URL ideali per SEO, che sono URL puramente strutturali, non includono una stringa di query ma contengono solo il percorso della risorsa, dopo lo schema e l'autorità.This policy only needs to be applied when exposing an alternative URL format, such as clean URLs, RESTful URLs, user-friendly URLs or SEO-friendly URLs that are purely structural URLs that do not contain a query string and instead contain only the path of the resource (after the scheme and the authority). Sono spesso usati a fini estetici, di usabilità o di ottimizzazione dei motori di ricerca (SEO, Search Engine Optimization).This is often done for aesthetic, usability, or search engine optimization (SEO) purposes.

Nota

Il criterio consente di aggiungere solo parametri delle stringhe di query.You can only add query string parameters using the policy. Non è possibile aggiungere un parametro di percorso di modello aggiuntivo nell'URL riscritto.You cannot add extra template path parameters in the rewrite URL.

Istruzione del criterioPolicy statement

<rewrite-uri template="uri template" copy-unmatched-params="true | false" />  

EsempioExample

<policies>  
    <inbound>  
        <base />  
        <rewrite-uri template="/v2/US/hardware/{storenumber}&{ordernumber}?City=city&State=state" />  
    </inbound>  
    <outbound>  
        <base />  
    </outbound>  
</policies>  
<!-- Assuming incoming request is /get?a=b&c=d and operation template is set to /get?a={b} -->
<policies>  
    <inbound>  
        <base />  
        <rewrite-uri template="/put" />  
    </inbound>  
    <outbound>  
        <base />  
    </outbound>  
</policies>  
<!-- Resulting URL will be /put?c=d -->
<!-- Assuming incoming request is /get?a=b&c=d and operation template is set to /get?a={b} -->
<policies>  
    <inbound>  
        <base />  
        <rewrite-uri template="/put" copy-unmatched-params="false" />  
    </inbound>  
    <outbound>  
        <base />  
    </outbound>  
</policies>  
<!-- Resulting URL will be /put -->

ElementiElements

NomeName DescrizioneDescription ObbligatorioRequired
rewrite-urirewrite-uri Elemento radice.Root element. Yes

AttributiAttributes

AttributoAttribute DescrizioneDescription ObbligatorioRequired DefaultDefault
templatetemplate URL effettivo del servizio Web con eventuali parametri delle stringhe di query.The actual web service URL with any query string parameters. Quando si usano le espressioni, l'intero valore deve essere un'espressione.When using expressions, the whole value must be an expression. Yes N/DN/A
copy-unmatched-paramscopy-unmatched-params Specifica se i parametri di query nella richiesta in ingresso non presenti nel modello di URL originale vengono aggiunti all'URL definito dal modello di riscritturaSpecifies whether query parameters in the incoming request not present in the original URL template are added to the URL defined by the re-write template NoNo truetrue

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: prodotto, API, operazionePolicy scopes: product, API, operation

Trasforma XML usando XSLT Transform XML using an XSLT

Il criterio Transform XML using an XSLT applica una trasformazione XSL all'XML nel corpo della richiesta o della risposta.The Transform XML using an XSLT policy applies an XSL transformation to XML in the request or response body.

Istruzione del criterioPolicy statement

<xsl-transform>  
    <parameter name="User-Agent">@(context.Request.Headers.GetValueOrDefault("User-Agent","non-specified"))</parameter>  
    <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">  
        <xsl:output method="xml" indent="yes" />  
        <xsl:param name="User-Agent" />  
        <xsl:template match="* | @* | node()">  
            <xsl:copy>  
                <xsl:if test="self::* and not(parent::*)">  
                    <xsl:attribute name="User-Agent">  
                        <xsl:value-of select="$User-Agent" />  
                    </xsl:attribute>  
                </xsl:if>  
                <xsl:apply-templates select="* | @* | node()" />  
            </xsl:copy>  
        </xsl:template>  
    </xsl:stylesheet>  
  </xsl-transform>  

EsempioExample

<policies>  
  <inbound>  
      <base />  
  </inbound>  
  <outbound>  
      <base />  
      <xsl-transform>  
        <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">  
            <xsl:output omit-xml-declaration="yes" method="xml" indent="yes" />  
            <!-- Copy all nodes directly-->  
            <xsl:template match="node()| @*|*">  
                <xsl:copy>  
                    <xsl:apply-templates select="@* | node()|*" />  
                </xsl:copy>  
            </xsl:template>  
        </xsl:stylesheet>  
    </xsl-transform>  
  </outbound>  
</policies>  

ElementiElements

NomeName DescrizioneDescription ObbligatorioRequired
xsl-transformxsl-transform Elemento radice.Root element. Yes
parametroparameter Consente di definire le variabili usate nella trasformazioneUsed to define variables used in the transform NoNo
xsl:stylesheetxsl:stylesheet Elemento del foglio di stile principale.Root stylesheet element. Tutti gli elementi e gli attributi definiti rispettano le specifiche XSLT standardAll elements and attributes defined within follow the standard XSLT specification 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, outboundPolicy sections: inbound, outbound

  • Ambiti del criterio: globale, prodotto, API, operazionePolicy scopes: global, product, API, operation

Passaggi successiviNext steps

Per altre informazioni sull'uso dei criteri, vedere Criteri di Gestione API.For more information working with policies, see Policies in API Management.