Nouvelles Chroniques d'Amethyste

Penser au Sens, pas au Verbe

Microsoft Azure Api Management – I

Poster un commentaire

API Management est un service Azure pour publier des Api de façon fiables, sécurisées et aptes à monter en charge. De cette façon vous pouvez déployer et partager des services de façon industrialisée. L’ensemble de ces services est packagé dans une interface unifiées. API MANAGEMENT supporte tous types de services, qu’ils soient ou non hébergés dans Azure.

API Management se présente sous la forme d’un service de proxy pour les services que vous souhaitez mettre à disposition:

2014-10-11_14-07-55

Les applications clientes se connectent donc aux services de façon contrôlée à travers API MANAGEMENT.

Installer API MANAGEMENT c’est aussi installer une application administrative dans laquelle vous paramétrez les conditions d’accès aux API, mais aussi une interface de développement qui permettra à l’équipe de développement de tester les différents services. Concrètement l’architecture complète est la suivante:

2014-10-11_18-06-02

Un service API MANAGEMENT héberge une ou plusieurs API servis par un service Web déployé on premises ou sur Azure (cloud service, VM , Mobile Service).

On déclare des opérations. Les opérations jouent 3 rôles:

  1. documenter les appels aux Apis
  2. Déclarer la correspondance entre l’url publique qui sera consommée par les clients et l’url privée qui accède réellement au service
  3. Mise en place éventuelle du cache

Les API sont associées à une ou plusieurs opérations.

Les produits sont une collection d’API. Ils définissent la façon dont les APIs sont accessibles aux utilisateur. C’est à travers les produits que l’on accède aux Api en fournissant une clef dans l’url ou dans le header de la requête. Le produit est comme son nom l’indique: une offre commerciale. Par exemple tel produit donne une offre limité à un quota, tel autre un accès illimité…

Le produits se chargent de filtrer les appels externes et peuvent ainsi alimenter le service en statistiques. Ils gèrent également les droits d’accès sous la forme de compte ou de profil. La plupart des modes d’authentification sont pris en charge.

 

On peut rattacher des policies aux produits et c’est ce qui en fait l’intérêt. Les policies mettent en place la politique des quotas d’accès ou des politiques d’accès, ils peuvent apporter des modifications aux données émises par les services comme les transformer d’un format XML vers JSON, ils gèrent également le cache et effectuent diverses autres manipulations.

2014-10-11_18-21-10

La portée des policies peut être le produit, l’API ou bien l’opération ou une combinaison qui se cumule.

 

Partons donc à la découverte de ce service intéressant issu du rachat par Microsoft de la société Apiphany. Dans un premier temps nous allons juste jeter les bases et passer rapidement sur la plupart des options.

Un deuxième article permettra d’approfondir le sujet.

Service de test

On va créer un service de test pour la démo. Il sera hébergé dans un worker role. Voici donc ce pas très ambitieux service, mais si des gens lèvent 10 millions de dollars pour envoyer un YO, moi j’envoie mon RIB direct….

public class MathController : ApiController
{
    public int Get(int a, int b)
    {
       return a + b;
    }

    [HttpGet]
    public int Carre(int a)
    {
       return a * a;
    }
}

Le service héberge deux actions. La première additionne deux entiers, la deuxième élève un entier au carré. A chaque fois le résultat est renvoyé.

Si vous ne savez pas comment héberger un Web Api dans un worker role:

https://amethyste16.wordpress.com/2014/03/30/web-api-deux-modes-dhebergement/

 

Avant de déployer, faites F5 et testez le avec une url du type:

/Math?a=4&b=10

Qui doit afficher 14. Mon déploiement conduit à ces urls:

http://demoapimanagement.cloudapp.net/Math?a=4&b=10

http://demoapimanagement.cloudapp.net/Math/Carre?a=4

Une fois Api Manager mis en place, ces urls seront des urls privées, donc différentes de celles que l’on publiera auprès des clients du service.

Provisionner le service

Lancez votre portail puis rendez vous dans l’onglet API Management et faites NEW:

2014-10-04_14-05-33

  • Cliquer sur CREATE et renseigner le formulaire:

2014-10-04_14-07-02

Url: demoamethyste

subscription: choisissez votre abonnement

region: west europe

 

  • Faire NEXT une fois le formulaire renseigné

