Übersicht über RAD Server-Ressourcen

Aus RAD Studio
Wechseln zu: Navigation, Suche

Nach oben zu Erweitern der RAD Server Engine


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.

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:

  1. Führt der EMS-Server diese Endpunktmethode aus.
  2. Generiert die Endpunktmethode eine Antwort.
  3. 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 oder Patch.
    Get, PutItem und PostWhateverYouWant sind alles gültige Namen für Endpunktmethoden. Sie können jede Schreibweise für diesen Präfix verwenden; z. B. sind Get, get und GET 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>}

<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: item=foo.

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:

  1. Erstellen Sie eine Instanz von TEMSResourceAttributes.
  2. Füllen Sie die Eigenschaften Ihres Ressourcenattributobjekts mit den Zuordnungen, die Ihre Ressource verwenden soll.
  3. Ü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

ResourceName

Legt den Namen Ihrer Ressource fest.

ResourceSuffix

Legt anhand des Namens einer Endpunktmethode das Ressourcensuffix dieser Endpunktmethode fest.

EndPointName

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

ResourceName

Legt den Namen Ihrer Ressource fest.

Endpunktmethode

ResourceSuffix

Legt das Ressourcensuffix der Endpunktmethode fest.

EndpointName

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:

  1. Ihre Ressourcenklasse an TypeInfo übergeben, um die RTTI-Informationen Ihrer Ressourcenklasse abzurufen.
  2. 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());

Siehe auch

Abgerufen von „http://docwiki.embarcadero.com/RADStudio/Sydney/d/index.php?title=Übersicht_über_RAD_Server-Ressourcen&oldid=214069“