NVXWUL Web Utility Library

Library-App für Web-Autorisierung und Nachrichten.

Aktuelle Version: 2.0.21.0 ab Business Central 22.

Handbuch

Erstellungsdatum: 2024/11/22
Die aktuelle Version dieses Handbuchs finden Sie unter:

https://www.navax.app/help.php?AppID=NVXWUL&L=de

☰ Inhaltsverzeichnis

Allgemein

App Web Utility Library
Diese App soll es erleichtern Requests an REST Webservices zu senden, welche eine Authentifizierung erfordern...

Aufgaben

Arbeiten mit der App
MultiPart/Form-Data Helper
Für den komplexen Content-Type MultiPart/Form-Data gibt es eine Hilfs-Codeunit zum Aufbau eines solchen Bodys...
Test Webrequest erstellen
Auf dieser Seite können Sie von Business Central ausgehende Anfragen testen...
Aufbewahrungsrichtlinie
Es wurde eine eigene Aufbewahrungsrichtlinie für die Web Messages bereit gestellt...

Anhang

Versionshinweise

Docs / NVXWUL Web Utility Library / Allgemein
General

Diese App soll es erleichtern Requests an REST Webservices zu senden, welche eine Authentifizierung erfordern. Diese App unterstützt für REST Requests die Authentifizierungsarten OAuth2, Basic und Bearer Token.

Docs / NVXWUL Web Utility Library / Aufgaben
Arbeiten mit der App

Web Authentifizierung

In dieser Tabelle werden benötigte Endpunkte und deren Authentifizierungsart hinterlegt.

Authentifizierung Felder
Endpunkt URL	Gibt die Endpunkt URL.
Art	Gibt die Authentifizierungsart an.

OAuth, Felder
Mit dieser Authentifizierungsart können Token von Autorisierungsservern der Microsoft Identy Platform abgerufen werden. Als OAuth2 Flow wird die Option "Client Credentials unterstützt.
OAuth URL	Gibt den OAuth Token Endpunkt.
Client ID	Gibt die Client ID an.
Client Secret	Gibt das Client Secret.

Basic, Felder
Username	Gibt den Benutzernamen für die Basic Authentifizierung an.
Password	Gibt das Passwort für die Basic Authentifizierung an.

Bearer Token, Felder
Bearer Token Login Url	Gibt die Bearer Token Login Url an.
Requires Encryption	Gibt an, ob die Login Url die Anmeldedaten in verschlüsselter Form benötigt.
Bearer Token Json Key	Gibt den Schlüssel des Json Wertes der Http Antwort des Bearer Token Logins an, welcher den Bearer Token beinhaltet.
Username	Gibt den Benutzernamen für die Bearer Token Authentifizierung an.
Password	Gibt das Passwort für die Bearer Token Authentifizierung an.

Verschlüsselung, Felder
Verschlüsselungsalgorithmus	Gibt an, welcher Verschlüsselungsalgorithmus verwendet werden soll.
Kryptografischer Schlüssel	Gibt den Schlüssel einer schlüsselbasierten kryptografischen Funktion an.

API-Schlüssel, Felder
API-Schlüssel Header Name	Gibt den Namen des Header der Anfrage der für den API-Schlüssel verwendet werden soll an.
API-Schlüssel	Gibt den API-Schlüssel an.

OAuth-extern, Felder
Mit dieser Authentifizierungsart können Token von Autorisierungsservern ausßerhalb der Microsoft Identy Platform abgerufen werden. Als OAuth2 Flow wird die Option "Client Credentials unterstützt.
OAuth2 Flow	Gibt an, welchen OAuth 2.0 Flow Sie nutzen wollen.
OAuth URL	Gibt den OAuth Token Endpunkt.
Client ID	Gibt die Client ID an.
Client Secret	Gibt das Client Secret.
Scope	Gibt den Bereich für den Token an. Ist dies leer so wird * verwendet.

Aktionen

Anmeldeinformationen und Verbindung testen
Sendet eine HTTP GET Anfrage mit den angegebenen Anmeldeinformationen an den Endpunkt, um zu prüfen, ob der Endpunkt erreicht werden kann und ob die Anmeldeinformationen korrekt sind. Wenn die Bearer Token oder OAuth2 Authentifizierungsart verwendet wird, wird eine weitere Anfrage an die Token Url mit den gegebenen Anmeldeinformationen gesendet um zu überprüfen, ob diese korrekt sind und einen Authentifizierungstoken zurückliefern. Die Antwort des getesteten Webservices wird in einem Dialog ausgegeben.
Test Webrequest erstellen
Erstellt einen Test Webrequest mit dieser Anmeldeinformation.