2014-10-04_14-10-49

  • Organization Name
    Nom utilisé dans le portail développeur et dans les mails de notification
  • Administrator email
    email qui recevra les notification
  • Advanced settings
    Le service est proposé selon plusieurs versions. La version développeur (celle par défaut) est gratuite. Mais vous n’aurez ni SLA ni HD
    En cochant cette option vous vous réservez la possibilité de choisir votre modèle de facturation dans l’étape suivante

Si vous avez coché la case précédente, l’étape suivante est disponible:

2014-10-04_14-14-55

Vous pouvez sélectionner un modèle de facturation spécifique.

Une fois le service provisionné une nouvelle instance est affichée:

2014-10-04_14-50-22

Un clic sur le détail de l’API nous amène ici:

2014-10-04_18-00-29

Prenez le temps d’explorer les différentes options avant de passer à la suite. Il est en particulier intéressant d’aller sur le tableau de bord:

2014-10-07_23-35-34

Observez l’url: https://demoamethyste.portal.azure-api.net

Il s’agit de la future url publique à partir de laquelle on va accéder aux Api en cours de configuration. Comparez là avec l’url du service.

 

Notez également que les menus Management console et Developer Portal sont identiques à ceux-ci:

2014-10-04_14-54-03

  • MANAGE
     Accès à la console de gestion
  • BROWSE
    Accès au menu développeur

 

Déclarer les APIs

Notre service est provisionné, on va y déclarer l’API précédemment déployée. Evidemment rien ne nous oblige à la déployer sous Azure.

 

Rejoignez la console de gestion (MANAGE). Dans cette copie d’écran j’ai déjà des statistiques d’utilisation, mais le votre sera vide:

2014-10-07_23-39-56

  •  Cliquer sur ADD API et renseigner le formulaire:

2014-10-08_22-47-34

On déclare le nom de l’API ainsi que l’url privée vers le service.

  • Web API Name
    Un nom qui décrit l’API. Ce nom va apparaître dans le portail développeur et administrateur.
  • Web Service Url
    Url vers le service Web que l’on a précédemment déployé
    Cette url sera masquée aux clients qui consommeront le service. L’url publique sera construite à l’étape qui suit.
  • Web API suffix
    Ici c’est le suffixe du contrôleur

L’url + préfixe doivent être uniques.

 

Cliquer ensuite sur SAVE.

Ajouter une opération

On examinera plus tard les différentes options, pour l’instant on va créer une opération en cliquant sur ADD OPERATION. On créée en général autant d’opérations que de verbes HTTP et d’actions supportés.

On va commencer par la fonction d’addition de deux nombres.

2014-10-05_13-58-25

On se rend dans l’onglet Operations et on clique sur ADD. On démarre avec l’onglet Signature.

2014-10-08_22-05-30

  • Url Template est le modèle d’url qui sera soumis par les clients du service, l’url publique du service.
  • Rewrite Url Template est l’url qui sera réellement présentée au service. Dans cet exemple elle est identique à Url Template, mais ce n’est pas obligatoire.
    Nous verrons dans le deuxième exemple comment exploiter ces deux options pour faire de la réécriture d’url.

Note: On peut se demander pourquoi faut t’il renseigner les deux zones dans ce cas. Et bien parce que je n’ai jamais réussi à le faire fonctionner sans ça! Et pourtant je sais bien que dans les tonnes de démos que j’ai pu voir, tout le monde y arrive…
Je rate certainement quelque chose, mais j’ignore quoi.

 

On se rend ensuite sur l’onglet Parameters, il arrive pré-rempli:

2014-10-05_17-50-47

On va le renseigner ainsi:

2014-10-08_22-44-34

VALUES permet de déclarer des valeurs par défaut. Si nécessaire on peut compléter avec des paramètres de requête:

2014-10-05_17-54-26

Si vous avez choisit un verbe comme POST un onglet BODY apparaît également:

2014-10-05_18-11-24

On fait SAVE pour sauvegarder.

 

Puis l’opération qui correspond à la méthode qui élève au carré:

2014-10-08_22-52-21

Noter de quelle façon on profite de la réécriture d’url. Cela permet d’utiliser des url un peu plus RestFull.

2014-10-08_22-54-20

Au final notre Api exposera les opérations qui suivent:

2014-10-08_22-55-24

Créer les produits

Si on se rend dans l’onglet PRODUCTS on verra que deux produits sont définis par défaut:

2014-10-05_18-58-35

On n’est pas obligé de les conserver et on peut définir ses propres options. Faire ADD PRODUCT:

2014-10-09_20-49-26

 

