Introduction à Open Data Protocol et WCF Data Services

Un service OData expose deux types de métadonnées. Le premier est un « Service Document » relatif au protocole AtomPub que nous avons vu précédemment et qui présente les collections de ressources disponibles. Le deuxième est un document (XML) de métadonnées du service. Ce document décrit le modèle de donnée exposé en HTTP par le service : la structure des ressources, les liens entre ces ressources, les opérations de service. Le contenu de ce document utilise des termes Entity Data Model (EDM) qui sont un langage XML de description de modèles appelé ConceptualSchemaDefinitionLanguage (CSDL). L'accès à ce document se fait en rajoutant « $medatata » à l'URL root d'un service OData. Par exemple : http://monsite.com/OData.svc/$metadata.

Voici un exemple de document de métadonnées d'un service OData :

Ce document décrit trois entités exposées par le service : Product, Category et Model et trois relations les liant.

Pour chaque entité, le document décrit ses différentes composantes (propriétés, associations, etc.) :

Ce document est à un service OData ce qu'un document WSDL est à un Web Service SOAP. Il va faciliter la consommation du service par les clients en permettant aux outils de génération de code d'en extraire les métadonnées afin de générer des proxys.

OData s'appuie sur le style d'architecture REST dont un point fondamental est la notion de ressource. Chaque ressource est adressable via une URI (Uniform Resource Identifiers).