Web Messages

Mit dieser Tabelle können HTTP Requests an die, in der Tabelle Web Authentifizierung, hinterlegten Endpunkte erstellt und gesendet werden. Die gesendeten Requests werden hier einen Monat lang gespeichert, dies muss allerdings in den Aufbewahrungsrichtlinien für die Tabelle mit der ID 61483 aktiviert werden.

Felder
Entry No.	Gibt die Nummer des Datensatzes an.
Date and Time	Gibt den Zeitstempel des Datensatzes an.
Method	Gibt die HTTP Request Methode an.
Target URL	Gibt die Ziel URL des Requests an.
Payload	Gibt den gesendeten Payload des Requests an.
Response	Gibt den Payload des empfangenen Responses an.
Response Reason Phrase	Gibt den http-Ursachentext des empfangenen Responses an.
Response Is Success Status	Gibt an, ob der Request akzeptiert oder abgelehnt wurde.
Response Status Code	Gibt den http-Ursachenstatuscode an.

Funktionen

CreateMessage

Parameter

RequestType Enum "Http Request Type" -> die HTTP Methode mit der der Request abgeschickt werden soll
TargetURL Text[250] -> die URL an welche die erstellte Message gesendet werden soll
RequestContent Text -> der Request Body

AddWebMessageHeader

Parameter

HeaderType Enum "WULWebMessageHeaderTypeNVX" -> die Art des HTTP Headers (Request oder Content Header)
Name Text -> der Name des Headers
Value Text -> der Wert des Headers

AddWebMessageAuthorization

Parameter

HeaderType Enum "WULWebMessageHeaderTypeNVX" -> die Art des HTTP Headers (Request oder Content Header)
WebAuthorization Record "WULWebAuthorizationNVX" -> die konfigurierte Anmeldemethode

SendMessage

Parameter

var ResponseMessage: HttpResponseMessage -> die Antwort des Webservices welcher den Request erhalten hat

procedure ExecuteWebService(Payload: Text; WebAuthorization: Record WULWebAuthorizationNVX; EndpointURL: Text)
var
    WebMessage: Record WULWebMessageNVX;
    ResponseMessage: HttpResponseMessage;
    BodyContent: Text;
    ResponseText: Text;
begin
    WebMessage.CreateMessage("Http Request Type"::POST, EndpointURL, BodyContent);
    WebMessage.AddWebMessageHeader(WULWebMessageHeaderTypeNVX::"Content Header", 'Content-Type', 'application/json');
    WebMessage.AddWebMessageAuthorization(WULWebMessageHeaderTypeNVX::"Request Header", WebAuthorization);
    Commit();
    WebMessage.SendMessage(ResponseMessage);
    Commit();
    ResponseText := WebMessage.GetResponse();
end;

Web Message Headers

In dieser Tabelle werden die mitgesendeten HTTP Header der zugehörigen Web Message Einträge gespeichert.

Felder
Name	Gibt den Namen des Headers an.
Value	Gibt den Wert des Headers an.

MultiPart/Form-Data Helper

Für den komplexen Content-Type MultiPart/Form-Data gibt es eine Hilfs-Codeunit zum Aufbau eines solchen Bodys. MultiPart/Form-Data Helper

Docs / NVXWUL Web Utility Library / Aufgaben
MultiPart/Form-Data Helper

Für den komplexen Content-Type MultiPart/Form-Data gibt es eine Hilfs-Codeunit zum Aufbau eines solchen Bodys.

Allgemein

Ein MultiPart/Form-Data Body kann verwendet werden, um eine oder mehrere Dateien als als auch Felder zu senden. Dieser Body hat mehrere Parameter mit Namen und Inhalt. Anders als ein normaler JSON oder XML Body, können hier Dateien als Byte-Stream mitübergeben werden. Swagger Spezification multipart/form-data

Helper Codeunit

WULMultiPartFormDataHelperNVX

Methoden

InitBody

Bereite die Codeunit Instanz für einen neuen body vor. Die boundary wird auf einen Standardwert gesetzt wenn sie zuvor nicht gesetzt wurde.

procedute InitBody()

