Web Service in 4D abonnieren

Mit 4D können Sie Web Services abonnieren, d.h. Sie können sie aufrufen und innerhalb Ihrer eigenen Anwendung nutzen. 

Über Web Services können Sie mühelos verschiedene Funktionalitäten in Ihrer Software hinzufügen, z.B. Zugriff auf Lagerhaltung, Verfolgung von Paketzustellung, Ausführung komplexer Berechnungen. Sehr viele Dienste werden im Internet über Web Services angeboten. 

Sie können auch Web Services abonnieren, die Sie selbst in anderen Anwendungen veröffentlicht haben. So können verschiedene 4D Datenbanken miteinander kommunizieren.

Jede mit 4D erstellte Datenbank kann einen Web Service abonnieren, sie muss lediglich an ein Netzwerk bzw. an das Internet angeschlossen sein.

Um einen Web Service aufrufen zu können, müssen Sie nachfolgende Schritte ausführen:

1. Machen Sie die URL des Web Service ausfindig, den Sie abonnieren wollen.
   Dazu können Sie Web Sites einsetzen, die im Internet veröffentlichte Web Services auflisten, z.B. www.xmethods.net oder Verzeichnisse wie UDDI. In den meisten Fällen müssen Sie die URL der WSDL Datei für den Web Service kennen.
   Hinweis: kann Web Services verwenden, die im RPC oder DOC Modus veröffentlicht werden (siehe Kompatibilität von RPC, DOC und komplexen Typen)
2. Über den Assistenten für Web Services analysieren Sie den Inhalt der WSDL des betreffenden Web Service und generieren die dazugehörige Proxy Methode. Das ist die lokale Projektmethode, die den Web Service abfragt und die zurückgegebenen Werte herausfindet. Dieser Schritt wird im Absatz unten beschrieben.
   Hinweise:
   
   • Im Assistenten für Web Services können Sie auch eine Proxy Methode ohne WSDL Datei erstellen. Dazu geben Sie einfach die betreffenden Parameter manuell ein.
   • Sie können eine Proxy Methode auch im Methodeneditor erstellen, ohne den Assistenten für Web Services zu verwenden (für fortgeschrittene Anwender).
3. Im Code Ihrer 4D Datenbank rufen Sie die Proxy Methode, so oft wie benötigt, durch Übergeben geeigneter Parameter auf.
   Dieser Schritt wird im Absatz Proxy Methode aufrufen.

Die Proxy Methode verwaltet die Verbindung zum Web Service:

Die 4D Anwendung verwendet zum Abonnieren eines Web Service den Assistenten für Web Services. Er führt automatisch folgende Schritte aus:

• Analyse (parsen) der WSDL Dateien für die zu verwendenden Web Services
• Definition der Parameter für die zu erstellenden Proxy Methoden
• Erstellen der Proxy Methoden

Um den Assistenten für Web Services zu öffnen, wählen Sie im Menü Design>Web Services Assistent. Auf dem Bildschirm erscheint folgendes Dialogfenster:

Hinweis: Das Fenster erscheint auch, wenn Sie im Explorer auf der Seite Methoden am unteren Rand auf das Menü Optionen klicken. Weitere Informationen dazu finden Sie im Abschnitt ).

Es ist in drei Bereiche gegliedert:

• Im Bereich “URL” geben Sie die URL der WSDL Datei für den gewählten Web Service ein oder wählen eine URL aus. Dieser Bereich ist eine Combo Box, welche die zuvor eingegebenen Werte in Form einer DropDown-Liste speichert.
• Der Hauptbereich zeigt das Ergebnis aus der Analyse des Inhalts in der WSDL Datei: Namen der Dienste und veröffentlichte Methoden.
• Der untere Bereich ist standardmäßig ausgeblendet. Über das Icon Erweitert können Sie ihn aufklappen. Er zeigt die Parameter zur Methode, die im Hauptbereich ausgewählt wurde.

Die Schaltfläche Erkennen durchsucht die angegebene WSDL Datei und setzt die Informationen in den darunterliegenden Bereich ein.
Die Schaltfläche Öffnen zeigt einen Standard-Öffnen Dialog, um eine lokal gespeicherte WSDL auszuwählen. Der Zugriffspfad wird dann im Bereich URL angezeigt. Er beginnt mit “Datei://”. Sie können ihn auch manuell eingeben.
Die Schaltfläche Erzeugen generiert die Proxy Methode, die zum gewählten Web Service gehört.
Die Schaltfläche Schließen schließt das Dialogfenster wieder.

Die Hauptaufgabe des Assistenten für Web Services ist, eine WSDL Datei zu analysieren und die entsprechende(n) Proxy Methode(n) zu generieren. Diese Operation ist vollkommen automatisch und erfordert vom Benutzer weder Programmierung noch besonderes Know-how. 

Um eine WSDL Datei zu analysieren und die Proxy Methode zu generieren:

