Prozessentwicklung
Geschrieben vonOssi Galkin Vor über einer Woche aktualisiertTable of contentsAPI-Trigger
Ein API-Trigger wird verwendet, wenn Sie einen Prozess durch Aufrufen eines angegebenen HTTP-Endpunkts starten möchten oder, kurz gesagt, eine OpenAPI-Spezifikationsschnittstelle mit Frends bereitstellen möchten. Diese Trigger sind an vorhandene OpenAPI-Spezifikationsvorgänge gebunden und werden über die Frends API Management View erstellt.
Wenn Sie einen API-Trigger vom Prozess-Editor aus konfigurieren, müssen Sie auswählen, welche vorhandene Operation an diesen bestimmten Prozess gebunden ist.
API-Trigger-Parameter
Nach Auswahl desAPI-Betrieb,Die Systemsteuerung stellt eine Reihe von Parametern bereit.
DerHTTP-Methodeist auf den im Swagger-Vorgang angegebenen Wert festgelegt und kann nicht geändert werden. Gültige Werte sind GET, POST, PUT, DELETE, HEAD, OPTIONS und PATCH.
DerURLDer Pfad ist auf den im Swagger-Vorgang angegebenen Pfad beschränkt und kann nicht geändert werden. Pfadparameter sind zulässig. Wenn die Pfadparameter vom Typ Integer oder Boolean sind, wird der Pfad auf diese Typen beschränkt. Dadurch können Endpunkte wie /api/pet/{id} und /api/pet/getStatus gleichzeitig ohne Kollision aktiv sein, wenn der Parameter {id} vom Typ Integer ist. Es wäre jedoch nicht möglich, /api/pet/{name} und /api/pet/getStatus gleichzeitig zu haben, wenn der Parameter {name} vom Typ String wäre.
DerErlaubte Protokolledefiniert, ob Anfragen mit HTTP, HTTPS oder beiden akzeptiert werden. Wenn eine Anfrage mit einem nicht zulässigen Protokoll gestellt wird, lautet die Antwort Verboten (403).
Die API-Trigger können vier verschiedene Arten vonAuthentifizierung:
Keine - Keine Authentifizierung überhaupt
Basic – Authentifizieren Sie mit der HTTP-Basisauthentifizierung. Dadurch wird der Benutzer entweder gegenüber dem Active Directory oder den lokalen Benutzern authentifiziert. Welche davon verwendet wird, hängt vom Benutzer des Frends Agent-Dienstes ab. Wenn der Agent ein lokales Benutzerkonto verwendet, werden Benutzer gegenüber den Benutzern des lokalen Computers authentifiziert. Wenn der Agent ein AD-Benutzerkonto verwendet, werden Benutzer gegenüber den AD-Benutzern authentifiziert. Benutzername und Kennwort müssen mit UTF-8 codiert werden, bevor sie für den Basisauthentifizierungsheader in Base64 konvertiert werden.
Zertifikat - Verwenden Sie zur Authentifizierung ein Client-Zertifikat. Dies erfordert, dass das Client-Zertifikat für den Frends Agent-Benutzer auf dem Agent-Computer gültig ist. Außerdem muss der Aussteller des Zertifikats im Zertifikatspeicher „Client Authentication Issuers“ des Agent-Benutzers zu finden sein.
API-Schlüssel - Authentifizieren Sie sich mit einem API-Schlüssel zusammen mit einem Regelsatz, um zu bestimmen, ob der Client Zugriff auf eine URL hat. Weitere Informationen finden Sie unterAPI-Schlüssel.
OAuth2 - Authentisierung mit OAuth 2.0 Bearer Tokens vonregistrierte OAuth-Anwendungenum Zugriff auf die API zu erhalten. Sie müssen eineAPI-Zugriffsrichtlinieum den Zugriff zu ermöglichen.
Wenn Sie Bereiche zur Steuerung des Zugriffs auf eine API verwenden, müssen Sie die erforderlichen Bereiche in der Swagger-Definition angeben. Bitte beachten Sie, dass Aufrufe durchgehen, wenn Sie einer API-Trigger-Operation viele Bereiche zuweisen, wenn das OAuth-Tokenbeliebigder angegebenen Bereiche.
Wir empfehlen dringend, nur die Authentifizierung über HTTPS zu verwenden.
EinAnfragen von diesen Ursprüngen zulassen (CORS)Flag wird verwendet, wenn es erforderlich ist, einer bestimmten Seite das Auslösen eines Prozesses zu erlauben, d. h. Cross-Origin Resource Sharing (CORS) zu aktivieren. Aktivieren Sie das Kontrollkästchen „Anfragen von diesen Ursprüngen zulassen“ und definieren Sie die zulässigen Ursprünge im Textfeld. Das Zeichen * erlaubt Aufrufe von allen Ursprüngen. Mehrere Ursprünge können durch einen Doppelpunkt (,) oder ein Semikolon (;) getrennt angegeben werden.
Hinweis: Wenn der Anruf nicht vom Standardport kommt, muss er im Ursprung enthalten sein. Der Ursprung, der den Anruf tätigt, muss auch CORS unterstützen.
Zwischenrendite
Ein Prozess kann eine Antwort an den Benutzer zurückgeben, bevor der Prozess beendet ist. Diese Funktion wird aktiviert, indem dem Prozess ein Zwischenelement zur Rückgabe hinzugefügt wird. Wenn dieses Element ausgeführt wird, erhält der Anrufer eine HTTP-Antwort vom Prozess. Dies kann beispielsweise verwendet werden, wenn ein lang laufender Prozess aufgerufen wird und der Anrufer benachrichtigt werden soll, dass die lang laufende Aufgabe gestartet wurde.
HTTP-Antwortformatierung
Der API-Trigger gibt das Ergebnis des ausgeführten Prozesses als HTTP-Antwort zurück. Die Antwort variiert je nach den folgenden Bedingungen. Wenn das Ergebnis des Prozesses eine Zeichenfolge ist, wird die Zeichenfolge als Hauptteil der Antwort festgelegt. Wenn es sich um ein Objekt handelt, wird es je nach ACCEPT-Header der Anforderung oder standardmäßig als JSON entweder als JSON oder XML zurückgegeben. Beispielsweise würde ACCEPT: application/xml eine XML-Antwort erzeugen, während ACCEPT: application/json eine JSON-Antwort erzeugen würde.
Wenn das Ergebnis ein Objekt mit den Eigenschaften HttpStatusCode und Content ist, wird das Ergebnis entsprechend einer Antwort zugeordnet:
HttpStatusCode: Antwortstatuscode (int)
Inhalt: Der Hauptteil der Antwort (Zeichenfolge)
ContentEncoding: Die Kodierung für den Textkörper, z. B. utf-8 (Zeichenfolge)
ContentType: ContentType-Headerwert, z. B. application/xml oder application/json (Zeichenfolge)
HttpHeaders: Antwortheader (KeyValuePair[])
HTTP-Antwort
Die Elemente return, Intermediate return und Throw des Prozesselements bieten alle die Option, eine vordefinierte HTTP-Antwort zu generieren. Siehe HTTP-Antwortergebnisse imParameter-Editor.
Verweisen auf Triggerparameterwerte
#trigger.data.httpBody
Der Hauptteil der HTTP-Anfrage im String-Format#trigger.data.httpClientIp
IP des Clients als String#trigger.data.httpCookies
Mit der Anfrage verknüpfte Cookies als Wörterbuch#trigger.data.httpMethod
HTTP-Methodentyp (z. B. GET, POST usw.)#trigger.data.httpRequestUri
Anforderungs-URI (z. B.https://myfrendsagent.example.com:9998/api/MyApi/execute?mode=1).#trigger.data.Benutzername
Der dem Anrufer zugeordnete Benutzername. Wird nur festgelegt, wenn Authentifizierung verwendet wird. Für die verschiedenen Authentifizierungstypen werden die folgenden Werte übergeben:
API-Schlüssel: Der Name des API-Schlüssels
Grundlegende Authentifizierung: Der angegebene Benutzername
Zertifikat: Das Feld „SubjectName.Name“ des Zertifikats
OAuth2: Der Wert aus dem Namensanspruch#trigger.claimsprincipal(ab 5.1.1)
DerHauptforderungeninitialisiert aus dem Zugriffstoken. Nur verfügbar bei Verwendung von OAuth2. Sie können auf die Claims-Sammlung zugreifen mit#trigger.claimsprincipal.Ansprücheoder prüfen Sie die Existenz einzelner Ansprüche mit#trigger.claimsprincipal.HasClaim("foo"). Bei der Verwendung von Rollenansprüchen, z. B. von Azure AD, können Sie überprüfen, ob das Token die Rolle hatte über#trigger.claimsprincipal.IsInRole()#trigger.daten.body
Enthält alles, was im Anforderungstext übergeben wird. Wenn der Text ein JSON-Objekt enthält, sind die Eigenschaften mit Punktnotation zugänglich. Wenn beispielsweise die JSON-Zeichenfolge{ "Haus": { "Fenster": 4}}im Body übergeben wird, wäre es möglich, auf die Eigenschaft "window" zuzugreifen mit#trigger.daten.körper.haus.fenster#trigger.daten.pfad
Enthält Pfadparameter. Automatisches Casting wird versucht, wenn die Parameter in der Swagger-Spezifikation definiert wurden. Pfadparameter sind obligatorisch und daher immer ausgefüllt.
Wenn der Pfad /user/{id} konfiguriert wurde und der Parameter id vom Typ int ist, dann ist die Referenz#trigger.data.path.idkann sofort für ganzzahlige Vergleiche verwendet werden (zum Beispiel in einem Entscheidungsausdruck#trigger.data.path.id>3wäre verwendbar)#trigger.daten.abfrage
Enthält Abfrageparameter. Automatisches Casting wird versucht, wenn die Parameter in der Swagger-Spezifikation definiert wurden. Wenn der Parameter einen Standardwert hat und die Anforderung den Parameter nicht enthält, wird der Standardwert an den Prozess übergeben.
In der Swagger-Spezifikation definierte Abfrageparameter werden immer im Trigger ausgefüllt, auch wenn kein Wert angegeben ist.#trigger.daten.header
Enthält Header-Parameter. Automatisches Casting wird versucht, wenn die Parameter in der Swagger-Spezifikation definiert wurden. Wenn der Parameter einen Standardwert hat und die Anforderung den Parameter nicht enthält, wird der Standardwert an den Prozess übergeben.
In der Swagger-Spezifikation definierte Header-Parameter werden im Trigger immer aufgefüllt, auch wenn kein Wert angegeben ist.
Sie können versuchen, von einer beliebigen Referenz aus auf eine optionale Referenz zuzugreifen (z. B.#trigger.data.httpHeader.foo) und wenn es gefunden wird, wird der Wert zurückgegeben, und wenn nicht, wird der Wert auf null gesetzt.
Automatisches Casting von Parameterwerten per Definition
Swagger-Parameter enthalten normalerweise eine Typdefinition. Parameter vom Typ Integer, Number oder Boolean werden in ihren entsprechenden .NET-Typ (Int, Long, Float, Double oder Boolean) umgewandelt. Bei Parametern vom Typ Array verwendet das Array das im Swagger-Parameter definierte Trennzeichen und der Array-Inhalt wird wiederum entsprechend ihrer Typen umgewandelt. Ein Array-Parameter mit einem CSV-Trennzeichen und dem Inhaltstyp Integer hat den Aufrufinhalt „1,2,3,4,5“ und ist als JArray mit Integer-Werten zugänglich.
Der nächste Artikel istEinführung in HTTP-Trigger
Verwandte ArtikelErstellen einer Frends-APIAPI-TriggerHTTP-TriggerAPI-VerwaltungEinführung in HTTP-Trigger