Handbuch drucken  

 NVXWUL Web Utility Library


Library-App für Web-Autorisierung und Nachrichten.
Aktuelle Version: 2.0.19.0 ab Business Central 22.

Handbuch


Erstellungsdatum: 2024/04/29
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

Anhang

  • Versionshinweise
    Möchten Sie wissen, was sich in der App geändert hat...

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 URLGibt die Endpunkt URL.
ArtGibt 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 URLGibt den OAuth Token Endpunkt.
Client IDGibt die Client ID an.
Client SecretGibt das Client Secret.

Basic, Felder
UsernameGibt den Benutzernamen für die Basic Authentifizierung an.
PasswordGibt das Passwort für die Basic Authentifizierung an.

Bearer Token, Felder
Bearer Token Login UrlGibt die Bearer Token Login Url an.
Requires EncryptionGibt an, ob die Login Url die Anmeldedaten in verschlüsselter Form benötigt.
Bearer Token Json KeyGibt den Schlüssel des Json Wertes der Http Antwort des Bearer Token Logins an, welcher den Bearer Token beinhaltet.
UsernameGibt den Benutzernamen für die Bearer Token Authentifizierung an.
PasswordGibt das Passwort für die Bearer Token Authentifizierung an.

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

API-Schlüssel, Felder
API-Schlüssel Header NameGibt den Namen des Header der Anfrage der für den API-Schlüssel verwendet werden soll an.
API-SchlüsselGibt 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 FlowGibt an, welchen OAuth 2.0 Flow Sie nutzen wollen.
OAuth URLGibt den OAuth Token Endpunkt.
Client IDGibt die Client ID an.
Client SecretGibt das Client Secret.
ScopeGibt 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 TimeGibt den Zeitstempel des Datensatzes an.
MethodGibt die HTTP Request Methode an.
Target URLGibt die Ziel URL des Requests an.
PayloadGibt den gesendeten Payload des Requests an.
ResponseGibt den Payload des empfangenen Responses an.
Response Reason PhraseGibt den http-Ursachentext des empfangenen Responses an.
Response Is Success StatusGibt an, ob der Request akzeptiert oder abgelehnt wurde.
Response Status CodeGibt den http-Ursachenstatuscode an.

Funktionen

    CreateMessage

    Mit dieser Funktion wird eine neue WebMessage anhand der übergebenen Parameter erstellt.

    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

    Mit dieser Funktion wird ein HTTP Header einer bestehenden WebMessage hinzugefügt.

    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

    Mit dieser Funktion wird ein HTTP Header mit der konfigurierten Anmeldemethode einer bestehenden WebMessage hinzugefügt.

    Parameter

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

    SendMessage

    Mit dieser Funktion wird eine bestehende WebMessage an das definierte Webservice gesendet.

    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
NameGibt den Namen des Headers an.
ValueGibt 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
Test Webrequest erstellen


Not Found


The requested topic was not found on this server.

Docs  /  NVXWUL Web Utility Library  /  Anhang
Versionshinweise

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

NVXWUL 2.0.19.0

ab Business Central 22
2024/02/21

  • Erweiterungen

    • 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

  • Erweiterungen

    • Unterstützung für externe OAuth Authentifizierung hinzugefügt.

NVXWUL 2.0.17.0

ab Business Central 22
2024/02/01

  • Erweiterungen

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

NVXWUL 2.0.16.0

ab Business Central 22
2023/12/14

  • Erweiterungen

    • 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

  • Erweiterungen

    • Unterstützung für Webservices ohne Authentifizierung hinzufügt.

NVXWUL 2.0.13.0

ab Business Central 17
2023/04/20

  • Erweiterungen

    • MultiPart/Form-Data Hilfscodeunit hinzugefügt.

NVXWUL 2.0.12.0

ab Business Central 17
2023/04/12

  • Erweiterungen

    • 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

  • Erweiterungen

    • 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

  • Erweiterungen

    • 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

  • Erweiterungen

    • 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.

  • Erweiterungen

    • 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

  • Erweiterungen

    • 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

  • Erweiterungen

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

NVXWUL 2.0.0.0

ab Business Central 17

  • Erweiterungen

    • 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

  Handbuch drucken  
DE|EN Impressum