1. Kopieren oder geben Sie im Bereich “URL” die URL für den gewünschten Web Service ein:
   
   Die URL kann z.B. aus einem Verzeichnis mit Web Services stammen oder direkt vom Server des Web Services mitgeteilt werden.
   Sie können auch eine lokale URL angeben, z.B. die Adresse einer WSDL Datei, die auf Ihrer Festplatte gespeichert ist. Dazu klicken Sie auf die Schaltfläche Öffnen und wählen die lokale WSDL Datei aus oder geben den Zugriffspfad direkt ein. Der Zugriffspfad der lokalen Datei beginnt mit “Datei://” und verwendet dann den standardmäßigen Separator des Systemordners. Sie müssen einen absoluten Zugriffspfad übergeben.
2. Klicken Sie auf die Schaltfläche Erkennen, um den Inhalt der WSDL Datei zu analysieren (parsen).
   Nach wenigen Augenblicken erscheint im Hauptbereich das Ergebnis der Durchsuchung: Der Name des/der Web Service(s) sowie die publizierten Methoden erscheinen in Form einer hierarchischen Liste.
   
   Hinweis: Klicken Sie mit gedrückter Umschalttaste auf die Schaltfläche Erkennen, erscheint der XML Quellcode der WSDL Datei direkt in Ihrem Standard Web Browser.
   Klicken Sie auf einen Web Service, erscheint – sofern vorhanden – die dazugehörige Beschreibung neben der hierarchischen Liste. Ansonsten erscheint die Angabe “Keine Dokumentation”.
   Dasselbe gilt, wenn Sie einen Methodennamen wählen und dazu Dokumentation vorhanden ist:
   
   Hinweis: Werden beim Durchsuchen der WSDL Datei Parameter für komplexe Typen festgestellt, zeigt der Assistent vor der betreffenden Methode eine gelbe Flagge .
3. Wählen Sie die gewünschte Web Service Methode und klicken auf die Schaltfläche Erzeugen.
   4D erzeugt sofort die dazugehörige Proxy Methode und zeigt sie in einem Fenster des 4D Methodeneditors an:
   
   Der Name der Proxy Methode beginnt mit der Standardvorsilbe “proxy_” gefolgt vom Namen der Web Service Methode. Sie können die Standardvorsilbe in den Datenbank-Einstellungen auf der Seite Web/ Web Services ändern. Sie können den Namen auch nach Erstellen der Proxy Methode ändern. Das beeinflusst nicht die Ausführung der Methode.

Die Proxy Methoden, die der Assistent für Web Services über Analysieren einer WSDL Datei erzeugt, sind sofort einsatzfähig, ohne irgendeine Änderung (Standardmodus). Sie können die Parameter dieser Proxy Methoden aber auch verändern, z.B. einen anderen Namen zuweisen. 

Mit dem Assistenten für Web Services können Sie auch eine Proxy Methode erstellen, in die Sie die Parameter manuell eingegeben haben. In diesem Fall verwenden Sie nicht den WSDL Parser.
Eine Methode wird auch erstellt, wenn Sie nicht alle Parameter eingeben.
Sie können sogar eine Proxy Methode ohne Parameter erstellen, die als Vorlage dient und dann über 4D Programmierung gefüllt wird.

Für diese Operationen müssen Sie die zusätzlichen Parameter des Assistenten für Web Services verwenden. Klicken Sie dazu auf das Icon Erweitert unter der Liste, um das Fenster zu erweitern. Ist eine Methode ausgewählt, enthalten die Eingabefelder die aktuellen Parameter:

Sie können alle Parameter verändern. Behandeln Sie jedoch Parameter, die sich aus WSDL Parsing ergeben, mit Bedacht, denn das kann die Funktionalität des Web Service beeinflussen. Davon ausgenommen ist der Methodenname. 

Es gibt folgende zusätzliche Parameter:

