Schnittstellenabschnitt für Zugriff auf einen REST-Service erstellen

Ein EGL-Schnittstellenabschnitt wird in einer Datei definiert, die dem Anforderer dieses Service zur Verfügung gestellt wird. Der Schnittstellenabschnitt kann sich im selben EGL-Paket befinden oder aus einem anderen Paket importiert werden.

Ein EGL-Schnittstellenabschnitt enthält mindestens einen Funktionsprototyp. Ein Funktionsprototyp beschreibt, wie Code geschrieben werden muss, um auf eine bestimmte Serviceoperation zugreifen zu können. Der Funktionsprototyp enthält den Operationsnamen, Parameter (sofern vorhanden) und gegebenenfalls einen Rückgabetyp. Die Logik der Operation ist im Prototyp nicht enthalten. Diese ist nur im Service verfügbar.

Der Schnittstellenabschnitt eines EGL-REST-RPC-Service ist einfacher als der Schnittstellenabschnitt für den REST-Service eines anderen Herstellers.

Schnittstellenabschnitt für Zugriff auf einen EGL-REST-RPC-Service

Das folgende Beispiel zeigt einen Schnittstellenabschnitt für den Zugriff auf einen EGL-REST-RPC-Service. Das Beispiel enthält einen einzelnen Funktionsprototyp:
Interface EmployeeService
   Function GetEmployeeDetail(employeeCode STRING IN, 
                              employeeSalary FLOAT OUT, 
                              employeeStatus STRING INOUT) 
            returns(myEmployeeRecordPart);
end

Sie können verschiedene EGL-Datentypen angeben und die Änderungswerte IN, OUT und INOUT verwenden.

Gehen Sie wie folgt vor, um den Schnittstellenabschnitt zu erstellen:
  1. Klicken Sie im Projektexplorer mit der rechten Maustaste auf die EGL-Datei, die den Service definiert.
  2. Klicken Sie auf EGL-Services > EGL-Schnittstelle extrahieren.
  3. Geben Sie im Fenster 'Neuer EGL-Schnittstellenabschnitt' die entsprechenden Details an und klicken Sie auf Fertigstellen.

Schnittstellenabschnitt für Zugriff auf REST-Service eines anderen Herstellers

Das folgende Beispiel zeigt einen Schnittstellenabschnitt für den Zugriff auf den REST-Service eines anderen Herstellers:
Interface WeatherForecast
   Function GetWeatherByZipCode(zipcode string in) returns(myRecordPart)
      {@GetRest{uriTemplate="/GetWeatherByZipCode?zipCode={zipcode}",
                requestFormat = JSON,
                responseFormat = JSON}};
end
Wenn der Schnittstellenabschnitt die Aufgabe hat, die Operationen in einem REST-Service eines anderen Herstellers (nicht in einem EGL-REST-RPC-Service) zu beschreiben, müssen Sie für jeden Funktionsprototyp eine komplexe Eigenschaft angeben. Der Name der Eigenschaft weist auf das HTTP-Verb hin, mit dem der Zugriff auf den Service erfolgt:
  • Für die Methode GET lautet der Eigenschaftsname @GetREST.
  • Für die Methode POST lautet der Eigenschaftsname @PostREST.
  • Für die Methode PUT lautet der Eigenschaftsname @PutREST.
  • Für die Methode DELETE lautet der Eigenschaftsname @DeleteREST.
Diese komplexen Eigenschaften werden als @xREST-Eigenschaften bezeichnet, weil sie dieselben drei Eigenschaftsfelder aufweisen (siehe Abschnitt zu den @xREST-Eigenschaften weiter unten).
In der Serviceaufrufanweisung für den Zugriff auf den REST-Service eines anderen Herstellers hat das Argument, das an einen bestimmten Funktionsparameter übergeben wird, eine von zwei Aufgaben:
  • In der Regel stellt das Argument einen Wert bereit, den der Anforderer in den URI einfügt. Diese Art der Verwendung wird weiter unten in der Beschreibung der @xREST-Eigenschaften erläutert. Diese Werte werden nicht an die Servicelogik übergeben, sondern in den URI eingebettet. Bei der Eigenschaft @GetREST werden sogar alle den Funktionsparametern zugeordneten Argumente zur Erstellung des URIs verwendet.
  • Im Falle nur eines Arguments ist das Argument eine Darstellung, die vom Service verarbeitet wird (z. B. ein Datensatz, der Werte zur Erstellung einer Datenbanktabellenzeile enthält). Weitere Details:
    • Wenn die Eigenschaft für eine bestimmte Operation @PostREST oder @PutREST lautet, muss das zusätzliche Argument vorhanden sein. Der zugehörige Parameter wird als Darstellungsparameter bezeichnet.
    • Das Argument kann ebenfalls erforderlich sein, wenn die Eigenschaft @DeleteREST lautet. Ob ein solches Argument erforderlich ist, hängt vom Service-Provider ab.
