Übersicht über EMS-Ressourcen
Nach oben zu Erweitern des EMS-Servers
Eine EMS-Ressource ist eine Erweiterung der EMS-Server-API.
Wenn Sie eine EMS-Ressource in den EMS-Server laden, registriert der EMS-Server die Ressource und stellt alle ihre Endpunkte bereit. EMS-Client-Anwendungen können mit einer TBackendEndpoint-Komponente auf die Endpunkte Ihrer EMS-Ressource zugreifen.
- Hinweis: Erstellen Sie vor dem Definieren von EMS-Ressourcen ein EMS-Package, in dem Sie sie definieren können.
Inhaltsverzeichnis
Definieren einer Ressourcenklasse
Eine Ressourcenklasse ist eine Klasse, die eine EMS-Ressource repräsentiert.
Deklarieren einer Ressourcenklasse
Sie können Ressourcenklassen wie reguläre Klassen deklarieren. Zum Beispiel:
Delphi:
TMyResource = class;
C++:
// .h
class TMyResource {};
Ressourcenklassen müssen mindestens einen Konstruktor haben, der entweder:
- Keinen Parameter oder
- Einen einzelnen Parameter mit dem Typ TComponent akzeptiert.
Ressourcennamen
Jede EMS-Ressource hat einen Ressourcennamen, der diese Ressource eindeutig bezeichnet. Wenn Sie auf Ihre Ressource aus einer EMS-Client-Anwendung zugreifen, müssen Sie in der Eigenschaft Resource Ihrer TBackendEndpoint-Komponente den Namen der Zielressource angeben.
Standardmäßig ist der Name der EMS-Ressource, die Ihre Klasse repräsentiert, der Name Ihrer Klasse ohne das Präfix "T" (falls vorhanden). Beispielsweise lautet der Name der Ressource der oben genannten Klasse "MyResource". Wenn Sie für Ihre EMS-Ressource einen anderen Namen verwenden möchten, können Sie ihn später anpassen.
Definieren von Endpunktmethoden
Nach der Definition einer Ressourcenklasse sollten Sie dieser Klasse mindestens eine Endpunktmethode hinzufügen.
Eine Endpunktmethode ist eine Methode, die API-Anforderungen an die Ressource behandelt, in der diese Methode definiert ist.
API-Anforderungen müssen eine Anforderungsmethode (z. B. "GET") und ein optionales Ressourcensuffix enthalten. Jede Endpunktmethode einer Ressourcenklasse muss eine Kombination der Anforderungsmethode und des Ressourcensuffixes behandeln.
Wenn der EMS-Server eine Anforderung erhält, die eine Endpunktmethode behandeln kann:
- Führt der EMS-Server diese Endpunktmethode aus.
- Generiert die Endpunktmethode eine Antwort.
- Sendet der EMS-Server die generierte Antwort zurück an die Client-Anwendung, die die ursprüngliche Anforderung gesendet hat.
Deklarieren einer Endpunktmethode
Zum Deklarieren einer Endpunktmethode müssen Sie eine Methode in Ihrer Ressourcenklasse deklarieren, die die folgenden Bedingungen erfüllt:
- Sie ist mit der Sichtbarkeit public oder published deklariert.
- Ihr Name beginnt mit einem String (Zeichenfolge), die dem Namen einer Anforderungsmethode entspricht:
Get
,Put
,Post
,Delete
oderPatch
.Get
,PutItem
undPostWhateverYouWant
sind alles gültige Namen für Endpunktmethoden. Sie können jede Schreibweise für diesen Präfix verwenden; z. B. sindGet
,get
undGET
gültige Präfixe für den Namen einer Endpunktmethode.
- Ihre Signatur hat keinen Rückgabewert und akzeptiert nur die folgenden drei Parameter in dieser Reihenfolge: TEndpointContext, TEndpointRequest und TEndpointResponse.
-
- Delphi:
procedure MethodName(const AContext: TEndpointContext; const ARequest: TEndpointRequest; const AResponse: TEndpointResponse);
-
- C++:
void MethodName(TEndpointContext* AContext, TEndpointRequest* ARequest, TEndpointResponse* AResponse);
Wenn eine Methode einer Ressourcenklasse nicht alle oben genannten Bedingungen erfüllt, ordnet der EMS-Server dieser Methode keinen API-Endpunkt zu.
Implementieren einer Endpunktmethode
Ihre Implementierung einer Endpunktmethode muss die Instanz von TEndpointResponse, die diese Daten erhält, normalerweise mit JSON-Daten füllen. Sie können mit der Methode SetValue der Eigenschaft Body von TEndpointResponse
die Antwort mit JSON-Daten füllen, oder Sie können mit SetBytes oder SetStream Rohdaten in den Antwortrumpf schreiben.
Unter Tutorial: Implementieren Ihrer ersten EMS-Ressource finden Sie einige einfache Beispiele dazu.
Anforderungsmethoden
Der Name einer Endpunktmethode beginnt mit dem Namen der Anforderungsmethode, die die Endpunktmethode behandelt. Daher kann eine einzelne Endpunktmethode nicht mehrere unterschiedliche Anforderungsmethoden behandeln.
Die EMS-Server-API unterstützt die folgenden Typen von Anforderungsmethoden:
Name | Beschreibung |
---|---|
GET |
Zum Abrufen von Daten. |
PUT |
Zum Erstellen eines neuen Elements und Abrufen seiner ID. |
POST |
Zum Ersetzen eines vorhandenen Elements durch neue Daten. |
PATCH |
Zum Aktualisieren der Daten eines vorhandenen Elements. |
DELETE |
Zum Löschen eines Elements. |
Ressourcensuffixe
Ein Ressourcensuffix ist ein String (Zeichenfolge) am Ende eines Endpunkt-URL, direkt nach dem Ressourcennamen (in Kleinbuchstaben). Wenn beispielsweise mit dem URL http://example.com/ems/myresource/item/count auf einen Endpunkt zugegriffen wird und der Name der Ressource "MyResource" lautet, ist das Ressourcensuffix dieses Endpunkts "item/count" (oder "/item/count").
Jede Endpunktmethode wird einem bestimmten Ressourcensuffix zugeordnet. Wenn Sie auf Ihre Ressource aus einer EMS-Client-Anwendung zugreifen, müssen Sie in der Eigenschaft ResourceSuffix Ihrer TBackendEndpoint-Komponente den Namen des Ressourcensuffixes angeben.
Standardmäßig ist das Ressourcensuffix einer Endpunktmethode ein leerer String. Um einer Endpunktmethode ein anderes Ressourcensuffix zuzuweisen, müssen Sie die Zuordnung der Endpunktmethode später anpassen.
Ein Ressourcensuffix ist immer der relative Pfad zu dem URL der Ressource selbst. Wenn Sie einer Endpunktmethode ein Ressourcensuffix zuweisen, das mit einem Schrägstrich (/) beginnt, ignoriert der EMS-Server diesen Schrägstrich. Beispielsweise sind "/item/count" und "item/count" gültige Ressourcensuffixe, die beide auf denselben Endpunkt-URL, z. B. http://example.com/ems/myresource/item/count, zeigen.
Spezielle Segmente für Ressourcensuffixe
Ein Segment ist ein String (Zeichenfolge), der andere Zeichen als Schrägstriche enthält. Ein Ressourcensuffix kann aus mehreren durch Schrägstriche getrennten Segmenten bestehen. Zum Beispiel enthält "item/count" zwei Segmente, "item" und "count".
Ressourcensuffixe unterstützen die folgenden speziellen Segmente:
Segment | Beschreibung |
---|---|
|
Entspricht jedem Segment. Beispielsweise entspricht das Ressourcensuffix "*/count" den Segmenten "foo/count" und "bar/count". |
|
<Bezeichner> kann ein Bezeichner, wie z. B. "item" oder "key", sein. Entspricht jedem Segment und speichert das übereinstimmende Segment in der Eigenschaft TEndpointRequest.Params mit Ihrem Bezeichner als Schlüssel und dem eigentlichen String aus dem Anforderungs-URL als Wert. Das Ressourcensuffix "{item}/bar" entspricht "foo/bar" und füllt die Eigenschaft TEndpointRequest.Params mit dem folgenden Paar: |
- Hinweis: Sie können diese speziellen Segmente nur als vollständige Segmente verwenden. In Ressourcensuffixen, wie "foo*/bar" oder "{foo}bar/count", interpretiert der EMS-Server "foo*" und "{foo}bar" als reguläre Strings, nicht als spezielle Segmente.
Namen von Endpunkten
Der Name eines Endpunkts ist der Anzeigestring, der diesen Endpunkt in der Benutzeroberfläche der EMS-Konsole repräsentiert.
Standardmäßig ist der Name eines Endpunkts, der eine Endpunktmethode repräsentiert, der Name dieser Methode. Wenn Sie für Ihren Endpunkt einen anderen Namen verwenden möchten, können Sie ihn später anpassen.
Endpunktnamen müssen innerhalb einer Ressource eindeutig sein. Wenn Sie denselben Endpunktnamen für zwei verschiedene Endpunktmethoden verwenden, hängt der EMS-Server an das Ende der wiederholten Endpunktnamen eine Zahl an, damit sie eindeutig sind. Wenn Sie beispielsweise bei zwei Endpunktmethoden die Zuordnung ändern, damit beide "MyEndpoint" als Endpunktnamen verwenden, behält die erste Endpunktmethode diesen Endpunktnamen, aber der Name der zweiten Endpunktmethode wird zu "MyEndpoint2".
Anpassen der Zuordnung Ihrer Ressourcen
Bevor Sie Ihre Ressourcenklassen beim EMS-Server registrieren, können Sie ändern, wie Sie jede Ressourcenklasse und Endpunktmethode zur EMS-Server-API zuordnen.
Sie können Ressourcennamen, Ressourcensuffixe und Endpunktnamen ändern. Allerdings können Sie keine Anforderungsmethoden ändern; diese werden immer durch das Präfix des Namens einer Endpunktmethode festgelegt.
Um die Zuordnung einer Ressource anzupassen, können Sie für diese Ressource ein Ressourcenattributobjekt definieren und dieses Objekt beim Registrieren Ihrer Ressource verwenden. In Delphi können Sie alternativ die Zuordnung Ihrer Ressource mithilfe von Attributen ändern.
Definieren eines Ressourcenattributobjekts
Ein Ressourcenattributobjekt ist eine Instanz von TEMSResourceAttributes.
So passen Sie die Zuordnung einer Ressource mithilfe eines Ressourcenattributobjekts an:
- Erstellen Sie eine Instanz von
TEMSResourceAttributes
. - Füllen Sie die Eigenschaften Ihres Ressourcenattributobjekts mit den Zuordnungen, die Ihre Ressource verwenden soll.
- Übergeben Sie Ihr Objekt als zweiten Parameter von RegisterResource, wenn Sie Ihre Ressource registrieren.
Sie können mit den folgenden Eigenschaften von TEMSResourceAttributes
die Zuordnung Ihrer Ressource anpassen:
Eigenschaft | Beschreibung |
---|---|
Legt den Namen Ihrer Ressource fest. | |
Legt anhand des Namens einer Endpunktmethode das Ressourcensuffix dieser Endpunktmethode fest. | |
Legt anhand des Namens einer Endpunktmethode den Namen des Endpunkts fest, den die angegebene Endpunktmethode repräsentiert. |
- Hinweis: Sie müssen nur die Zuordnungsdaten festlegen, die Sie ändern möchten. Wenn Sie beispielsweise den Wert von ResourceName nicht ändern, verwendet der EMS-Server den Standardnamen Ihrer Ressource (der auf dem Namen Ihrer Ressourcenklasse basiert).
Zum Beispiel:
- Delphi:
// var MyResourceAttributes: TEMSResourceAttributes;
MyResourceAttributes.Create();
MyResourceAttributes.ResourceName := 'Resource';
MyResourceAttributes.ResourceSuffix['Get'] := '{item}';
MyResourceAttributes.EndPointName['Get'] := 'GetItem';
- C++:
std::auto_ptr<TEMSResourceAttributes> MyResourceAttributes(new TEMSResourceAttributes());
MyResourceAttributes->ResourceName = "Resource";
MyResourceAttributes->ResourceSuffix["Get"] = "{item}";
MyResourceAttributes->EndPointName["Get"] = "GetItem";
Anpassen der Zuordnung von Ressourcen mithilfe von Attributen (Delphi)
Um die Zuordnungsdaten Ihrer Ressourcenklassen und Endpunktmethoden in Delphi anzupassen, können Sie sie mit den folgenden Attributen mit Hinweisen versehen:
Member-Typ | Attribut | Beschreibung |
---|---|---|
Ressourcenklasse |
Legt den Namen Ihrer Ressource fest. | |
Endpunktmethode |
Legt das Ressourcensuffix der Endpunktmethode fest. | |
Legt den Namen des Endpunkts fest, der die Endpunktmethode repräsentiert. |
Zum Beispiel:
[ResourceName('Resource')]
TMyResource = class
published
[ResourceSuffix('{item}')]
[EndpointName('GetItem')]
procedure Get(const AContext: TEndpointContext; const ARequest: TEndpointRequest; const AResponse: TEndpointResponse);
end;
Registrieren einer Ressource
Wenn Ihre Ressourcenklasse und deren Endpunktmethoden definiert sind, müssen Sie:
- Ihre Ressourcenklasse an TypeInfo übergeben, um die RTTI-Informationen Ihrer Ressourcenklasse abzurufen.
- Die RTTI-Informationen Ihrer Ressourcenklasse übergeben und RegisterResource verwenden.
Sie sollten RegisterResource
für die Methode Register Ihres Package aufrufen.
Zum Beispiel:
- Delphi:
RegisterResource(TypeInfo(TMyResource));
- C++:
RegisterResource(__typeinfo(TMyResource));
Registrieren einer Ressource mit einem Ressourcenattributobjekt
Wenn Sie ein Ressourcenattributobjekt erstellt haben, um die Zuordnungsdaten Ihrer Ressourcenklasse und Ihrer Endpunktmethoden anzupassen, übergeben Sie Ihr Ressourcenattributobjekt an RegisterResource
als zweiten Parameter.
Zum Beispiel:
- Delphi:
RegisterResource(TypeInfo(TMyResource), MyResourceAttributes);
- C++:
RegisterResource(__typeinfo(TMyResource), MyResourceAttributes.release());