Implémentation d’un point de terminaison REST Server-Side personnalisé

Article
08/24/2015

S’applique à : Windows Azure Pack

Le côté serveur fournit un ensemble d’API REST appelées par le client pour récupérer des données et effectuer des opérations. Ces deux types d’opération appellent généralement un back-end pour obtenir les données réelles ou effectuer l’opération réelle. Le contrôleur, qui implémente l’API, est généralement un contrôleur MVC ASP.NET retournant JSON, et le back-end sera généralement l’API Gestion des services, mais peut être n’importe quel autre service accessible à partir d’un site web MVC ASP.NET.

Important

L’exemple Hello World fournit un exemple d’implémentation côté serveur.

Le ou les deux serveurs peuvent résider dans le même projet Visual Studio et sont déployés sur le même portail de gestion.

Classe contrôleur

La classe de contrôleur est une instance de l’un des ASP.NET contrôleur de classes abstraites MVC standard ou AsyncController. Il sera généralement marqué avec les attributs [RequireHttps] pour garantir que seules les connexions sécurisées sont autorisées, [OutputCache] pour interdire la mise en cache des réponses et [PortalExceptionHandler] qui est décrite dans la section Gestion des erreurs suivantes. Pour empêcher les attaques par hameçonnage, les méthodes du contrôleur sont marquées avec [HttpPost]. Cela interdit les requêtes HTTP GET tout en autorisant les requêtes HTTP POST. Ni les infrastructures côté client ni côté serveur n’imposent aucune restriction sur la façon dont les côtés serveur et côté client parlent entre eux, à l’exception de l’endroit où l’interaction avec le widget Grid du framework côté client est requise. Dans ce cas, consultez la section Retour de jeux de données suivant.

Retour de jeux de données

Un jeu de données est une liste de données à afficher par l’interface utilisateur, généralement dans une liste (vue grille). Il est différent d’une réponse standard dans laquelle l’infrastructure côté client gère la récupération et l’affichage dans une grille. Si une méthode retourne un jeu de données, généralement représenté dans l’interface utilisateur en tant que liste, il est recommandé d’utiliser la méthode Controller.JsonDataSet comme dans l’exemple suivant :

return this.JsonDataSet(listOfData);

Cela encapsule automatiquement le jeu de données listOfData dans un wrapper JSON adapté au traitement par l’infrastructure côté client. Pour plus d’informations sur l’implémentation côté client, consultez How to Display a Grid in a Windows Azure Pack Management Portal Extension.

Exécution de commandes

Les méthodes qui effectuent des commandes dans le contrôleur retournent généralement un objet JSON pour afficher l’opération exécutée. Cela peut être aussi simple qu’un succès booléen signifiant, ou aussi complexe que les données qui ont changé en raison de l’opération. Rien n’est en fait requis par les frameworks côté client ni côté serveur.

Gestion des erreurs

Les exceptions levées par le contrôleur doivent généralement être affichées à l’utilisateur pour une action ou un suivi supplémentaires. Le moyen le plus simple d’effectuer cette opération côté serveur consiste à appliquer l’attribut [PortalExceptionHandler] à votre classe. Toutes les exceptions de type PortalException seront traduites en JSON correctement modélisé, disposez du jeu de code d’erreur HTTP approprié et revenez au côté client pour faciliter l’affichage avec une notification d’erreur. Un exemple de JSON retourné sur l’erreur avec l’attribut [PortalExceptionHandler] est ci-dessous :

{
  "message": "Fake Error",
  "ErrorMessage": "Fake Error",
  "httpStatusCode": "InternalServerError",
  "operationTrackingId": null,
  "stackTrace": null,
}

Tout autre type d’exception s’affiche sous la forme d’une erreur HTTP 500 vide pour éviter d’exposer les détails internes à l’utilisateur. En outre, les traces de pile ne seront envoyées que si le portail dans lequel l’extension s’exécute a la valeur True. Cela peut être modifié dans le fichier web.config du portail de gestion. Pour plus d’informations, consultez la section Interface utilisateur pour les erreurs retournées à partir d’appels d’API.

Voir aussi

Windows extensions d’interface utilisateur du portail d’administration Azure Pack
Comment afficher une grille dans une extension du portail d’administration Azure Pack Windows
Débogage d’une extension du portail d’administration Azure Pack Windows

Partager via