AddKey

füge einen Key der Art Text zu einem MultiPart/Form-Data Body hinzu.

procedure AddKey(Name: Text; Value: Text)

AddFile

Füge einen Key der Art Datei zu einem MultiPart/Form-Data Body hinzu.

procedure AddFile(KeyName: Text; FileName: Text; FileInStream: InStream)

FinishBody

Schließe den vorbereiteten Body ab.

procedure FinishBody()

SetBoundary

Setze einen benutzerdefinierten Boundary Text. Das muss gesetzt werden bevor der Body initialisiert wurde.

procedure SetBoundary(NewBoundary: Text)

GetBoundary

Lese den gesetzten Boundary.

procedure GetBoundary(): Text

GetDefaultBoundary

Lese den Standard Boundary Text der Codeunit.

procedure GetDefaultBoundary(): Text

GetMultiformData

Lese den vorbereiteten Body nachdem er abgeschlossen wurde.

procedure GetMultiformData(var _TempBlob: Codeunit "Temp Blob")

GetMultiPartFormDataContentTypeHTTPHeader

Lese den HTTP Header Text mit dem eingestellten Boundary Wert für den HTTP Request.

procedure GetMultiPartFormDataContentTypeHTTPHeader() MultiPartFormDataContentTypeHTTPHeader: Text

Beispiel

Das Beispiel erstellt einen Multipart/Form-Data Body mit einem Key mit dem namen "keyvalue1" mit dem wert "myvalue" und einem 2ten key mit dem namen "example_file" mit Dateinamen "examle.txt" und einem Dateiinhalt.

procedure Example(WebAuthorization: Record WULWebAuthorizationNVX; URL: Text[250]; ExampleFileInstream: InStream) ResponseText: Text;
var
    TempBlob: Codeunit "Temp Blob";
    MultiformDataHelper: Codeunit WULMultiPartFormDataHelperNVX;
    WebMessage: Record WULWebMessageNVX;
    ResponseMessage: HttpResponseMessage;
    MultiPartFormDataInStream: InStream;
begin
    Commit();

    MultiformDataHelper.InitBody();
    MultiformDataHelper.AddKey('keyvalue1', 'myvalue');
    MultiformDataHelper.AddFile('example_file', 'example.txt', ExampleFileInstream);
    MultiformDataHelper.FinishBody();

    MultiformDataHelper.GetMultiformData(TempBlob);
    TempBlob.CreateInStream(MultiPartFormDataInStream);
    WebMessage.CreateMessage(Enum::"Http Request Type"::POST, URL, MultiPartFormDataInStream);

    WebMessage.AddWebMessageHeader(Enum::WULWebMessageHeaderTypeNVX::"Request Header", 'Accept', 'application/json');
    WebMessage.AddWebMessageHeader(Enum::WULWebMessageHeaderTypeNVX::"Content Header", 'Content-Type', MultiformDataHelper.GetMultiPartFormDataContentTypeHTTPHeader());
    WebMessage.AddWebMessageAuthorization(WULWebMessageHeaderTypeNVX::"Request Header", WebAuthorization);

    Commit();
    WebMessage.SendMessage(ResponseMessage);
    Commit();
    ResponseText := WebMessage.GetResponse();
end;

Docs / NVXWUL Web Utility Library / Aufgaben
Neue Web Message testen

Auf dieser Seite können Sie von Business Central ausgehende Anfragen testen. Hier können Sie versuchen, benutzerdefinierte Anfragen mit definierbarem Text, Header, Methode und Autorisierung zu senden.

Achtung

Dies ist ein Debugging-Tool für Entwickler und sollte mit Vorsicht verwendet werden. Sie können mit der richtigen Autorisierung an Live-Endpunkte senden und externe Systeme stören.

Ziel, Felder
Endpunkt	Gibt den Endpunkt an, wohin die Anfrage gesendet werden soll.
Endpunkt für Anmeldeinformation	Gibt die Anmeldeinformation an, welcher für diese Anfrage verwendet werden soll.
HTTP Request Art	Gibt an, welche HTTP Request Art verwendet werden soll.

Payload, Felder
Payload	Gibt den Paylod an, welcher an den Endpunkt gesendet werden soll.

Antwort, Felder
Response Ursachentext	Gibt den http-Ursachentext des empfangenen Responses an.
Response ist Erfolg Status	Gibt an, ob der Request akzeptiert oder abgelehnt wurde.
Response Status Code	Gibt den http-Ursachenstatuscode an.

