Utilisation des actions OData pour implémenter le comportement côté serveur
Protocole OData (Open Data) vous permet de définir une action de service sur un service de données. Une action de service est une opération spéciale définie sur un service de données. Les actions de service permettent d'injecter des comportements dans un modèle centré sur les données. Les actions de service vous permettent d'appeler une logique métier dans OData, où la logique doit être liée à une ressource donnée. Les actions de service diffèrent des opérations de service classiques basées sur les points de terminaison en ce qu'elles :
Sont liées aux ressources.
Contrairement aux opérations de service définies sur un point de terminaison fixe, les actions de service sont généralement liées aux ressources, aux jeux d'entités (flux) ou aux entités individuelles. Ces ressources sont connues sous le nom de paramètres de liaison. Dans WCF Data Services, les paramètres de liaison peuvent uniquement être des types d'entités et des collections de types d'entités. Des paramètres non liants peuvent également être fournis aux actions de service. Cependant, ces paramètres peuvent uniquement être de type primitif, de type complexe, ou une collection de types primitifs ou complexes. Lorsqu'une action de service est liée à une ressource, elle est exposée en tant que ressource d'action dans la sérialisation d'entité.
Ont des effets secondaires.
La logique métier appelée par une action de service affecte le système, par exemple en modifiant des données ou un état ou en appelant un autre processus métier. Les actions de service ayant toujours des effets secondaires, elles ne peuvent être appelées qu'à l'aide d'une requête POST. Contrairement aux opérations de service, les paramètres non liants sont fournis aux actions de service dans le corps du message et non dans l'URI. Ces paramètres non liants sont fournis sous forme de valeurs JavaScript Notation (JSON) dans le corps de la requête.
Ne peuvent pas être composées davantage.
Les actions de service peuvent avoir les mêmes types de retours que les opérations de service. Cependant, contrairement aux opérations de service, elles ne peuvent pas être composées davantage. Cela signifie que les options de requête du système ne peuvent pas être appliquées à une action de service.
Prenez un film numérique comme ressource. Vous pouvez effectuer plusieurs opérations avec celui-ci : extraction, évaluation/commentaire ou archivage. Ce sont des exemples d'actions pouvant être implémentées par un service de données WCF qui gère les films numériques. Les actions sont écrites dans une réponse OData qui contient une ressource sur laquelle l'action peut être appelée. Lorsqu'un utilisateur demande une ressource qui représente un film numérique, la réponse retournée par le service de données WCF contient des informations sur les actions disponibles pour cette ressource. La disponibilité d'une action dépend de l'état du service de données ou de la ressource. Par exemple, une fois qu'un film numérique est extrait, il ne peut pas être extrait par un autre utilisateur. Les clients peuvent appeler une action en indiquant simplement une URL. Par exemple, http://MyServer/MovieService.svc/Movies(6) identifie un film numérique spécifique et http://MyServer/MovieService.svc/Movies(6)/Checkout appelle l'action sur le film spécifié. Les actions vous permettent d'exposer votre modèle de service sans exposer votre modèle de données. Poursuivons avec l'exemple de service de film, vous pouvez autoriser un utilisateur à évaluer un film, mais pas à exposer directement les données d'évaluation en tant que ressource. Vous pouvez implémenter une action d'évaluation pour autoriser l'utilisateur à évaluer un film, sans accéder directement aux données d'évaluation en tant que ressource.
Implémentation d'une action
Pour implémenter une action de service, vous devez implémenter les interfaces IServiceProvider, IDataServiceActionProvider et IDataServiceInvokable. IServiceProvider permet aux services de données WCF d'obtenir votre implémentation de IDataServiceActionProvider. IDataServiceActionProvider permet aux services de données WCF de créer, rechercher, décrire et appeler des actions de service. IDataServiceInvokable vous permet d'appeler le code qui implémente le comportement des actions de service et d'obtenir le résultat, le cas échéant. N'oubliez pas que les services de données WCF sont des services WCF par appel ; une nouvelle instance du service est créée à chaque fois que le service est appelé. Assurez-vous qu'aucun travail inutile n'est effectué lors de la création du service.
IServiceProvider
IServiceProvider contient une méthode appelée GetService(Type). Cette méthode est appelée par les services de données WCF pour récupérer plusieurs fournisseurs de services, notamment des fournisseurs de services de métadonnées et des fournisseurs d'actions de service de données. Lorsqu'un fournisseur d'actions de service de données est demandé, retourne votre implémentation IDataServiceActionProvider.
IDataServiceActionProvider
IDataServiceActionProvider contient des méthodes qui vous permettent de récupérer des informations concernant les actions disponibles. Lorsque vous implémentez IDataServiceActionProvider, vous augmentez les métadonnées de votre service qui est défini par votre implémentation de IDataServiceMetadataProvider du service avec des actions et vous gérez la répartition de ces actions comme il convient.
AdvertiseServiceAction
AdvertiseServiceAction(DataServiceOperationContext, ServiceAction, Object, Boolean, ODataAction%) est appelée pour déterminer quelles sont les actions disponibles pour la ressource spécifiée. Cette méthode est appelée uniquement pour les actions qui ne sont pas toujours disponibles. Elle s'utilise pour vérifier si l'action doit être incluse dans la réponse OData en fonction de l'état de la ressource demandée ou de l'état du service. Le mode de vérification dépend entièrement de vous. Si l'opération permettant de calculer la disponibilité et la ressource active dans un flux est coûteuse en ressources, la vérification peut être ignorée et l'action publiée. Le paramètre inFeed a la valeur true si la ressource active retournée fait partie d'un flux.
CreateInvokable
CreateInvokable(DataServiceOperationContext, ServiceAction, array<Object[]) est appelée pour créer un IDataServiceInvokable contenant un délégué qui encapsule le code qui implémente le comportement de l'action. Cela crée l'instance IDataServiceInvokable, mais n'appelle pas l'action. Les actions de service de données WCF ont des effets secondaires et doivent fonctionner conjointement avec le fournisseur de mise à jour pour enregistrer ces modifications sur le disque. La méthode Invoke() est appelée par la méthode SaveChanges() du fournisseur de mise à jour.
GetServiceActions
Cette méthode retourne une collection d'instances ServiceAction qui représentent toutes les actions exposées par un service de données WCF. ServiceAction est la représentation des métadonnées d'une action, qui inclut des informations, telles que le nom d'une action, ses paramètres et son type de retour.
GetServiceActionsByBindingParameterType
Cette méthode retourne la collection de toutes les instances ServiceAction pouvant être liées au type de paramètre de liaison spécifié. En d'autres termes, les ServiceAction pouvant agir sur le type de ressource spécifié (également appelé type de paramètre de liaison). Elle s'utilise lorsque le service retourne une ressource afin d'inclure des informations sur les actions pouvant être appelées par rapport à cette ressource. Cette méthode ne doit retourner que les actions qui lient au type exact de paramètre de liaison (aucun type dérivé). Cette méthode est appelée une fois par demande par type rencontré et le résultat est mis en cache par les services de données WCF.
TryResolveServiceAction
Cette méthode recherche un ServiceAction spécifique et retourne true si ServiceAction est trouvé. Une fois trouvé, ServiceAction est retourné dans le paramètre serviceAction out.
IDataServiceInvokable
Cette interface offre un moyen d'exécuter une action de service de données WCF. Lorsque vous implémentez IDataServiceInvokable, vous êtes chargé de trois opérations :
capture et marshaling potentiel des paramètres ;
distribution des paramètres dans le code qui implémente réellement l'action lorsque la méthode Invoke() est appelée ;
stockage des résultats de la méthode Invoke() de façon à ce qu'ils puissent être récupérés en utilisant la méthode GetResult().
Les paramètres peuvent être passés en tant que jetons. En effet, il est possible d'écrire un fournisseur de services de données qui fonctionne avec des jetons qui représentent des ressources ; le cas échéant, vous devrez peut-être convertir (marshaler) ces jetons en ressources réelles avant de les distribuer à l'action réelle. Une fois le paramètre marshalé, il doit être dans un état modifiable de façon à ce que les modifications apportées à la ressource lorsque l'action est appelée soient enregistrées et écrites sur le disque.
Cette interface nécessite deux méthodes : Invoke et GetResult. Invoke appelle le délégué qui implémente le comportement de l'action et GetResult retourne le résultat de l'action.
Contrôle d'accès des actions de service
Dans Services de données WCF, la visibilité des actions de service est contrôlée par la méthode SetServiceActionAccessRule(String, ServiceActionRights) sur la classe IDataServiceConfiguration de la même manière que la visibilité des opérations de service est contrôlée à l'aide de la méthode SetServiceOperationAccessRule(String, ServiceOperationRights).
Définition des métadonnées des actions de service
À l'instar des opérations de service, les actions de service sont définies comme des éléments FunctionImport dans les métadonnées du service. L'élément FunctionImport d'une action de service contient zéro ou plusieurs éléments Parameter, qui constituent des paramètres de liaison et non liants. De plus, les attributs suivants de FunctionImport définissent le comportement de l'action de service :
IsSideEffecting
Les actions de service pouvant toujours avoir des effets secondaires, cet attribut est toujours true.
IsBindable
Les actions de service sont généralement (mais pas toujours) liées à une ressource. Lorsque cet attribut est true, le premier paramètre doit être un type d'entité ou une collection d'entités.
IsComposable
Les actions de service ne prenant pas en charge la composition de requêtes supplémentaires, cet attribut est toujours false.
Appel d'une action de service de données WCF
Les actions sont appelées en utilisant une requête POST HTTP. L'URL spécifie la ressource suivie par le nom de l'action. Les paramètres sont passés dans le corps de la requête. Par exemple, s'il existe un service appelé MovieService qui expose une action appelée Rate. Vous pouvez utiliser l'URL suivante pour appeler l'action Rate sur un film spécifique :
http://MovieServer/MovieService.svc/Movies(1)/Rate
Movies(1) indique le film que vous voulez évaluer et Rate indique l'action d'évaluation. La valeur réelle de l'évaluation sera dans la corps de la requête HTTP tel que l'illustre cet exemple :
POST http://MovieServer/MoviesService.svc/Movies(1)/Rate HTTP/1.1
Content-Type: application/json
Content-Length: 20
Host: localhost:15238
{
"rating": 4
}
Avertissement
L'exemple de code ci-dessus ne fonctionnera qu'avec les services de données WCF version 5.2 et version ultérieure qui prennent en charge le format JSON léger.Si vous utilisez une version antérieure des services de données WCF, vous devez spécifier le type de contenu détaillé JSON comme suit : application/json;odata=verbose.
Vous pouvez aussi appeler une action en utilisant le client des services de données WCF comme indiqué dans l'extrait de code suivant :
MoviesModel context = new MoviesModel (new Uri("http://MyServer/MoviesService.svc/"));
//...
context.Execute(new Uri("http://MyServer/MoviesService.svc/Movies(1)/Rate"), "POST", new BodyOperationParameter("rating",4) );
Dans l'extrait de code ci-dessus, la classe MoviesModel a été générée en utilisant Visual Studio pour ajouter une référence de service à un service de données WCF.
Voir aussi
Concepts
Développer et déployer WCF Data Services
Fournisseurs de services de données personnalisés (WCF Data Services)