• Methodenname: Name, den der Assistent der zu erstellenden Proxy Methode gibt. Er beginnt standardmäßig mit der Vorsilbe “proxy_”. Das können Sie in den Voreinstellungen der 4D Anwendung verändern. Sie können den Namen beliebig verändern, z.B. weil er schon in der Datenbank vorhanden ist. Er hat keinen Einfluss auf die Ausführung des Web Service.
• Endpunkt URL: URL, an welche die Proxy Methode die SOAP Anfragen sendet.
• SOAP Aktion: Inhalt des Feldes SOAPAction. Es enthält in der Regel den Wert “ServiceName#MethodName”.
• Namensraum: Namensraum des Web Service. Weitere Informationen dazu finden Sie im Abschnitt Namensbereich anpassen).
• Parameter Tabelle: Diese Tabelle listet die Parameter der veröffentlichten Methode auf.
  
  Jede Zeile steht für einen Parameter:
  
  • Die erste Spalte zeigt an, ob der Parameter hereinkommt (“in”) oder hinausgeht (“out”). Dieses Merkmal wird aus Sicht der Proxy Methode, nicht aus Sicht der veröffentlichten Methode bewertet.
  • Die zweite Spalte gibt den Namen der Parameter an.
  • Die dritte Spalte gibt den SOAP Typ der Parameter an. Verschiedene von 4D anerkannte Typen lassen sich im Menü Typ im Bereich Eigenschaften anzeigen. Der 4D Assistent für Web Services hat die Aufgabe, die SOAP Typen den entsprechenden 4D Typen in der Proxy Methode zuzuweisen.
    Nachfolgende Tabelle gibt eine Übersicht:
    

    SOAP Typ	Entsprechender 4D Typ
    boolean	Boolean
    int	Lange Ganzzahl
    time	Zeit
    float	Zahl
    double	Zahl
    date	Datum
    string	Text
    base64Binary	BLOB
    ArrayOfBoolean	Array Boolean
    ArrayOfInt	Array Lange Ganzzahl
    ArrayOfTime	Array Lange Ganzzahl
    ArrayOfFloat	Array Zahl
    ArrayOfDate	Array Datum
    ArrayOfString	Array Text
    AsXML	BLOB

           
    Hinweis: Der Typ AsXML ist streng genommen kein SOAP Typ, er dient zur Unterstützung komplexer XML Typen (siehe Komplexe Typen).
    Der Bereich Eigenschaften zeigt die Wesensmerkmale der Parameter, die in der Tabelle gewählt wurden. Im Assistenten für 4D Web Services können Sie vorhandene Parameter verändern oder Parameter hinzufügen, z.B. wenn die angegebene WSDL Datei nicht mehr aktuell ist.
    
    • Wollen Sie einen Parameter verändern, wählen Sie ihn aus und nehmen die Änderungen im Bereich Eigenschaften vor.
    • Wollen Sie einen Parameter hinzufügen, klicken Sie auf die Schaltfläche Hinzufügen und definieren dann die Merkmale im Bereich Eigenschaften.
    • Wollen Sie einen Parameter löschen, wählen Sie ihn in der Liste aus und klicken auf die Schaltfläche Löschen.
  Hinweis: Änderungen in den zusätzlichen Parametern werden nur berücksichtigt, wenn die Proxy Methode über die Schaltfläche Erzeugen erstellt wurde.

Um eine Proxy Methode in Ihrem Code aufzurufen, schreiben Sie einfach ihren Namen und übergeben die erforderlichen Parameter. Diese Parameter deklariert der Assistent für Web Services im Header-Bereich der Proxy Methode. In Übereinstimmung mit der standardmäßigen Syntax zum Übergeben von Parametern zwischen Methoden in 4D lauten sie $0, $1, $2... Sie erscheinen auch in den zusätzlichen Parametern der Beschreibung zu den veröffentlichten Methoden (siehe Abschnitt Zusätzliche Parameter) und werden manchmal in der dazugehörigen Dokumentation beschrieben.

Beispiel: In einer Methode lässt sich die Proxy Methode folgendermaßen aufrufen:

Nach Ausführung der Methode erscheint folgende Meldung:

Mit 4D können Sie Web Services verwenden, die im RPC oder DOC Modus veröffentlicht werden und komplexe Typen enthalten (siehe Kompatibilität von RPC, DOC und komplexen Typen).

Hinweis: Auch bei komplexen XML Typen behandelt 4D Daten Arrays als einfache Typen. 

Proxy Methoden mit komplexen Typen, welche der Assistent für Web Services erzeugt, ähneln standardmäßigen Proxy Methoden, z.B. veröffentlicht im RPC Modus mit komplexen Typen oder im DOC Modus. Bei diesen Web Services werden Sie jedoch feststellen, dass der 4D Befehl WEB SERVICE CALL als Parameter eine Konstante mit den Wort manuell enthält. 

Das bedeutet, dass solche Web Services weitere Bearbeitung durch den 4D Entwickler erfordern. Der Hauptgrund dafür ist, dass komplexe Typen in Form von Dokumenten oder XML Elementen ausgetauscht werden. Demzufolge muss zum Entnehmen oder Einfügen von Information in diesen SOAP Parametern zuerst XML parsing ausgeführt werden – im Gegensatz dazu sind in einfachen Typen Werte von Parametern direkt lesbar. 

• Verwendung einfacher Typen (RPC)
  

• Verwendung komplexer Typen (DOC)
  

Der Assistent für Web Services kann nur Arrays und komplexe Typen mit einer Ebene verwalten, d.h. eine hierarchische Ebene in der SOAP Anfrage. Werden mehr komplexe Einträge in der Anfrage gefunden, signalisiert der Assistent über eine Flagge neben dem Methodennamen, wenn eine WSDL entdeckt wird. Die Verwaltung dieser Art Web Service erfordert in der Regel durch den Entwickler angepasstes Analysieren.

In 4D werden Parameter komplexer Typen – mit Ausnahme von Arrays – in Form von BLOBS verwaltet. Über die XML-Befehle können Sie deren Inhalt verwalten. Weitere Informationen dazu finden Sie im Handbuch 4D Programmiersprache in den Kapiteln Web Services (Client) und XML DOM.