Raw Response, Felder
Raw Response	Gibt die letzte Antwort an, welcher vom Endpunkt erhalten wurde.

Aktionen

Senden
Sendet die Anfrage an den Endpunkt.
Laden
Laden Sie eine vorherige Web Message, um zu versuchen, sie erneut zu senden. Geheime Werte werden weggelassen. Anmeldeinformationen können nicht übernommen werden.
Headers
Gibt die Header an, die mit dieser Anfrage verwendet werden sollen.

Docs / NVXWUL Web Utility Library / Aufgaben
Aufbewahrungsrichtlinie

Es wurde eine eigene Aufbewahrungsrichtlinie für die Web Messages bereit gestellt. Der vorgeschlagene Wert für die Aufbewahrungsdauer ist 1 Monat aber er kann nach belieben angepasst werden.

Docs / NVXWUL Web Utility Library / Anhang
Versionshinweise

Möchten Sie wissen, was sich in der Erweiterung geändert hat?
Nachfolgend finden Sie eine Übersicht über die neuen Funktionen und Änderungen, die in den Updates vorgenommen wurden. Build-Übersicht in DevOps

NVXWUL 2.0.21.0

ab Business Central 22
2024/06/27

Fehlerbehebungen
- Die Aufbewahrungsrichtlinie konnte fehlen.

NVXWUL 2.0.20.0

ab Business Central 22
2024/06/04

Verbesserungen
- Neue Prozedure ResendWebRequest hinzugefügt.

NVXWUL 2.0.19.0

ab Business Central 22
2024/02/21

Verbesserungen
- TargetUrl Feld in WebMessage Tabelle wurde auf 2048 Zeichen Kapazität vergrößert.

NVXWUL 2.0.18.0

ab Business Central 22
2024/02/21

Verbesserungen
- Unterstützung für externe OAuth Authentifizierung hinzugefügt.

NVXWUL 2.0.17.0

ab Business Central 22
2024/02/01

Verbesserungen
- Fehler beim Löschen der WebMessage [Funktion CleanUpWebMessagesOnDeleteLinkedRecord()] wurde behoben.

NVXWUL 2.0.16.0

ab Business Central 22
2023/12/14

Verbesserungen
- Eine Seite um Web Messages zu erstellen und bearbeiten und direkt aus Business Central zu senden.

NVXWUL 2.0.15.0

ab Business Central 22
2023/10/19

Änderungen
- Anpassungen für BC 23 Kompatibilität.

NVXWUL 2.0.14.0

ab Business Central 17
2023/05/06

Verbesserungen
- Unterstützung für Webservices ohne Authentifizierung hinzufügt.

NVXWUL 2.0.13.0

ab Business Central 17
2023/04/20

Verbesserungen
- MultiPart/Form-Data Hilfscodeunit hinzugefügt.

NVXWUL 2.0.12.0

ab Business Central 17
2023/04/12

Verbesserungen
- Funktion AddWebMessageAuthorization in WebMessage hinzufügt für das einfache hinzufügen von Anmeldedaten in den Header.
- API Key Anmeldemethode hinzugefügt.

NVXWUL 2.0.11.0

ab Business Central 17
2023/02/16

Fehlerbehebungen
- Fehler beim hinzufügen von mehr als zwei Web Message Headern wurde behoben.

NVXWUL 2.0.10.0

ab Business Central 17
2022/05/25

Verbesserungen
- Web Message Seite wird absteigend sortiert geöffnet.

NVXWUL 2.0.9.0

ab Business Central 17
2022/04/22

Fehlerbehebungen
- Fehler bei den Secret Values der Request Headers wurde behoben.

NVXWUL 2.0.8.0

ab Business Central 17
2022/04/22

Verbesserungen
- Felder und Funktionen für das Verschlüsseln von den Anmeldeinformationen beim Absenden von Anfragen gegen ein Webservice wurde hinzugefügt.

NVXWUL 2.0.7.0

ab Business Central 17
2022/04/16

Verbesserungen
- Der Tooltip der Aktion "Anmeldeinformationen und Verbindung testen" wurde erweitert. Das Enum WULSecretHeaderValuesNVX wurde hinzugefügt, um den Wert benutzerdefinierter HTTP Header bei Bedarf im Web-Client zu verdecken.

NVXWUL 2.0.6.0

