Présentation des ressources de RAD Server

De RAD Studio
Aller à : navigation, rechercher

Remonter à Extension du moteur RAD Server


Une ressource EMS est une extension de l'API du serveur EMS.

Lorsque vous chargez une ressource EMS dans le serveur EMS, celui-ci la recense et expose tous ses points de terminaison. Les applications client EMS peuvent utiliser un composant TBackendEndpoint pour accéder aux points de terminaison de votre ressource EMS.

Remarque : Avant de définir une ou plusieurs ressources EMS, créez un package EMS à l'endroit approprié pour cette définition.

Définition d'une classe de ressource

Une classe de ressource est une classe qui représente une ressource EMS.

Déclaration d'une classe de ressource

Vous pouvez déclarer des classes de ressource en tant que classes normales. Par exemple :

Delphi : 

TMyResource = class;

C++ : 

// .h
class TMyResource {};

Les classes de ressource doivent avoir au moins un constructeur correspondant à l'une des situations suivantes :

  • Le constructeur n'accepte aucun paramètre.
  • Le constructeur accepte un seul paramètre de type TComponent.

Noms de ressource

Chaque ressource EMS a un nom de ressource qui l'identifie de manière unique. Lorsque vous accédez à votre ressource depuis une application client EMS, vous devez remplir la propriété Resource de votre composant TBackendEndpoint avec le nom de la ressource cible.

Par défaut, le nom de la ressource EMS représentant votre classe est le nom de la classe sans le préfixe "T" (si elle utilise un tel préfixe). Par exemple, le nom de la ressource de la classe ci-dessus est "MyResource". Si vous voulez utiliser un nom différent pour votre ressource EMS, vous avez la possibilité de le personnaliser ultérieurement.

Définition des méthodes de point de terminaison

Après avoir défini une classe de ressource, vous devez ajouter une ou plusieurs méthodes de point de terminaison à cette classe.

Une méthode de point de terminaison est une méthode qui gère les requêtes API ciblant la ressource à l'endroit où cette méthode est définie.

‎Les requêtes API doivent spécifier une méthode de requête (par exemple, "GET") et un suffixe de ressource optionnel. Chaque méthode de point de terminaison d'une classe de ressource doit gérer une combinaison composée d'une méthode de requête et d'un suffixe de ressource.

Lorsque le serveur EMS reçoit une requête pouvant être gérée par une méthode de point de terminaison :

  1. Le serveur EMS exécute cette méthode de point de terminaison.
  2. La méthode de point de terminaison génère une réponse.
  3. Le serveur EMS renvoie la réponse générée à l'application client qui a envoyé la requête originale.

Déclaration d'une méthode de point de terminaison

Pour déclarer une méthode de point de terminaison, vous devez déclarer une méthode au sein de votre classe de ressource et faire en sorte qu'elle réponde aux exigences suivantes :

  • Elle est déclarée avec une visibilité publique ou publiée.
  • Son nom commence par une chaîne correspondant à un nom de méthode de requête : Get, Put, Post, Delete ou Patch.
    Get, PutItem et PostWhateverYouWant sont tous des noms valides de méthodes de point de terminaison. Vous pouvez utiliser n'importe quelle casse pour ce préfixe ; par exemple, Get, get et GET sont tous des préfixes valides pour le nom d'une méthode de point de terminaison.
  • Sa signature n'a aucune valeur de renvoi et accepte seulement les trois paramètres suivants dans l'ordre qui suit : TEndpointContext, TEndpointRequest et TEndpointResponse.
  • Delphi :
procedure MethodName(const AContext: TEndpointContext; const ARequest: TEndpointRequest; const AResponse: TEndpointResponse);
  • C++ :
void MethodName(TEndpointContext* AContext, TEndpointRequest* ARequest, TEndpointResponse* AResponse);

Si une méthode de classe de ressource ne satisfait pas toutes les exigences ci-dessus, le serveur EMS ne mappe aucun point de terminaison API sur cette méthode.

Implémentation d'une méthode de point de terminaison

Votre implémentation de méthode de point de terminaison doit remplir l'instance de TEndpointResponse qu'elle reçoit avec des données, généralement des données JSON. Vous pouvez utiliser la méthode SetValue de la propriété Body de TEndpointResponse pour remplir la réponse avec des données JSON, ou vous pouvez utiliser SetBytes ou SetStream pour écrire des données brutes dans le corps de la réponse.