Wenn der Funktionsprototyp über einen Parameter verfügt, der im Eigenschaftsfeld uriTemplate (für @PostREST, @PutREST und @DeleteREST) nicht angegeben ist, ist dieser Parameter ein Darstellungsparameter. Die beiden folgenden Fälle stellen einen Fehler dar:
  • Die Angabe von mehr als einem Darstellungsparameter.
  • Die Angabe eines Darstellungsparameters, wenn @GetREST verwendet wird.

Einschränkungen in Bezug auf Argumente, die an einen Service gesendet werden, finden Sie in 'Einschränkungen bei den für den Servicezugriff verwendeten Prototypen'.

Die Erstellung eines Schnittstellenabschnitts ist nicht erforderlich. Sie können stattdessen IRest verwenden, einen für den Benutzer bereitgestellten Schnittstellenabschnitt, der die Basis einer Variablen für den Zugriff auf den REST-Service eines anderen Herstellers sein kann. Weitere Informationen zu diesem Schnittstellenabschnitt finden Sie in 'Bereitgestellte Schnittstelle für REST-Service eines anderen Herstellers verwenden'.

@xREST-Eigenschaften für REST-Services eines anderen Herstellers

Jede komplexe @xREST-Eigenschaft verfügt über die folgenden Felder: uriTemplate, requestFormat und responseFormat.

uriTemplate
Eine Zeichenfolge oder Vorlage, die in den meisten Fällen einen relativen URI beschreibt, der die letzten Qualifikationsmerkmale des URI angibt, die für den Zugriff auf den Service verwendet werden. Hintergrundinformationen finden Sie in 'REST für Entwickler'.
Zum Angeben der ersten URI-Qualifikationsmerkmale (Basis-URI) gibt es drei Möglichkeiten:
  • Bei der Deklaration einer Variablen, die auf dem Schnittstellenabschnitt basiert, kann der Basis-URI definiert werden. In diesem Fall wird der Basis-URI zur Entwicklungszeit definiert und kann zur Konfigurations- oder Laufzeit nicht mehr geändert werden. Diese Verwendungsmöglichkeit ist einfach und schnell, aber unflexibel.
  • Alternativ können Sie bei der Deklaration einer Variablen, die auf dem Schnittstellenabschnitt basiert, einen Eintrag im Implementierungsdeskriptor angeben. In diesem Fall befindet sich ein Anfangswert für den Basis-URI im Implementierungsdeskriptor, der zur Konfigurationszeit von einem für die Codeinstallation verantwortlichen Benutzer geändert werden kann.
  • Die Funktion serviceLib.setServiceLocation kann ausgeführt werden, um den Wert des Basis-URI zur Laufzeit zu ändern. Dies ist unabhängig davon, wie Sie einen Anfangswert angeben.

Wenn Sie den Basis-URI nicht angeben, enthält der Wert des Eigenschaftsfelds uriTemplate den vollständigen URI. In den meisten Fällen hat der Wert der Eigenschaft uriTemplate zwei Aspekte:

  • Der Wert der Eigenschaft uriTemplate kann einen konstanten Wert enthalten. Diese Zeichen sind in oder hinter jedem URI vorhanden, der für den Zugriff auf die Funktion verwendet wird. Im obigen Beispiel enthält der Wert von uriTemplate eine Abfragevariable und der konstante Wert lautet wie folgt:
       /GetWeatherByZip?zipcode= 
    Wenn das Beispiel geändert und eine Pfadvariable anstelle der Abfragezeichenfolge eingefügt wird, lautet der konstante Wert wie folgt:
       /GetWeatherByZip/
  • Der Wert der Eigenschaft uriTemplate kann Pfadvariablen und Abfragevariablen enthalten. Das obige Beispiel enthält eine einzelne Abfragevariable:
       {zipcode}
    Für das ursprüngliche Beispiel mit einer Abfragezeichenfolge werden der folgende relative URI und Wert für den Zugriff auf den Service verwendet:
    /GetWeatherByZip?zipcode=02135
    Wenn die Vorlage eine Pfadvariable anstelle einer Abfragezeichenfolge enthält, könnte der relative URI so aussehen:
    /GetWeatherByZip/02135

    Der EGL-Laufzeitcode nimmt für jeden in einer Serviceaufrufanweisung angegebenen Substitutionswert automatisch eine URI-Codierung vor. Dabei gibt es eine Ausnahme:

    Wenn beispielsweise der Wert für eine bestimmte Substitutionsvariable laut Serviceaufrufanweisung 'Jeff Smith' lautet, konvertiert der EGL-Laufzeitcode die Zeichenfolge in 'Jeff%20Smith', damit der URI gültig ist. Wenn der Wert eines Substitutionswerts jedoch mit http beginnt, nimmt der EGL-Laufzeitcode keine URI-Codierung vor, weil die Serviceaufrufanweisung ein Argument mit einem vollständigen URI angibt. Der für die URI-Codierung verantwortliche Benutzer sollten die Dokumentation für die Systemfunktion serviceLib.convertToURLEncoded zu Rate ziehen.

