Übersicht über RAD Server-Ressourcen

Aus RAD Studio
Wechseln zu: Navigation, Suche

Nach oben zu Erweitern der RAD Server Engine


Eine RAD Server-Ressource ist eine Erweiterung der API der RAD Server Engine (EMS-Server).

Wenn Sie eine RAD Server-Ressource in die RAD Server Engine laden, registriert die RAD Server Engine sie und stellt alle ihre Endpunkte bereit. RAD Server-Anwendungen können mit einer TBackendEndpoint-Komponente auf die Endpunkte Ihrer RAD Server-Ressource zugreifen.

Hinweis: Erstellen Sie zunächst ein RAD Server-Package, in dem Sie RAD Server-Ressourcen definieren können.

Definieren einer Ressourcenklasse

Eine Ressourcenklasse ist eine Klasse, die eine RAD Server-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 einem der folgenden Punkte entspricht:

  • Der Konstruktor akzeptiert keine Parameter.
  • Der Konstruktor akzeptiert einen einzelnen Parameter mit dem Typ TComponent.

Ressourcennamen

Jede RAD Server-Ressource hat einen Ressourcennamen, der diese Ressource eindeutig bezeichnet. Wenn Sie auf Ihre Ressource aus einer RAD Server-Client-Anwendung zugreifen, müssen Sie in der Eigenschaft Resource Ihrer TBackendEndpoint-Komponente den Namen der Zielressource angeben.

Standardmäßig ist der Name der RAD Server-Ressource, die Ihre Klasse repräsentiert, der Name der Klasse ohne das Präfix "T" (falls vorhanden). Beispielsweise lautet der Name der Ressource der oben genannten Klasse "MyResource". Wenn Sie für Ihre RAD Server-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 aus Anforderungsmethode und Ressourcensuffix verarbeiten.

Wenn die RAD Server Engine eine Anforderung erhält, die eine Endpunktmethode verarbeiten kann:

  1. Führt die RAD Server Engine diese Endpunktmethode aus.
  2. Generiert die Endpunktmethode eine Antwort.
  3. Sendet die RAD Server Engine 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, der dem Namen einer Anforderungsmethode entspricht: Get, Put, Post, Delete oder Patch. Andernfalls müssen Sie die Anforderungsmethode angeben.
    Get, PutItem und PostWhateverYouWant sind alles gültige Namen für Endpunktmethoden. Sie können jede Schreibweise für dieses 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 die RAD Server Engine (EMS-Server) dieser Methode keinen API-Endpunkt zu.

Implementieren einer Endpunktmethode

Ihre Implementierung einer Endpunktmethode muss die empfangene Instanz von TEndpointResponse mit Daten, 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 RAD Server-Ressource finden Sie einige einfache Beispiele dazu.

Anforderungsmethoden

Standardmäßig wird die Anforderungsmethode einer Endpunktmethode durch den Anfang des Endpunktmethodennamens bestimmt. Um einer Endpunktmethode eine andere Anforderungsmethode zuzuweisen, müssen Sie die Zuordnung der Endpunktmethode später anpassen.

Die RAD Server Engine-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 am Ende einer Endpunkt-URL, direkt nach dem Ressourcennamen (in Kleinbuchstaben). Wenn beispielsweise mit der 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 RAD Server-Client-Anwendung zugreifen, müssen Sie in der Eigenschaft ResourceSuffix Ihrer TBackendEndpoint-Komponente das Ressourcensuffix 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 der URL der Ressource selbst. Wenn Sie einer Endpunktmethode ein Ressourcensuffix zuweisen, das mit einem Schrägstrich (/) beginnt, ignoriert die RAD Server Engine diesen Schrägstrich. Beispielsweise sind "/item/count" und "item/count" gültige Ressourcensuffixe, die beide auf dieselbe Endpunkt-URL, z. B. http://example.com/ems/myresource/item/count, zeigen.

Spezielle Segmente für Ressourcensuffixe

Ein Segment ist ein String, der andere Zeichen (keine 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 der 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 die RAD Server Engine "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 RAD Server-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 die RAD Server Engine an das Ende von 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 bei, aber der Name der zweiten Endpunktmethode wird zu "MyEndpoint2".

Anpassen der Zuordnung Ihrer Ressourcen

Bevor Sie Ihre Ressourcenklassen bei der RAD Server Engine registrieren, können Sie ändern, wie Sie jede Ressourcenklasse und Endpunktmethode der RAD Server Engine-API zuordnen.

Sie können Ressourcennamen, Ressourcensuffixe, Endpunktnamen und Anforderungsmethoden ändern.

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 aus, 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.

EndPointHTTPMethod

Legt anhand des Namens einer Endpunktmethode die Anforderungsmethode dieser Endpunktmethode fest.

Hinweis: Sie müssen nur die Zuordnungsdaten definieren, die Sie ändern möchten. Wenn Sie beispielsweise den Wert von ResourceName nicht ändern, verwendet die RAD Server Engine 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.

EndpointMethod

Legt die Anforderungsmethode der Endpunktmethode fest.

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 an die RAD Server Engine mit RegisterResource übergeben.

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 „https://docwiki.embarcadero.com/RADStudio/Alexandria/d/index.php?title=Übersicht_über_RAD_Server-Ressourcen&oldid=217919“