Voir Tutoriel : Implémentation de votre première ressource EMS pour des exemples simples.

Méthodes de requête

Le nom d'une méthode de point de terminaison commence par le nom de la méthode de requête gérée par cette méthode de point de terminaison. Une seule méthode de point de terminaison ne peut donc pas gérer deux méthodes de requête différentes ou plus.

L'API du serveur EMS prend en charge les types de méthodes de requête suivants :

Nom Description

GET

Récupère les données.

PUT

Crée un nouvel élément et obtient son identificateur.

POST

Remplace un élément existant par de nouvelles données.

PATCH

Met à jour une partie des données d'un élément existant.

DELETE

Supprime un élément.

Suffixes de ressource

Le suffixe d'une ressource est la chaîne à la fin d'une URL de point de terminaison, juste après le nom de la ressource (en minuscules). Par exemple, si l'URL d'accès à un point de terminaison est http://example.com/ems/myresource/item/count et si le nom de la ressource est "MyResource", le suffixe de ressource de ce point de terminaison est "item/count" (ou "/item/count").

Chaque méthode de point de terminaison est directement liée à un suffixe de ressource spécifique. Lorsque vous accédez à votre ressource depuis une application client EMS, vous devez remplir la propriété ResourceSuffix de votre composant TBackendEndpoint avec la chaîne du suffixe de ressource.

Par défaut, le suffixe de ressource d'une méthode de point de terminaison est une chaîne vide. Pour assigner un autre suffixe de ressource à une méthode de point de terminaison, vous devez personnaliser le mappage de la méthode de point de terminaison ultérieurement.

Un suffixe de ressource est toujours un chemin relatif à l'URL de la ressource elle-même. Si vous assignez un suffixe de ressource commençant par une barre oblique (/) à une méthode de point de terminaison, le serveur EMS ignore la barre oblique du début. Par exemple, "/item/count" et "item/count" sont deux suffixes de ressource valides pointant vers la même URL de point de terminaison, par exemple http://example.com/ems/myresource/item/count.

Segments spéciaux pour suffixes de ressource

Un segment est une chaîne qui contient des caractères autres que des barres obliques. Un suffixe de ressource peut être composé de plusieurs segments séparés par des barres obliques. Par exemple, "item/count" contient deux segments, "item" et "count".

Les suffixes de ressource prennent en charge les segments spéciaux suivants :

Segment Description

*

Correspond à n'importe quel segment.

Par exemple, le suffixe de ressource "*/count" correspond à "foo/count" et "bar/count".

{<identifier>}

Où <identifier> peut être n'importe quel identificateur, par exemple "item" ou "key".

Correspond à n'importe quel segment et stocke le segment correspondant dans la propriété TEndpointRequest.Params avec votre identificateur comme clé et la chaîne réelle de l'URL de requête comme valeur.

Par exemple, le suffixe de ressource "{item}/bar" correspond à "foo/bar" et remplit la propriété TEndpointRequest.Params avec la paire suivante : item=foo.

Remarque : Vous pouvez également utiliser ces segments spéciaux comme des segments complets. Dans les suffixes de ressource comme "foo*/bar" ou "{foo}bar/count", le serveur EMS interprète "foo*" et "{foo}bar" comme des chaînes normales, pas comme des segments spéciaux.

Noms des points de terminaison

Le nom d'un point de terminaison est la chaîne d'affichage qui représente ce point de terminaison dans l'UI de la console EMS.

Par défaut, le nom du point de terminaison représentant une méthode de point de terminaison est le nom de cette méthode. Si vous voulez utiliser un nom différent pour votre point de terminaison, vous avez la possibilité de le personnaliser ultérieurement.

Dans une ressource, les noms des points de terminaison doivent être uniques. Si vous utilisez le même nom de point de terminaison pour deux méthodes de point de terminaison différentes, le serveur EMS ajoute un numéro à la fin des noms des points de terminaison en doublon pour qu'ils soient uniques. Par exemple, si vous avez deux méthodes de point de terminaison et que vous changez leur mappage pour que toutes deux utilisent "MyEndpoint" comme nom de point de terminaison, la première méthode de point de terminaison conservera ce nom, mais la deuxième méthode de point de terminaison prendra le nom "MyEndpoint2".