Require subscrition approval indique que toutes les requêtes seront soumises à approbation. On a un produit, il faut ajouter les API qu’il contient.

Cliquons sur le nom du produit:

2014-10-05_19-26-08

Puis sur ADD API pour ajouter les API concernées:

2014-10-09_20-53-55

 

Par défaut les produits ne sont pas publiés et ne sont accessibles qu’au groupe des administrateurs. On va donc le publier et l’ouvrir à tout le monde.

2014-10-09_20-58-51

 

On va donner une visibilité au produit à partir de l’onglet Visibility:

2014-10-05_19-33-12

Faire SAVE.

2014-10-09_21-01-07

Nous allons ajouter cette API au produit STARTER, mais avec une portée plus limité:

2014-10-09_21-04-05

 

Et maintenant on teste

API MANAGEMENT fournit un environnement de test plus pratique que lancer les url directement. C’est le portail développeur:

2014-10-09_21-47-08

Cliquons sur le lien:

2014-10-09_21-48-44

Il est possible de le personnaliser, mais nous ne le ferons pas dans ce tutoriel. Nous somme connecté comme Administrateur dans cet exemple.

Cliquons sur le menu APIS:

2014-10-10_21-20-00

Puis on sélectionne Fonctions mathématiques.

2014-10-10_21-23-15

Le formulaire affiche la documentation de la fonction sélectionnée. Nous voyons un exemple d’url pour l’appeler. La clef de souscription est un ID pour un des produits, nous verrons comment l’obtenir tout à l’heure.

L’interface fournit également des exemples de code pour faire l’appel à l’API autrement que par REST. Dans la liste on notera la présence de Curl, ce qui est bien pratique pour faire des tirs de perf. Par exemple pour C#:

2014-10-10_21-28-08

Nous disposons également d’une console de tests en cliquant sur le bouton Open Console:

2014-10-10_21-30-49

On peut tester l’API en saisissant les paramètres et ajoutant d’éventuels paramètres d’entête. La liste déroulante subscription-key permet de saisir la clef du produit à travers lequel aura lieu l’appel. Par exemple cette API est disponible dans les produits Starter et Offre de la rentrée.

2014-10-10_21-33-14

API MANAGEMENT cherche la clef de souscription tout d’abord dans l’entête puis dans l’url.

On termine en cliquant sur le bouton HTTP GET et si tout se passe bien:

2014-10-10_21-36-46

Si tout se passe pas bien vous pouvez obtenir des logs d’erreur avec l’url trouvée dans le paramètre d’entête ocp-apim-trace-location.

2014-10-10_21-39-00

Nous verrons dans le prochain article comment exploiter ces informations.

Une autre façon d’obtenir les clefs de souscription est de se rendre dans le portail administratif:

2014-10-10_21-45-45

Le portail fournit également diverses statistiques d’exploitation sur les différentes opération, produits et API:

2014-10-10_21-48-30

2014-10-10_21-49-58

 

L’API ECHO

Si vous observez le contenu de l’onglet APIs:

2014-10-05_18-43-52

On voit apparaître une API appelée ECHO. Cette API est générée par défaut avec toute instance d’API MANAGEMENT. Comme l’indique son nom elle renvoie comme un écho la requête émise.

C’est intéressant d’aller voir comment cette API est montée, par exemple ses opérations:

2014-10-05_18-47-55

Conclusions

Nous venons de voir un tour d’horizon qui a permis de mettre en place les principes de base. Nous n’avons pas encore abordé la partie la plus intéressante: les politiques d’accès (policies).

API Management est également accessible via l’Api REST. Nous n’aborderons pas cette possibilité, mais on peut trouver des informations ici:

http://alexandrebrisebois.wordpress.com/2014/08/17/powershell-module-for-the-azure-api-management-rest-apis/#more-5324

Cette option est désactivée par défaut:

2014-10-10_22-08-41

Bibliographie

Publicités

Laisser un commentaire

Entrez vos coordonnées ci-dessous ou cliquez sur une icône pour vous connecter:

Logo WordPress.com

Vous commentez à l'aide de votre compte WordPress.com. Déconnexion / Changer )

Image Twitter

Vous commentez à l'aide de votre compte Twitter. Déconnexion / Changer )

Photo Facebook

Vous commentez à l'aide de votre compte Facebook. Déconnexion / Changer )

Photo Google+

Vous commentez à l'aide de votre compte Google+. Déconnexion / Changer )

Connexion à %s