Der Standardwert des Felds uriTemplate ist eine leere Zeichenfolge, sodass Sie durch Angabe des Basis-URI standardmäßig den vollständigen URI definieren können.

requestFormat
Ein Wert, der das Format der an den Service gesendeten Darstellung angibt:
  • XML gibt an, dass Extensible Markup Language als Format verwendet wird.
  • NONE gibt an, dass die Darstellung eine Zeichenfolge oder ein mit einer Zeichenfolge kompatibler Wert ist, die unverändert gesendet wird.
  • JSON gibt an, dass JavaScript Object Notation als Format verwendet wird.
  • FORM gibt an, dass das Format aus Formulardaten (ein Datensatz, der aus Argument-/Wertpaaren zusammengesetzt ist) besteht. Im folgenden Beispiel des an den Service gesendeten Inhalts sind die einzelnen Paare durch ein Et-Zeichen (&) voneinander getrennt:
    division=Consumer&dept=Sales
    Für ein Feld des Datensatzabschnitts, der die Basis der Formulardaten darstellt, kann die Eigenschaft FormName angegeben werden. Diese Eigenschaft kann für einen Argumentnamen verwendet werden, der ein reserviertes EGL-Wort oder in EGL nicht gültig ist. Im Folgenden ist ein Beispiel für die Verwendung der Eigenschaft FormName aufgeführt:
    record anyRecord
       continue boolean {FormName="continue-content"};
    end
    Der Laufzeitcode verwendet den Wert der Eigenschaft FormName als Namen für das an den Service übertragene Argument. Im Folgenden ist eine Darstellung aufgeführt, die an den Service gesendet werden könnte:
    continue-content=yes

    Der Standardwert der Eigenschaft FormName ist der Name des Datensatzfelds. In diesem Beispiel lautet der Standardwert continue.

    Der Wert der Eigenschaft FormName kann beim Deklarieren eines auf dem Datensatzabschnitt basierenden Datensatzes nicht überschrieben werden.

Wenn die Darstellung ein Datensatz ist, treffen die folgenden Aussagen zu:
  • Der Standardwert von requestFormat ist XML.
  • JSON ist ebenfalls gültig.
  • FORM ist nur gültig, wenn jedes Feld im Datensatz vom Typ STRING ist oder einen Typ aufweist, der mit STRING zuordnungskompatibel ist. FORM ist nicht gültig, wenn der Datensatz auf einen anderen Datensatz verweist.
responseFormat
Ein Wert, der das Format der an den Anforderer zurückgegebenen Darstellung angibt:
  • XML gibt an, dass die Darstellung im XML-Format zurückgegeben wird.
  • NONE gibt an, dass die Darstellung als Zeichenfolge zurückgegeben wird.
  • JSON gibt an, dass die Darstellung im JSON-Format zurückgegeben wird.

Wenn der Rückgabewert im Funktionsprototyp des Schnittstellenabschnitts eine Zeichenfolge oder ein mit einer Zeichenfolge kompatibler Wert ist, weist responseFormat den Standardwert NONE auf. Dieser Wert stellt das einzig gültige Format dar. Wenn der Rückgabewert ein Datensatz ist, hat responseFormat den Standardwert XML; JSON ist ebenfalls gültig.

Sie können eine @xREST-Eigenschaft angeben, ohne den Eigenschaftsfeldern Werte zuzuweisen:
Interface IEmployeeService
   Function GetEmployeeDetail() returns(myRecordPart)
      {@GetRest{}};
end
Wenn keine Eigenschaftsfelder vorhanden sind, weist dies auf das folgende Verhalten hin:
  • Sie müssen den vollständigen REST-Service-URI angeben (z. B. http://www.ibm.com/myservice), ohne Details im Schnittstellenabschnitt. Informationen zu den drei Möglichkeiten der Angabe des Basis-URI finden Sie in der Beschreibung zu uriTemplate in diesem Thema.
  • Wenn der Darstellungsparameter (oder im Falle der Eigenschaft @GetREST der Rückgabewert) eine Zeichenfolge ist, führt der EGL-Laufzeitcode keine Konvertierung durch. Sie müssen die Konvertierung durchführen und können dazu die folgenden Funktionen verwenden:
    • serviceLib.convertFromJSON
    • serviceLib.convertToJSON
    • XMLLib.convertFromXML
    • XMLLib.convertToXML
  • Wenn der Darstellungsparameter ein Datensatz ist, konvertiert der EGL-Laufzeitcode das zugehörige Argument in das XML-Format.
  • Wenn der Rückgabewert bei der Eigenschaft @GetREST ein Datensatz ist, konvertiert der EGL-Laufzeitcode diesen Datensatz aus dem XML-Format.
.

Feedback