OData définit un certain nombre de règles pour la construction d'URI afin d'identifier des ressources et des métadonnées exposées par un service, ainsi qu'un ensemble d'opérateurs (passés en paramètre d'URI) permettant d'effectuer des requêtes sur celles-ci.

Les URI des services OData se découpent généralement en trois parties : l'URI root du service, un chemin d'accès aux ressources et des paramètres de requête.

Le schéma suivant présente un exemple d'URI et ses trois composantes :

I-C-2-a. URI root du service▲

I-C-2-b. Chemin de la ressource▲

Le chemin de la ressource identifie celle avec laquelle interagir. Il permet l'accès à n'importe quel élément du modèle de données exposé par le service OData (collection d'entrées, entrée unique, propriétés, liens, opération de service, etc.).

Par exemple, l'accès à l'ensemble des entrées « Category » se fera en incluant le nom de la collection à l'URI :
http://localhost:2666/AdventureWorksDataService.svc/Categories.

Après le nom d'une collection d'entrées, il est possible de spécifier entre parenthèses un filtre optionnel permettant de restreindre la réponse à une seule entrée. Dans le cas d'une entrée ayant une clef composée d'une seule propriété il est possible de n'indiquer que la valeur dans le filtre à la place du couple « nom de la propriété/valeur ».

Ainsi, dans le cas d'une entité « Category » dont l'identifiant est la propriété CategorieID, les deux URI suivantes sont équivalentes pour adresser l'entrée d'identifiant 18 de la collection « Categories » :
http://localhost:2666/AdventureWorksDataService.svc/Categories(18)
http://localhost:2666/AdventureWorksDataService.svc/Categories(CategoryID=18)

Vous pouvez ensuite ajouter le nom d'une propriété de navigation afin de, par exemple, accéder aux entités « Product » associées à une entité « Category » :
http://localhost:2666/AdventureWorksDataService.svc/Categories(18)/Products

La propriété « Products » étant elle-même une collection, vous pouvez continuer à construire l'URI en rajoutant un filtre pour accéder à un seul produit, puis rajouter une propriété de navigation, etc.

Les associations (liens) entre les entrées sont adressables de la même manière que n'importe quelle autre ressource. La règle de base pour adresser les relations est montrée dans le schéma suivant :

Par exemple, voici l'URI pour récupérer la liste des liens vers les produits associés à la catégorie d'identifiant 19 :
http://localhost:2666/AdventureWorksDataService.svc/Categories(19)/$links/Products

Et le résultat retourné :

 

Sélectionnez

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<links xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices">
  <uri>http://localhost:2666/AdventureWorksDataService.svc/Products(908)</uri>
  <uri>http://localhost:2666/AdventureWorksDataService.svc/Products(909)</uri>
  <uri>http://localhost:2666/AdventureWorksDataService.svc/Products(910)</uri>
  <uri>http://localhost:2666/AdventureWorksDataService.svc/Products(911)</uri>
  <uri>http://localhost:2666/AdventureWorksDataService.svc/Products(912)</uri>
  <uri>http://localhost:2666/AdventureWorksDataService.svc/Products(913)</uri>
  <uri>http://localhost:2666/AdventureWorksDataService.svc/Products(914)</uri>
  <uri>http://localhost:2666/AdventureWorksDataService.svc/Products(915)</uri>
  <uri>http://localhost:2666/AdventureWorksDataService.svc/Products(916)</uri>
</links>

I-C-2-c. Paramètres de requête▲

La façon la plus simple de tester un service OData est de passer un navigateur. Vous pourrez saisir une URI à requêter dans la barre d'adresse et visualiser le résultat retourné.

Le résultat d'une requête sur un service OData renvoyant par défaut un flux Atom, il faut désactiver dans le navigateur la vue utilisée pour le rendu des flux Atom/RSS afin de visualiser le XML retourné. Dans Internet Explorer cela se fait via le menu Outils/Option Internet/Contenu :

Voici par exemple le résultat retourné pour l'URI http://localhost:2666/AdventureWorksDataService.svc/Categories(1) sur un service exposant les données de la base AdventureWorks :

Bien que faciles d'utilisation, les navigateurs ne vous permettent pas d'effectuer des requêtes HTTP utilisant les verbes PUT ou DELETE, de modifier les en-têtes http ou encore de visualiser des données au format JSON.

Pour pallier ces manques, vous pouvez utiliser le logiciel Fiddler.

L'onglet RequestBuilder de Fiddler vous permet de construire des requêtes HTTP en spécifiant, par exemple, le verbe HTTP à utiliser, les valeurs de l'en-tête, le contenu du corps du message, etc.

Par exemple, voici une requête HTTP GET sur l'URI http://127.0.0.1.:2666/AdventureWorksDataService.svc/Categories(1). Nous avons ici spécifié dans l'en-tête « accept » le type MIME application/json qui indique au service OData que l'on souhaite récupérer le résultat au format JSON.

En analysant le résultat, on voit que celui-ci a bien été renvoyé au format JSON :

La création d'une nouvelle entrée au sein d'une collection se fait via une requête HTTP POST sur l'URI de la collection.

Si l'on souhaite par exemple ajouter une nouvelle catégorie à la collection « Categories », il faut poster à l'URI http://127.0.0.1.:2666/AdventureWorksDataService.svc/Categories. Le corps de la requête doit contenir la nouvelle entrée dans un format accepté par le service (Atom ou JSON). L'en-tête « content-type » indique le format de l'entrée contenue dans le corps du message (ici Atom). L'en-tête « accept » indique le format dans lequel on souhaite obtenir la réponse du service.

Le service crée la nouvelle ressource et renvoie au client une réponse contenant la nouvelle ressource (dans le format spécifié via l'en-tête « accept » de la requête) ainsi que l'URI de cette nouvelle ressource via l'en-tête « location ».

La mise à jour d'une entrée peut s'effectuer de deux manières : via une opération de fusion ou via une opération de remplacement.

Le protocole AtomPub définit la mise à jour via une requête HTTP PUT envoyée à l'URI de la ressource à modifier. Une requête HTTP PUT modifie une ressource en la remplaçant par celle spécifiée dans le corps de la requête. Le corps de la requête doit donc contenir une ressource complète avec toutes ses propriétés. Il n'est cependant pas obligatoire de spécifier les valeurs associées à ces propriétés ; si elles sont manquantes, celles-ci seront remplacées par leur valeur par défaut.

Dans certains cas il est intéressant de modifier une ressource, non pas en la remplaçant, mais en la fusionnant avec une ressource envoyée par un client. Celle-ci n'a pas besoin d'être complète (contrairement à une requête PUT). Seules les propriétés présentent dans la requête seront mises à jour côté service. Il n'existe pas de verbe HTTP correspondant à ce type de mise à jour et le protocole AtomPub ne le prend pas en charge. Ainsi, plutôt que de surcharger le verbe PUT, OData introduit un nouveau verbe : MERGE.

Voici un exemple d'utilisation où l'on met à jour une catégorie en ne spécifiant que son nouveau nom :

Il est question d'introduire le verbe PATCH au sein du protocole HTTP. Une fois finalisé, celui-ci remplacerait alors le verbe MERGE au sein d'OData afin de respecter le protocole.

Il est aussi possible de mettre à jour les propriétés d'une ressource de façon individuelles via une requête HTTP PUT sur l'URI de cette propriété. Le corps de la requête ne contient alors que la propriété et sa nouvelle valeur.

La suppression d'une entrée se fait en envoyant une requête HTTP DELETE sur l'URI de l'entrée en question. Dans le cas où celle-ci est liée à d'autres entrées, il revient au service de décider si la suppression s'effectue en cascade ou non.

Les associations entre entrées sont elles aussi modifiables. Il est possible de modifier un lien de deux manières : en modifiant une entrée ou en modifiant directement le lien.

Voici un exemple où l'on modifie la catégorie d'un produit directement via l'URI de l'association. L'association entre le produit d'identifiant 680 et sa catégorie est adressable via l'URI /Products(680)/$links/Category.

Une requête HTTP GET sur l'URI de l'association indique que le produit est lié à la catégorie d'identifiant 18 :

Pour associer dorénavant ce produit à la catégorie d'identifiant 1, il suffit d'envoyer une requête HTTP PUT contenant la nouvelle valeur pour cette association sur l'URI de l'association.

Si l'on renvoie une requête HTTP GET sur l'URI de l'association, nous obtenons le résultat suivant, indiquant que le produit a bien changé de catégorie :

La création et la suppression d'associations s'effectuent de la même manière via des requêtes HTTP POST et DELETE.

Un service de données est une classe héritant de la classe générique DataService dont le type est celui de la source de données (ici notre model Entity Framework).

La méthode InitializeService vous permet de configurer le service. Cette méthode fournit en paramètre un objet de type DataServiceConfiguration contenant les paramètres de configuration du service.

II-B-1-a. Droits d'accès▲

config.SetEntitySetAccessRule("Products", EntitySetRights.All);
config.SetEntitySetAccessRule("Categories", EntitySetRights.AllRead);
config.SetEntitySetAccessRule("Models", EntitySetRights.None);

II-B-1-b. Pagination▲

La méthode SetEntitySetPageSize permet d'activer la pagination en limitant le nombre de résultats retournés par une requête cliente.

L'exemple suivant limite à 10 le nombre de produits pouvant être retournés par n'importe quelle requête cliente :

 

Sélectionnez

config.SetEntitySetPageSize("Products", 10);

Si un client effectue une requête retournant plus de 10 produits alors le service renverra les 10 premiers produits ainsi qu'un lien vers les 10 suivants.

Par exemple, une requête sur l'URI http://localhost:2666/AdventureWorksDataService.svc/Products renverra le résultat suivant:

Seules dix entrées sont retournées ainsi qu'un lien permettant d'obtenir les dix suivantes.

Il existe de nombreux autres paramètres de configuration pour lesquels vous trouverez plus d'information sur la MSDN.

WCF Data Services vous permet de définir des intercepteurs au niveau des requêtes effectuées sur le service. Vous pouvez, par exemple, valider des paramètres d'entrée, modifier les requêtes d'origine, définir des restrictions d'accès, définir des règles métier, etc.

Les intercepteurs agissent au niveau des entités exposées par le service. Il existe deux types d'intercepteurs : les « queryinterceptors » qui agissent sur les requêtes HTTP GET (lecture de données) et les « change interceptors » qui agissent sur les requêtes modifiant des données.

Les « queryinterceptors » possèdent l'attribut QueryInterceptor et retournent une expression lambda permettant d'évaluer si une entité peut faire partie du résultat renvoyé par la requête cliente.

Voici un exemple de « queryinterceptor » pour la collection des catégories :

// On définit un intercepteur pour la collection Categories.
[QueryInterceptor("Categories")]
public Expression<Func<Category, bool>> OnQueryCategories()
{
    // on ne renvoie une catégorie que si elle a au moins un produit attaché
    return c => c.Products.Any();
}

Seules les catégories ayant au moins un produit associé seront exposées par le service et renvoyées suite à des requêtes HTTP GET.

Si l'on tente d'accéder directement via son URI à une catégorie ne possédant pas de produit associé (par exemple /AdventureWorksDataService.svc/Categories(1)) nous obtenons une erreur 404 Not Found ainsi qu'un message d'erreur :

Les « change interceptors » sont des méthodes avec l'attribut ChangeInterceptor ne retournant rien et prenant deux paramètres. Le premier correspond à l'entité qui va être modifiée (sa valeur correspond aux informations envoyées par la requête HTTP). Le deuxième est une énumération de type UpdateOperation et indique le type d'opération en cours sur l'entité (ajout, modification, suppression).

Voici un exemple de « change interceptor » agissant sur la collection des produits :

// On définit un change interceptor pour la collection Products.
[ChangeInterceptor("Products")]
public void OnChangeProducts(Product product, UpdateOperations operations)
{
    if (operations == UpdateOperations.Change)
    {
        // On rejette les changements sur les produits abandonnés
        using (AdventureWorksEntities ctx = new AdventureWorksEntities())
        {
            Product originalProduct = ctx.Products.Where(p => p.ProductID == product.ProductID).First();

            // On rejette les changements sur les produits abandonnés
            if (originalProduct.DiscontinuedDate != null)
            {
                throw new DataServiceException(400,
                            "A discontinued product cannot be modified");
            }
        }
    }
    else if (operations == UpdateOperations.Delete)
    {
        // On rejette la suppression. On ne peut pas supprimer un produit, seulement lui mettre une date d'arrêt de commercialisation.
        throw new DataServiceException(400,
            "Products cannot be deleted; instead set the DiscontinuedDate property");
    }
}

Ce « change interceptor » permet de mettre en place deux règles métier en interceptant toutes les requêtes clientes agissant sur les produits : la non-modification d'un produit dont la commercialisation a été abandonnée (propriété DiscontinuedDate non null) et le fait de ne pas pouvoir supprimer un produit (seulement le marquer comme étant abandonné via la propriété DiscontinuedDate).

Ainsi, une requête HTTP DELETE sur l'URI /AdventureWorksDataService.svc/Products(680) renverra une erreur 400 Bad Request ainsi que le message d'erreur défini dans l'intercepteur :

Les opérations de service sont des méthodes que vous pouvez exposer via un service WCF Data Services. Elles sont adressables via une URI comme n'importe quelle ressource du service.

Les opérations de service sont annotées par l'attribut [WebGet] pour celles adressables via une requête HTTP GET et par l'attribut [WebInvoke] pour celles adressables via une requête HTTP POST.

Des paramètres de type simple uniquement peuvent être spécifiés pour les opérations de service. Celles-ci peuvent retourner void (Nothing en VB.NET), IEnumerable, IQueryable, une entité du modèle de donnée ou un type primitif. Retourner IQueryable permet de supporter des options de requête (pagination, filtre, etc.) et de naviguer via les propriétés de navigation des entités retournées.

L'exemple d'opération de service ci-dessous permet d'obtenir un ensemble de cinq produits recommandés en fonction du type de personne passé en paramètre (fille ou garçon) :

// Opération de service
[WebGet]
public IQueryable<Product> GetRecommendedProductsByGender(string gender)
{
    if (string.IsNullOrEmpty(gender))
    {
        throw new ArgumentNullException("gender",
            "You must provide a value for the parameter'gender'.");
    }

    if (gender != "boy" && gender != "girl")
    {
        throw new ArgumentException("Bad value for the parameter 'gender'.", "gender");
    }

    try
    {
        string color = gender == "boy" ? "black" : "red";
        var products = from product in this.CurrentDataSource.Products
                                where product.Color == color
                                && product.DiscontinuedDate == null
                                orderby product.ListPrice descending
                                select product;

        return products.Take(5);
    }
    catch (Exception ex)
    {
        throw new ApplicationException("An error occured: {0}", ex);
    }
}

La propriété CurrentDataSource représente la source de données associée au service (dans notre cas, le modèle Entity Framework).

La visibilité des opérations de service est contrôlée lors de l'initialisation du service (méthode InitializeService) via la méthode SetServiceOperationAccessRule:

config.SetServiceOperationAccessRule("GetRecommendedProductsByGender", ServiceOperationRights.AllRead);

Par exemple, une requête HTTP GET dans un navigateur sur l'URI /AdventureWorksDataService.svc/GetRecommendedProductsByGender?gender='boy' renverra le résultat suivant :

L'infrastructure WCF Data Services étant basée sur http et OData étant un ensemble de conventions au-dessus de HTTP, il est possible d'utiliser les possibilités offertes par HTTP pour améliorer le service, notamment en ce qui concerne la mise en cache.

La mise en cache de données côté serveur et côté client permet d'améliorer drastiquement les performances d'un service basé sur HTTP.

La classe représentant le service (DataService) possède une méthode OnStartProcessingRequest qui est appelée avant le traitement de chaque requête. Il est possible de redéfinir cette méthode afin d'y ajouter des actions supplémentaires.

Voici un exemple de mise en place d'un cache sur la collection Categories :

// Appelée avant chaque requête
protected override void OnStartProcessingRequest(ProcessRequestArgs args)
{
    base.OnStartProcessingRequest(args);

    string[] segments = args.RequestUri.Segments;
    bool isQueryForCategory = segments[segments.Length - 1].Contains("Categories");

    string method = HttpContext.Current.Request.HttpMethod.ToUpper();

    // cache sur toutes les entités catégories
    if (method == "GET" && isQueryForCategory)
    {
        HttpCachePolicy c = HttpContext.Current.Response.Cache;
        c.SetCacheability(HttpCacheability.ServerAndPrivate);
        c.SetExpires(HttpContext.Current.Timestamp.AddSeconds(60));
        c.VaryByHeaders["Accept"] = true;
        c.VaryByHeaders["Accept-Charset"] = true;
        c.VaryByHeaders["Accept-Encoding"] = true;
        c.VaryByParams["*"] = true;
    }
}

On vérifie en premier si la requête concerne la collection Categories en inspectant l'URI adressé et s'il s'agit d'une requête HTTP GET.

La classe HttpCachePolicy permet de définir des en-têtes HTTP propres au cache.

La méthode SetCacheability permet de contrôler la valeur de l'en-tête Cache-Control. La valeur ServerAndPrivate de l'énumération HttpCacheability indique que la réponse est mise en cache côté serveur et client, mais pas au niveau des serveurs proxys.

La méthode SetExpires affecte une date et une heure absolues à l'en-tête HTTP Expires. On indique ici une durée de 60 secondes.

La propriété VaryByHeaders permet de spécifier les en-têtes qui feront varier la sortie du cache. Ainsi, pour une même URI, une version séparée de la réponse sera disponible dans le cache pour chaque type d'en-tête http spécifié.

La propriété VaryByParams spécifie les paramètres d'une requête HTTP GET ou POST qui affecteront la mise en cache. Le caractère « * » indique que l'ensemble des paramètres affecteront le cache. Ainsi, pour deux requêtes pointant vers le même URI, mais avec des paramètres différents il en résultera deux versions séparées de la réponse dans le cache.

Lors d'une requête HTTP GET sur la liste des catégories, le client recevra l'en-tête HTTP suivant :

Lorsqu'une erreur survient au niveau du service il convient d'un informer le client. Pour cela WCF Data Services fournit le type DataServiceException qui permet de lever une exception comprise par le service. Ce type permet de contrôler les informations envoyées au client.

Afin de gérer les différents types d'exceptions (ArgumentException, InvalidOperationException, exceptions personnalisées, etc.) pouvant être lancés par les composants du service et qui ne sont donc pas du type DataServiceException, WCF Data Services propose la méthode HandleException.

Celle-ci est appelée à chaque fois qu'une exception non gérée survient dans le service. Il est ainsi possible d'intercepter toute exception qui ne serait pas de type DataServiceException et de lancer une exception DataServiceException correspondante à la place.

protected override void HandleException(HandleExceptionArgs args)
{
    if (args.Exception.InnerException is ArgumentException)
    {
        ArgumentException e = (ArgumentException)
                    args.Exception.InnerException;
        args.Exception = new DataServiceException(400,
                "ErreurPropriété:" + e.ParamName,
                "Description du problème",
                "fr-FR",
                    e);
    }
    else if (args.Exception.InnerException is CustomException)
    {
        throw new DataServiceException(400, args.Exception.Message);
    }
}

Voici un exemple d'erreur au format XML que peut renvoyer un service Odata :

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<error xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">
  <code>ErreurPropriété:gender</code>
  <message xml:lang="fr-FR">Description du problème</message>
</error>