PowerApps vous permet de créer des applications complètes sans code d’application traditionnel. Dans certains cas, vous devez toutefois étendre les capacités PowerApps, et les services web conviennent parfaitement à cela. Votre application peut se connecter à un service, effectuer des opérations et obtenir des données en retour. Lorsque vous souhaitez connecter un service web à PowerApps, vous inscrivez le service en tant que connecteur personnalisé. Ce processus permet à PowerApps de connaître les caractéristiques de votre API web, notamment l’authentification dont elle a besoin, les opérations qu’elle prend en charge, et les paramètres et sorties de chacune de ces opérations.

Dans cette rubrique, nous allons étudier les étapes nécessaires pour inscrire et utiliser un connecteur personnalisé, et nous utiliserons l’exemple de l’API Analyse de texte d’Azure Cognitive Services. Cette API identifie la langue, le sentiment et les phrases clés dans le texte que vous lui passez. L’image suivante montre l’interaction entre le service, le connecteur personnalisé que nous créons à partir de celui-ci et l’application qui appelle l’API.

API, connecteur personnalisé et application

Conditions préalables

  • Un compte PowerApps.
  • Un fichier OpenAPI au format JSON, une URL vers une définition OpenAPI ou une collection Postman pour votre API. Si vous ne disposez d’aucun d’entre eux, nous vous fournirons des conseils.
  • Une image à utiliser en tant qu’icône de votre connecteur personnalisé (facultatif).

Étapes du processus de connecteur personnalisé

Le processus de connecteur personnalisé comporte plusieurs étapes, décrites brièvement ci-dessous. Cet article suppose que vous disposez déjà d’une API RESTful avec un certain type d’accès authentifié. Nous allons donc nous concentrer sur les étapes 3 à 6 dans la suite de l’article. Pour obtenir un exemple des étapes 1 et 2, consultez Créer une API web personnalisée pour PowerApps.

  1. Créez une API RESTful dans le langage et la plateforme de votre choix. Pour les technologies Microsoft, nous vous recommandons une des suivantes.

    • Azure Functions
    • Azure Web Apps
    • Azure API Apps

  2. Sécurisez votre API à l’aide de l’un des mécanismes d’authentification suivants. Vous pouvez autoriser un accès non authentifié à votre API, mais nous ne le recommandons pas.

  3. Décrivez votre API selon l’une des deux méthodes standard du secteur afin que PowerApps puisse s’y connecter.

    • Un fichier OpenAPI (également appelé fichier Swagger)
    • Une collection Postman

    Vous pouvez également créer un fichier OpenAPI à l’étape 4 du processus d’inscription.

  4. Inscrivez votre connecteur personnalisé à l’aide d’un Assistant dans PowerApps, dans lequel vous fournissez une description de l’API, des détails de la sécurité et d’autres informations.

  5. Utilisez votre connecteur personnalisé dans une application. Créez une connexion à l’API dans votre application et appelez des opérations fournies par l’API comme vous appelleriez des fonctions natives dans PowerApps.

  6. Partagez votre connecteur personnalisé comme vous le faites pour d’autres connexions de données dans PowerApps. Cette étape est facultative, mais il est souvent utile de partager des connecteurs personnalisés entre plusieurs créateurs d’application.

Décrire votre API

En supposant que vous disposez d’une API avec un certain type d’accès authentifié, vous avez besoin d’une méthode pour décrire l’API afin que PowerApps puisse s’y connecter. Pour cela, vous créez un fichier OpenAPI ou une collection Postman. Vous pouvez le faire à partir de n’importe quel point de terminaison d’API REST, notamment :

  • Les API mises à la disposition du public. Exemples : Spotify, Uber, Slack, Rackspace, etc.
  • Une API que vous créez et déployez sur n’importe quel fournisseur d’hébergement cloud, notamment Azure, Amazon Web Services (AWS), Heroku, Google Cloud, etc.
  • Une API métier personnalisée déployée sur votre réseau, tant que l’API est exposée sur le réseau Internet public.