Personnalisation du mappage de vos ressources

Avant de recenser vos classes de ressource dans le serveur EMS, vous pouvez changer la manière dont vous mappez chaque classe de ressource et méthode de point de terminaison sur l'API du serveur EMS.

Vous pouvez changer les noms de ressource, les suffixes de ressource et les noms des points de terminaison. Toutefois, vous ne pouvez pas changer les méthodes de requête. Elles sont toujours définies par le préfixe du nom d'une méthode de point de terminaison.

Pour personnaliser le mappage d'une ressource, vous avez la possibilité de définir un objet attributs de ressource pour cette ressource, puis d'utiliser cet objet lorsque vous recensez votre ressource. Dans Delphi, vous pouvez sinon personnaliser le mappage de votre ressource en utilisant des attributs.

Définition d'un objet attributs de ressource

Un objet attributs de ressource est une instance de TEMSResourceAttributes.

Pour personnaliser le mappage d'une ressource en utilisant un objet attributs de ressource :

  1. Créez une instance de TEMSResourceAttributes.
  2. Remplissez les propriétés de votre objet attributs de ressource avec les mappages que vous souhaitez que votre ressource utilise.
  3. Transmettez votre objet en tant que second paramètre de RegisterResource lorsque vous recensez votre ressource.

Vous pouvez utiliser les propriétés suivantes de TEMSResourceAttributes pour personnaliser le mappage de votre ressource :

Propriété Description

ResourceName

Détermine le nom de votre ressource.

ResourceSuffix

En fonction du nom d'une méthode de point de terminaison, détermine le suffixe de ressource de cette méthode de point de terminaison.

EndPointName

En fonction du nom d'une méthode de point de terminaison, détermine le nom du point de terminaison que la méthode de point de terminaison représente.

Remarque : Vous devez seulement définir les données de mappage que vous souhaitez changer. Par exemple, si vous ne changez pas la valeur de ResourceName, le serveur EMS utilise le nom par défaut de votre ressource (qui est basé sur le nom de votre classe de ressource).

Par exemple :

  • 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";

Personnalisation du mappage de vos ressources à l'aide d'attributs (Delphi)

Pour personnaliser les données de mappage de vos classes de ressource et méthodes de point de terminaison dans Delphi, vous pouvez les annoter en utilisant les attributs suivants :

Type de membre Attribut Description

Classe de ressource

ResourceName

Détermine le nom de votre ressource.

Méthode de point de terminaison

ResourceSuffix

Détermine le suffixe de ressource de la méthode de point de terminaison.

EndPointName

Détermine le nom du point de terminaison représentant la méthode de point de terminaison.

Par exemple : 

[ResourceName('Resource')]
TMyResource = class
published
    [ResourceSuffix('{item}')]
    [EndpointName('GetItem')]
    procedure Get(const AContext: TEndpointContext; const ARequest: TEndpointRequest; const AResponse: TEndpointResponse);
end;

Recensement d'une ressource

Une fois définies votre classe de ressource et ses méthodes de point de terminaison, vous devez :

  1. Transmettre votre classe de ressource à TypeInfo pour obtenir les informations RTTI de votre classe de ressource.
  2. Transmettre les informations RTTI de votre classe de ressource au serveur EMS en utilisant RegisterResource.

Vous devez appeler RegisterResource sur la méthode Register de votre package.

Par exemple :

  • Delphi :
RegisterResource(TypeInfo(TMyResource));
  • C++ :
RegisterResource(__typeinfo(TMyResource));

Recensement d'une ressource avec un objet attributs de ressource

Si vous avez créé un objet attributs de ressource pour personnaliser les données de mappage de votre classe de ressource et ses méthodes de points de terminaison, transmettez votre objet attributs de ressource à RegisterResource en tant que second paramètre.

Par exemple :

  • Delphi :
RegisterResource(TypeInfo(TMyResource), MyResourceAttributes);
  • C++ :
RegisterResource(__typeinfo(TMyResource), MyResourceAttributes.release());

Voir aussi

Récupérée de « http://docwiki.embarcadero.com/RADStudio/Rio/f/index.php?title=Présentation_des_ressources_de_RAD_Server&oldid=212930 »