Vorherige

Nächste

Ausdrücke verwenden, um auf Laufzeitwerte zuzugreifen

Abgeschlossen

Mit Ausdrücken können Richtlinienvorlagenparameter ihre Werte aus Laufzeitdaten abrufen. Die Funktionen können über die Kopfzeile, die Abfrage und den Hauptteil der Anforderung und Antwort von der API auf Laufzeitdaten zugreifen und diese transformieren. Es ist auch üblich, Ausdrücke zu verwenden, um über die Verbindungseigenschaften des Konnektors auf Daten zuzugreifen. Zum Beispiel würde @connectionParameters('HostUrl') den für die Verbindungseigenschaft HostUrl konfigurierten Wert erhalten. Dies würde es einem Entwickler ermöglichen, die Service-URL als Teil der Verbindung zu ändern, ähnlich wie bei Test‑ oder Produktions-API-Szenarien. In dieser Lerneinheit werden einige häufig verwendete Ausdrücke behandelt, die mit Richtlinienvorlagen verwendet werden.

Grundlagen von Ausdrücken

Ausdrücke werden zur Laufzeit ausgewertet. Ein Ausdruck ist eine Folge von einer oder mehreren Funktionen, Operatoren oder expliziten Werten. Wenn Sie einen Ausdruck in einem Parameter definieren, wird dem Ausdruck das @-Zeichen (@) vorangestellt. Wenn Ihr Ausdruck zu einem numerischen Wert führt, bei dem eine Zeichenfolgeneingabe erwartet wird, können Sie die Notation mit geschweiften Klammern verwenden ({}), und es wird automatisch der numerische Wert in eine Zeichenfolge konvertiert.

Das folgende Beispiel zeigt, wie beide Notationen verwendet werden:

@{connectionParameters('HostPortNumber')}

Stellen Sie sicher, dass alles im Pfad nicht NULL ist, um sicherzustellen, dass Ihre Ausdrücke nicht aufgrund von NULL-Eigenschaften fehlschlagen. Das folgende Beispiel würde fehlschlagen, wenn die Zusammenfassung NULL war:

@body().summary.amount

Wenn Sie explizite Werte (Zeichenfolgenliterale) in Ihre Ausdrücke aufnehmen, verwenden Sie ein einfaches Anführungszeichen. Verwenden Sie keine doppelten Anführungszeichen, da dies zu Konflikten mit dem Markup führt, das um den Ausdruck verwendet wird.

Arbeiten Sie mit dem Antworttext

Sie können die Funktion body() für den Zugriff auf den Antworttext zur Laufzeit verwenden. Zum Beispiel gibt die Aktion Rechnung auflisten die folgenden Daten zurück:

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

In diesem Beispiel bezieht sich die Funktion body() auf die äußeren Klammern ({}) und hat eine Eigenschaftsrechnung, die ein Array ist.

Sie können einen Ausdruck erstellen, der auf das Array Rechnungen unter Verwendung der folgenden Logik verweist:

@body().invoices

Sie können auch einen Ausdruck erstellen, der auf die Rechnung ab dem ersten Element im Array mithilfe der folgenden Logik zugreift:

@body().invoices[0].invoiceid

Mit Kopfzeilenwerten arbeiten

Mit dem Ausdruck @headers('headerName') können Sie über die Kopfzeile auf Werte zugreifen. Sie können auch den Ausdruck @headers als Zielvorlagenparameter verwenden, wenn Sie die Richtlinienvorlage Kopfzeile von URL setzen nutzen. Mit diesem Ansatz können Sie einen Wert von einer URL abrufen und dann in der Kopfzeile festlegen. Beispielsweise könnte ein Konnektor diesen Ausdruck verwenden, um ein Zugriffstoken vom Dienst abzurufen und das Posten auf einer Seite zu ermöglichen. Das folgende Beispiel zeigt, wie die Konfiguration der Richtlinienvorlage aussehen könnte, um das Zugriffstoken für die Aktion Auf Seite posten zu erhalten.

Mit Abfragewerten arbeiten

Ähnlich wie beim Arbeiten mit Kopfzeilen können Sie den Ausdruck @queryParameters('queryParameterName') verwenden, um auf die Abfrageparameter der Anforderung zuzugreifen. Das folgende Beispiel ähnelt dem vorherigen Beispiel für Kopfzeilen. In diesem Beispiel wird das abgerufene Token jedoch in die Abfrageparameter eingefügt.

Mit Verbindungswerten arbeiten

Mit dem Ausdruck @connectionParameters('connectionParameterName') können Sie auf Werte zugreifen, die eingegeben wurden, als die Verbindung für den benutzerdefinierten Konnektor eingerichtet wurde. Mit diesem Ausdruck können Sie Informationen vom Benutzer Ihres benutzerdefinierten Konnektors erfassen, z. B. Authentifizierungs‑ oder Host-URL-Werte. Mit diesen Parameterwerten können Sie URLs erstellen und andere verbindungsspezifische Konfigurationswerte eingeben.

Verbindungsparameter, die in der Datei „apiProperties.json“ konfiguriert sind, werden zum Erstellen des Verbindungsdialogfelds verwendet, das der Benutzer beim Erstellen einer neuen Verbindung ausfüllt.

Wenn Sie die Authentifizierung auf einem benutzerdefinierten Konnektor konfigurieren, werden die apiProperties automatisch bearbeitet, damit Sie die erforderlichen Authentifizierungseigenschaften hinzufügen können. Wenn Sie Ihre Konnektordefinition mithilfe von paconn heruntergeladen haben und in der Datei „apiProperties.json“ nachsehen, wird bei der Konfiguration der API-Schlüssel-Authentifizierung die folgende Logik hinzugefügt.

"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"
          }
        }

Als Ergebnis sehen Sie das folgende Eingabefeld, wenn Sie eine Verbindung herstellen.

Sie können andere Eingabefelder manuell hinzufügen, um andere Daten zu erfassen, die für jeden Benutzer des benutzerdefinierten Konnektors eindeutig sind. Ein allgemeines Feld, das hinzugefügt werden muss, ist beispielsweise Host-URL. Damit können Sie dem Konnektor erlauben, mit mehreren Endpunkten der zugrunde liegenden API zu arbeiten. Das folgende Beispiel zeigt die Datei „apiProperties.json“, in der Sie zusätzlich zum API-Schlüssel die Eingabe einer Host-URL und eines Abrechnungscodes zulassen.

"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"
          }
        }
      }
    }

Wenn Sie diese Konfiguration verwenden, wird das folgende Verbindungsdialogfeld angezeigt.

Dann können Sie die Ausdrücke @connectionParameters('hostUrl') und @connectionParameters('billingCode') verwenden, um die Werte in Ihren Richtlinienvorlagenkonfigurationen zu verwenden.

Der Rest dieses Moduls zeigt Beispiele für die Verwendung von Ausdrücken, während weiter erläutert wird, wie Sie Richtlinienvorlagen verwenden können.

Weiter