Uso delle espressioni per accedere ai valori di runtime

5 minuti

Le espressioni consentono ai parametri del modello di criteri di ottenere i propri valori dai dati di runtime. Le funzioni possono accedere e trasformare i dati di runtime dalle intestazioni, dalla query e dal corpo della richiesta e della risposta dall'API. Le espressioni vengono usate spesso anche per accedere ai dati dalle proprietà di connessione del connettore. Ad esempio, @connectionParameters('HostUrl') otterrebbe il valore configurato per la proprietà di connessione HostUrl, il che consentirebbe a un creatore di modificare l'URL del servizio nell'ambito della connessione, come accade negli scenari API di test rispetto a quelli di produzione. Questa unità esamina alcune espressioni comuni usate con i modelli di criteri.

Nozioni di base sulle espressioni

Le espressioni vengono valutate durante il runtime. Un'espressione è una sequenza di una o più funzioni, operatori o valori espliciti. Quando si definisce un'espressione in un parametro, si antepone all'espressione il simbolo della chiocciola (@). Se l'espressione restituisce un valore numerico dove è previsto un input di stringa, è possibile usare la notazione con parentesi graffe ({}) per convertire automaticamente il valore numerico in una stringa.

L'esempio seguente mostra come vengono usate queste notazioni:

@{connectionParameters('HostPortNumber')}

Per garantire che le espressioni non abbiano esito negativo a causa di proprietà non valide, verificare che non ci siano valori Null nel percorso. Il seguente esempio non riesce se summary è Null:

@body().summary.amount

Se si includono valori espliciti (valori letterali stringa) nelle espressioni, usare una virgoletta singola. Non usare le virgolette doppie perché creerebbero un conflitto con il markup usato per l'espressione.

Uso del corpo della risposta

È possibile usare le funzioni body() per accedere al corpo della risposta durante il runtime. Ad esempio, l'azione Elenca fatture restituisce i seguenti dati:

{ “invoices”: [ { “invoiceid”:”1234”}] }

In questo esempio, la funzione body() fa riferimento alle parentesi graffe esterne ({}) e ha una proprietà invoice che corrisponde a una matrice.

È possibile creare un'espressione che faccia riferimento alla matrice invoices usando la seguente logica:

@body().invoices

È anche possibile creare un'espressione che accede a invoiceid dal primo elemento della matrice usando la seguente logica:

@body().invoices[0].invoiceid

Uso dei valori di intestazione

Con l'espressione @headers('headerName') è possibile accedere ai valori dall'intestazione. È anche possibile usare l'espressione @headers come parametro del modello di destinazione quando si usa il modello di criteri Imposta intestazione dall'URL. Questo approccio consente di recuperare un valore da un URL e impostarlo nell'intestazione. Ad esempio, un connettore potrebbe usare questa espressione per ottenere un token di accesso dal servizio per consentire la pubblicazione su una pagina. L'esempio seguente mostra una possibile configurazione del modello di criteri per ottenere il token di accesso per l'azione Pubblica nella pagina.

Uso dei valori di query

Come per le intestazioni, è possibile usare l'espressione @queryParameters('queryParameterName') per accedere ai parametri di query della richiesta. Questo esempio è simile all'esempio precedente relativo alle intestazioni, ma in questo caso il token recuperato viene inserito nei parametri di query.

Uso dei valori di connessione

Con l'espressione @connectionParameters('connectionParameterName') è possibile accedere ai valori immessi durante l'impostazione della connessione per il connettore personalizzato. Questa espressione consente di raccogliere informazioni dall'utente del connettore personalizzato, ad esempio l'autenticazione o i valori dell'URL host. È possibile usare questi valori dei parametri per creare gli URL e inserire altri valori di configurazione specifici della connessione.

I parametri di connessione configurati nel file apiProperties.json vengono usati per creare la finestra di dialogo di connessione compilata dall'utente quando crea una nuova connessione.

Quando si configura l'autenticazione in un connettore personalizzato, apiProperties viene modificato automaticamente per poter aggiungere le proprietà di autenticazione richieste. Se la definizione del connettore è stata scaricata con paconn, nel file apiProperties.json si vedrà che è stata aggiunta la logica seguente se è stata configurata l'autenticazione Chiave API.

"api_key": {
        "type": "securestring",
        "uiDefinition": {
          "displayName": "API Key",
          "description": "The API Key for your environment",
          "tooltip": "Provide your API Key",
          "constraints": {
            "tabIndex": 2,
            "clearText": false,
            "required": "true"
          }
        }

Di conseguenza, si vedrà il seguente campo di input quando viene creata una connessione.

È possibile aggiungere manualmente altri campi di input per raccogliere altri dati esclusivi per ogni utente del connettore personalizzato. Ad esempio, un campo comune da aggiungere è URL host che consente al connettore di usare più endpoint dell'API sottostante. L'esempio seguente mostra il file apiProperties.json in cui, oltre alla chiave API, si può inserire un URL host e un codice di fatturazione.

"properties": {
    "connectionParameters": {
      "hostUrl": {
        "type": "string",
        "uiDefinition": {
          "constraints": {
            "required": "true"
          },
          "description": "Specify your API URl e.g. https://test.contoso.com",
          "displayName": "API URL",
          "tooltip": "Specify your API URl e.g. https://test.contoso.com"
        }
      },
      "billingCode": {
        "type": "string",
        "uiDefinition": {
          "constraints": {
            "required": "true"
          },
          "description": "billing code",
          "displayName": "Billing Code",
          "tooltip": "Billing Code"
        }
      },
      "api_key": {
        "type": "securestring",
        "uiDefinition": {
          "displayName": "API Key",
          "description": "The API Key for your environment",
          "tooltip": "Provide your API Key",
          "constraints": {
            "tabIndex": 2,
            "clearText": false,
            "required": "true"
          }
        }
      }
    }

L'uso di questa configurazione comporta la visualizzazione della seguente finestra di dialogo di connessione.

A questo punto, è possibile usare le espressioni @connectionParameters('hostUrl') e @connectionParameters('billingCode') per includere i valori nelle configurazioni del modello di criteri.