Les fichiers OpenAPI et les collections Postman utilisent des formats différents, mais sont tous deux des documents lisibles indépendants du langage qui décrivent les opérations et les paramètres de votre API :

  • Vous pouvez générer ces documents à l’aide d’une variété d’outils en fonction du langage et de la plateforme sur lesquels votre API est créée. Consultez la documentation de l’API Analyse de texte pour obtenir un exemple de fichier OpenAPI.
  • Si vous ne disposez pas de fichier OpenAPI pour votre API et que vous ne souhaitez pas en créer un, vous pouvez créer facilement un connecteur personnalisé à l’aide d’une collection Postman. Consultez Créer une collection Postman pour plus d’informations.
  • En définitive, PowerApps utilise OpenAPI en arrière-plan. Une collection Postman est ainsi analysée et convertie en fichier de définition OpenAPI.

Remarque: la taille de votre fichier doit être inférieure à 1 Mo.

Prise en main d’OpenAPI et de Postman

Inscrire votre connecteur personnalisé

Vous allez maintenant utiliser le fichier OpenAPI ou la collection Postman pour inscrire votre connecteur personnalisé dans PowerApps.

  1. Dans powerapps.com, dans le menu de gauche, sélectionnez Connexions. Sélectionnez les points de suspension (...), puis sélectionnez Gérer les connecteurs personnalisés dans le coin supérieur droit.

    Conseil : Si vous ne trouvez pas où gérer les connecteurs personnalisées dans un navigateur mobile, il peut se trouver sous un menu dans le coin supérieur gauche.

    Créer un connecteur personnalisé

  2. Sélectionnez Créer un connecteur personnalisé.

    Propriétés d’un connecteur personnalisé

  3. Dans l’onglet Général, choisissez comment vous souhaitez créer un connecteur personnalisé.

    • Télécharger un fichier OpenAPI
    • Utiliser une URL OpenAPI
    • Télécharger une collection Postman V1

    Comment créer un connecteur personnalisé

    Téléchargez une icône pour votre connecteur personnalisé. Les champs de description, d’hôte et d’URL de Base sont généralement remplis automatiquement avec les informations du fichier OpenAPI. S’ils ne sont pas remplis automatiquement, vous pouvez ajouter des informations dans ces champs. Sélectionnez Continuer.

  4. Dans l’onglet Sécurité, saisissez les éventuelles propriétés d’authentification.

    Types d’authentification

    • Le type d’authentification est rempli automatiquement en fonction de ce qui est défini dans l’objet securityDefinitions de votre OpenAPI. Voici un exemple d’OAuth2.0.

      "securityDefinitions": {
    "AAD": {
    "type": "oauth2",
    "flow": "accessCode",
    "authorizationUrl": "https://login.windows.net/common/oauth2/authorize",
    "scopes": {}
    }
},

    • Si le fichier OpenAPI n’utilise pas l’objet securityDefintions, aucune valeur supplémentaire n’est requise.

    • Lorsque vous utilisez une collection Postman, le type d’authentification n’est rempli automatiquement que lorsque vous utilisez des types d’authentification pris en charge tels qu’OAuth 2.0 ou De base.

    • Pour obtenir un exemple de configuration de l’authentification Azure Active Directory (AAD), consultez Créer une API web personnalisée pour PowerApps.

  5. Dans l’onglet Définitions, toutes les opérations définies dans votre fichier OpenAPI ou collection Postman, ainsi que les valeurs de requête et de réponse, sont remplies automatiquement. Si toutes vos opérations requises sont définies, vous pouvez passez à l’étape 6 du processus d’inscription sans apporter de modifications dans cet écran.

    Onglet Définition

    Si vous souhaitez modifier des actions existantes ou ajouter de nouvelles actions à votre connecteur personnalisé, lisez ce qui suit.

    1. Si vous souhaitez ajouter une nouvelle action qui n’existait pas dans votre fichier OpenAPI ou collection Postman, sélectionnez Nouvelle action dans le volet gauche et indiquez dans la section Général le nom, la description et la visibilité de votre opération.

    2. Dans la section Requête, sélectionnez Importer à partir de l’exemple en haut à droite. Dans le formulaire à droite, collez un exemple de requête. Des exemples de requêtes sont généralement disponibles dans la documentation de l’API, dans laquelle vous pouvez obtenir des informations pour remplir les champs Verbe, URL de la requête, En-têtes et Corps. Consultez la documentation de l’API Analyse de texte pour obtenir un exemple.

      Importer à partir de l’exemple

    3. Sélectionnez Importer pour terminer la définition de la requête. Définissez la réponse de la même manière.

  6. Lorsque toutes vos opérations sont définies, sélectionnez Créer pour créer votre connecteur personnalisé.

  7. Lorsque votre connecteur personnalisé est créé, accédez à l’onglet Test pour tester les opérations définies dans l’API. Choisissez une connexion, puis indiquez fournissez des paramètres d’entrée pour tester une opération.

    Tester un connecteur personnalisé

    Si l’appel réussit, vous obtenez une réponse valide.

    Tester une réponse d’API

