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:
- Klicken Sie im Projektexplorer mit der rechten Maustaste auf die EGL-Datei, die den Service definiert.
- Klicken Sie auf .
- 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.
.