ab Business Central 17
2022/03/31

Fehlerbehebungen
- Fehler beim erstmaligen Absenden einer Web Message innerhalb der Try-Function wurde behoben.
Verbesserungen
- Es wurde die Aktion "Anmeldeinformationen und Verbindung testen" auf der Seite "Web Authentifizierung" hinzugefügt

NVXWUL 2.0.5.0

ab Business Central 17
2022/02/23

Fehlerbehebungen
- Deadlock Fehler bei der Isolierten Datenspeicherung bei mehreren Sessions wurde behoben.

NVXWUL 2.0.4.0

ab Business Central 17
2022/02/19

Verbesserungen
- HTTP Request Fehler wird bei nicht erreichbarem Host unterdrückt.

NVXWUL 2.0.3.0

ab Business Central 17

Fehlerbehebungen
- Behebung fehlerhafter OAuth2 Token Erstellung.

NVXWUL 2.0.2.0

ab Business Central 17

Fehlerbehebungen
- Während der Upgrade Routine wurden identische Upgrade Tags mehrfach gesetzt, was zu einem Fehler bei Installation der App führte.

NVXWUL 2.0.1.0

ab Business Central 17

Verbesserungen
- Webservices und API's, welche Bearer Token Authentifizierung erfordern, können konsumiert werden.

NVXWUL 2.0.0.0

ab Business Central 17

Verbesserungen
- Web Messages können nun bei Erstellung mit einem Datensatz über dessen System Id und Tabellennr. verknüpft werden.

NVXWUL 1.0.0.0

ab Business Central 17

Ursprungsversion

NVXWUL Web Utility Library

Handbuch

☰ Inhaltsverzeichnis

Allgemein

Aufgaben

Anhang

Docs / NVXWUL Web Utility Library / AllgemeinGeneral

Docs / NVXWUL Web Utility Library / AufgabenArbeiten mit der App

Web Authentifizierung

Authentifizierung Felder

OAuth, Felder

Basic, Felder

Bearer Token, Felder

Verschlüsselung, Felder

API-Schlüssel, Felder

OAuth-extern, Felder

Aktionen

Anmeldeinformationen und Verbindung testen

Test Webrequest erstellen

Web Messages

Felder

Funktionen

CreateMessage

Parameter

AddWebMessageHeader

Parameter

AddWebMessageAuthorization

Parameter

SendMessage

Parameter

Web Message Headers

Felder

MultiPart/Form-Data Helper

Docs / NVXWUL Web Utility Library / AufgabenMultiPart/Form-Data Helper

Allgemein

Helper Codeunit

Methoden

InitBody

AddKey

AddFile

FinishBody

SetBoundary

GetBoundary

GetDefaultBoundary

GetMultiformData

GetMultiPartFormDataContentTypeHTTPHeader

Beispiel

Docs / NVXWUL Web Utility Library / AufgabenNeue Web Message testen

Ziel, Felder

Payload, Felder

Antwort, Felder

Raw Response, Felder

Aktionen

Senden

Laden

Headers

Docs / NVXWUL Web Utility Library / AufgabenAufbewahrungsrichtlinie

Docs / NVXWUL Web Utility Library / AnhangVersionshinweise

NVXWUL 2.0.21.0

Fehlerbehebungen

NVXWUL 2.0.20.0

Verbesserungen

NVXWUL 2.0.19.0

Verbesserungen

NVXWUL 2.0.18.0

Verbesserungen

NVXWUL 2.0.17.0

Verbesserungen

NVXWUL 2.0.16.0

Verbesserungen

NVXWUL 2.0.15.0

Änderungen

NVXWUL 2.0.14.0

Verbesserungen

NVXWUL 2.0.13.0

Verbesserungen

NVXWUL 2.0.12.0

Verbesserungen

NVXWUL 2.0.11.0

Fehlerbehebungen

Docs / NVXWUL Web Utility Library / Allgemein
General

Docs / NVXWUL Web Utility Library / Aufgaben
Arbeiten mit der App

Docs / NVXWUL Web Utility Library / Aufgaben
MultiPart/Form-Data Helper

Docs / NVXWUL Web Utility Library / Aufgaben
Neue Web Message testen

Docs / NVXWUL Web Utility Library / Aufgaben
Aufbewahrungsrichtlinie

Docs / NVXWUL Web Utility Library / Anhang
Versionshinweise