Utiliser votre connecteur personnalisé

Maintenant que vous avez inscrit votre API, ajoutez le connecteur personnalisé à votre application comme vous le feriez pour toute autre source de données. Nous allons étudier ici un exemple rapide. Pour plus d’informations sur les connexions de données, consultez Ajouter une connexion de données dans PowerApps.

  1. Dans PowerApps Studio, dans le volet à droite, cliquez ou appuyez sur Ajouter une source de données.

  2. Cliquez ou appuyez sur le connecteur personnalisé que vous avez créé.

  3. Effectuez les étapes nécessaires pour vous identifier sur le service auquel vous vous connectez. Si votre API utilise l’authentification OAuth, il se peut qu’un écran de connexion s’affiche. Pour l’authentification de clé d’API, vous pouvez être invité à indiquer une valeur de clé.

  4. Appelez l’API dans votre application. Dans notre exemple, nous avons créé une application qui envoie du texte à Cognitive Services et qui reçoit en réponse un score de sentiment de 0 sur 1, que l’application affiche sous forme de pourcentage.

    • Avec ce connecteur, si vous commencez à entrez « Az » dans la barre de formule, l’API s’affiche et présente les opérations qu’elle met à votre disposition.

    • L’appel complet ressemble à ceci, dans lequel nous passons du texte à partir de la commande TextInput et où un score à afficher dans l’application est renvoyé :

      'AzureMachineLearning-TextAnalytics'.Sentiment({documents:Table({language:"en",id:"1",text:TextInput.Text})}).documents.score)

    • Nous effectuons alors quelques tâches supplémentaires dans l’application pour gérer les données renvoyées, mais celles-ci ne sont pas trop complexes.

L’application terminée ressemble à l’image suivante. Il s’agit d’une application simple, mais dotée de fonctionnalités puissantes grâce à sa capacité d’appeler Cognitive Services via un connecteur personnalisé.

Quotas et limitation

  • Consultez la page relative à la tarification PowerApps pour en savoir plus sur les quotas de création de connecteur personnalisé. Les connecteurs personnalisés partagés avec vous ne sont pas comptés dans ce quota.
  • Pour chaque connexion créée sur un connecteur personnalisé, les utilisateurs peuvent générer jusqu’à 500 requêtes par minute.

Partager votre connecteur personnalisé

Maintenant que vous disposez d’un connecteur personnalisé, vous pouvez le partager avec d’autres utilisateurs de votre organisation. N’oubliez pas que lorsque vous partagez une API, d’autres peuvent en dépendre, et la suppression d’un connecteur personnalisé supprime toutes les connexions à l’API. Si vous souhaitez fournir un connecteur à des utilisateurs en dehors de votre organisation, consultez Overview of certifying custom connectors in PowerApps (Vue d’ensemble des connecteurs personnalisés de certification dans PowerApps).

  1. Dans powerapps.com, dans le menu de gauche, sélectionnez Connexions. Sélectionnez les points de suspension (...), puis sélectionnez Gérer les connecteurs personnalisés dans le coin supérieur droit.

    Nouvelle connexion

  2. Sélectionnez les points de suspension (... ) de votre connecteur, puis sélectionnez Afficher les propriétés.

    Afficher les propriétés d’un connecteur

  3. Sélectionnez votre API, sélectionnez Share (Partager), puis saisissez les utilisateurs ou les groupes auxquels vous souhaitez accorder l’accès à votre API.

    Partager un connecteur personnalisé

  4. Sélectionnez Save (Enregistrer).

Étapes suivantes

Découvrez comment créer une collection Postman

Découvrez comment utiliser une API web ASP.NET.

Découvrez comment inscrire une API Azure Resource Manager.