Connecter Microsoft Power Apps à Azumuta avec des jetons API de périphérique

Mis à jour

Remarque : Cet article est technique ; nous vous recommandons d'impliquer une personne disposant des compétences techniques appropriées. Si vous avez des questions ou besoin d'aide pour la configuration, contactez support@azumuta.com.

Cet exemple ajoute un bouton Open work instruction dans une application canvas Microsoft Power Apps. Le bouton appelle un flux Power Automate, qui demande un jeton de session à Azumuta et le renvoie à l'application. Power Apps ouvre ensuite la consigne dans l'Azumuta App.

La clé API de l'appareil à longue durée de vie reste dans une connexion Power Platform. Le flux ne renvoie au canvas app qu'un jeton de session. Il peut permettre une connexion une seule fois dans les 60 secondes ; après la connexion, la page utilise sa session Azumuta normale. Cet exemple ouvre une consigne pour consultation via /view/, ce qui crée normalement un enregistrement de consultation. Si l'enregistrement de consultation est désactivé pour la consigne, la page ouvre plutôt un aperçu autonome.

Comment fonctionne la connexion

Power Apps calls a Power Automate flow, which uses its stored API key to request a one-use token from Azumuta. The token returns through the flow to Power Apps, which opens an operator page and signs in on a normal device.

  1. Power Apps exécute le flux quand l'utilisateur appuie sur le bouton.
  2. Power Automate appelle POST /api/v1/auth/sessionTokens avec la clé API d'intégration dans l'en-tête x-api-key et le deviceId cible et le loginIdentifier dans le corps JSON.
  3. Azumuta valide la requête et renvoie un jeton à usage unique. Le flux transmet ce jeton à Power Apps.
  4. Power Apps ouvre /view/WORK_INSTRUCTION_ID?sessionToken=.... La clé API d'intégration ne fait jamais partie de cette URL.
  5. La page Azumuta se connecte en tant qu'opérateur autorisé sur l'appareil normal, supprime le jeton de la barre d'adresse et charge la consigne et les médias.

Ouvrir d'autres pages de l'Azumuta App

Cet exemple ouvre une consigne. Le même connecteur et le même flux peuvent ouvrir d'autres pages, comme un enregistrement, une commande produit ou un spot. Changez l'URL de destination dans le bouton Power Apps et demandez un nouveau jeton à chaque fois. Voir Open Azumuta App pages from another application pour la liste des pages et leurs options.

Exemple exécuté

L'exemple a été vérifié le 16 novembre 2026 avec ces ressources :

Resource Example
Azumuta environment https://sandbox.azumuta.com
Work instruction Installing the Motor, approved Version 10
Sandbox user Test Operator
Microsoft developer environment Azumuta Power Apps Docs
Canvas app Azumuta sandbox example
Power Automate flow AzumutaOpenInstruction
Custom connector Azumuta Sandbox

Utilisez votre propre accès sandbox et votre opérateur de test lors de l'exécution des étapes. Toutes les clés, identifiants de connexion et IDs de documents ci-dessous sont des valeurs de substitution ; l'exemple ne distribue pas de crédentiels pour la sandbox.

Dans l'exemple complété, l'onglet Flows de l'application liste AzumutaOpenInstruction. Le sélecteur d'environnement se trouve en haut à droite.

Power Apps shows the Azumuta sandbox example app with AzumutaOpenInstruction linked in its Flows tab and the developer environment selected.

Avant de commencer

Vous devez disposer de :

  • Un workspace sandbox Azumuta et l'autorisation de gérer les appareils et de voir les utilisateurs.
  • L'accès à la documentation REST API intégrée du workspace.
  • Un opérateur sandbox actif avec un login identifier qui est actuellement basculé sur ce workspace.
  • Une consigne approuvée que l'opérateur peut consulter.
  • Un compte Microsoft professionnel ou scolaire, un environnement de développement Power Platform, et l'autorisation de créer un connecteur personnalisé, un cloud flow et une application canvas dans cet environnement.

Le Power Apps Developer Plan prend en charge le développement et les tests avec des connecteurs personnalisés. Inscrivez le compte qui construira et exécutera cet exemple. La création d'un environnement seule n'attribue pas à ce compte un plan Power Apps : l'application peut fonctionner en aperçu Studio alors que son lecteur publié demande encore une licence. L'adhésion au Microsoft 365 Developer Program seule est insuffisante.

Suivez les exigences actuelles de provisionnement d'environnement de Microsoft. À partir du 15 novembre 2026, l'inscription au Developer Plan ne crée plus automatiquement un environnement. Demandez à votre administrateur un environnement développeur géré, ou utilisez un environnement d'essai approprié. Les environnements gérés nécessitent une licence premium supplémentaire, même lorsqu'un maker exécute sa propre application ou son propre flux de test ; le Developer Plan gratuit n'accorde pas ces droits d'utilisation. L'utilisation en production exige également les licences Microsoft appropriées.

L'exemple exécuté a été vérifié dans un environnement développeur non géré. Microsoft prévoit la suspension de ces environnements à partir du 15 décembre 2026 et leur suppression à partir du 15 janvier 2027. Traitez-le comme un test temporaire et prévoyez un environnement licencié ou déplacez la solution avant la suspension. Voir les consignes sur le cycle de vie du Developer Plan de Microsoft.

Gardez l'application, le flux et le connecteur dans le même environnement Power Platform pendant toute la procédure.

1. Préparez deux appareils Azumuta

L'intégration et la page opérateur utilisent des appareils différents :

Device Example name Configuration Used by
API device Power Apps documentation demo Only sessiontokens:write Power Automate
Normal device Power Apps demo workstation Allows login identifier authentication; no API scopes The operator page

Créer l'appareil API d'intégration

  1. Dans Azumuta sur Web, ouvrez Management > Devices > API.
  2. Utilisez le menu jaune plus pour Add device.
  3. Entrez Power Apps documentation demo et sélectionnez Api Device comme type.
  4. Ouvrez Security. Activez Restrict this API key to a subset of operations si ce n'est pas déjà fait.
  5. Effacez les scopes ordinaires en utilisant (select all). Sous Sensitive scopes, sélectionnez Session tokens (sessiontokens:write). Laissez tous les autres scopes décochés pour cet exemple.
  6. Cliquez sur Add, puis utilisez le menu de la ligne de l'appareil pour Copy API key. Conservez-la pour la connexion Power Platform à l'étape 2.

Full access et (select all) n'incluent pas le scope sensible des jetons de session. Vous devez le sélectionner explicitement. Voir Create and manage API keys pour la gestion générale des clés.

Préparer l'appareil normal et l'utilisateur opérateur

  1. Dans Devices > Overview, ajoutez un appareil normal dédié nommé Power Apps demo workstation. Ne sélectionnez pas Api Device.
  2. Sous Security, laissez Restrict this API key to a subset of operations désactivé. Activez Allow authentication using login identifier. Limitez User groups allowed to authenticate with login identifier au groupe de l'opérateur sandbox.
  3. Enregistrez l'appareil et copiez son Device ID depuis ses détails. C'est le deviceId cible ; n'utilisez pas l'ID de l'appareil API d'intégration.
  4. Sous Management > Users, vérifiez le Login identifier de l'opérateur de test et son appartenance au groupe. Un login identifier n'est pas nécessairement l'adresse e-mail de l'opérateur ni le nom du compte Microsoft.
  5. Ouvrez la consigne approuvée dans Azumuta sur Web. Ouvrez Help (le point d'interrogation en haut à droite) > API attributes et copiez le Work instruction ID. L'Tree node ID séparé dans cette boîte de dialogue, également utilisé dans l'adresse /nodes/workinstruction/..., ne fonctionnera pas avec /view/. Voir Using your data in the REST API pour trouver les attributs API.

La restriction de scope doit être désactivée sur l'appareil cible. La laisser activée avec tous les scopes décochés configure une liste de scopes vide, que l'endpoint de jeton de session rejette. La page opérateur utilise cet appareil normal pour ses propres requêtes après connexion, y compris les téléchargements de médias.

2. Créer un connecteur personnalisé

Le connecteur stocke la clé API de l'appareil dans une connexion et l'envoie à Azumuta comme en-tête de requête. L'application canvas appellera le flux, plutôt que de recevoir cette clé.

  1. Ouvrez Power Automate et sélectionnez votre environnement de développement.

  2. Ouvrez More > Discover all. Sous Data, sélectionnez Custom connectors, puis New custom connector > Create from blank. Nommez-le Azumuta Sandbox. Si Custom connectors est déjà présent dans la navigation de gauche, ouvrez-le directement.

  3. Sous General, configurez :

    Field Value
    Scheme HTTPS
    Host sandbox.azumuta.com
    Base URL /
  4. Sous Security, sélectionnez l'authentification API Key :

    Field Value
    Parameter label Azumuta device API key
    Parameter name x-api-key
    Parameter location Header
  5. Sous Definition, ajoutez une action avec pour résumé Create session token et operation ID CreateSessionToken.

  6. Dans Request, choisissez Import from sample. Utilisez le verbe POST, l'URL https://sandbox.azumuta.com/api/v1/auth/sessionTokens, et ce corps, en remplaçant les deux valeurs par vos valeurs sandbox :

    {
      "deviceId": "NORMAL_DEVICE_ID",
      "loginIdentifier": "SANDBOX_OPERATOR_LOGIN_IDENTIFIER"
    }
    
  7. Rendez les deux propriétés du corps obligatoires. Définissez le type de contenu de la requête sur application/json. N'ajoutez pas la clé API dans le corps d'exemple, l'URL ou les paramètres de l'action.

  8. Sous Response, ajoutez une réponse par défaut en utilisant cette structure d'exemple :

    {
      "object": "sessionToken",
      "token": "EXAMPLE_ONLY_NOT_A_VALID_TOKEN",
      "expiresAt": 1794826860000
    }
    
  9. Enregistrez le connecteur et corrigez toute erreur de validation de définition.

  10. Sous Test, sélectionnez New connection et entrez la clé API de l'appareil d'intégration. Entrez la clé seule, sans préfixe Bearer. Créez la connexion.

The Azumuta Sandbox custom connector's Security page uses API Key authentication, parameter name x-api-key, and Header as the parameter location.

Pour l'assistant complet du connecteur, voir la documentation Microsoft Create a custom connector from scratch.

Une requête réellement réussie renvoie HTTP 200 avec object, token et expiresAt. L'expiration est un timestamp en millisecondes depuis l'époque Unix. Un jeton généré dans le panneau de test du connecteur est séparé du jeton que l'application demandera ensuite ; ne le sauvegardez pas pour réutilisation.

3. Construire le flux Power Automate

Pour cet exemple privé, fixez l'opérateur et l'appareil dans le flux. Le déclencheur Power Apps n'a pas besoin d'entrées. Gardez le flux restreint à la personne qui le teste : chaque appel réussi permet la connexion en tant que cet opérateur sandbox.

  1. Dans Power Automate, créez un Instant cloud flow nommé AzumutaOpenInstruction avec le trigger When Power Apps calls a flow (V2).

  2. Ajoutez l'action Create session token depuis Azumuta Sandbox, en utilisant la connexion que vous venez de créer. Si le concepteur demande une connexion, entrez un nom de connexion et la même clé API sandbox dédiée.

  3. Renommez l'action CreateSessionToken. Définissez deviceId et loginIdentifier sur les valeurs sandbox fixes de l'étape 1.

  4. Ouvrez les Settings de l'action et activez Secure inputs et Secure outputs avant de l'exécuter.

  5. Ajoutez Respond to a Power App or flow. Ajoutez une sortie Text nommée sessionToken et sélectionnez body/token depuis CreateSessionToken dans le sélecteur de contenu dynamique. Dans l'éditeur d'expression, l'équivalent est :

    body('CreateSessionToken')?['token']
    
  6. Activez Secure inputs sur l'action de réponse ; ses paramètres expliquent que cela sécurise également les outputs. Laissez Asynchronous response désactivé et la condition run-after définie sur l'exécution réussie de CreateSessionToken.

  7. Enregistrez le flux. N'ajoutez pas la clé API à la réponse.

The Power Automate designer shows When Power Apps calls a flow (V2), CreateSessionToken, and Respond to a Power App or flow in sequence.

Les entrées et sorties sécurisées masquent les valeurs sensibles dans l'historique d'exécution. Elles n'empêchent pas un propriétaire de flux de modifier le flux. Les recommandations Microsoft sur la sécurisation des données des cloud flows expliquent ces paramètres.

4. Ajouter le bouton Power Apps

  1. Dans Power Apps, sélectionnez le même environnement de développement. Choisissez Start with design > Create from blank > Tablet. Enregistrez l'application canvas sous Azumuta sandbox example.

  2. Dans Power Apps Studio, ouvrez le volet Power Automate et ajoutez le flux existant AzumutaOpenInstruction.

  3. Insérez un bouton avec le texte Open work instruction.

  4. Définissez la propriété OnSelect du bouton sur la formule suivante. Remplacez WORK_INSTRUCTION_ID par l'ID de votre consigne approuvée :

    IfError(
        With(
            { result: AzumutaOpenInstruction.Run() },
            If(
                IsBlank(result.sessiontoken),
                Notify("Azumuta did not return a session token", NotificationType.Error),
                Launch(
                    "https://sandbox.azumuta.com/view/WORK_INSTRUCTION_ID",
                    { sessionToken: result.sessiontoken },
                    LaunchTarget.New
                )
            )
        ),
        Notify("Could not open the Azumuta work instruction", NotificationType.Error)
    )
    
  5. Vérifiez le nom du champ de réponse proposé par l'autocomplétion Power Apps. Utilisez le nom généré si sa casse diffère de sessiontoken. Si le flux a été modifié après avoir été ajouté à l'application, actualisez-le ou supprimez-le puis réajoutez-le.

  6. Enregistrez l'application et prévisualisez-la. Dans les paramètres régionaux qui utilisent des points-virgules comme séparateurs d'arguments Power Fx, adaptez les séparateurs de la formule selon la locale de l'éditeur.

Après test, enregistrez et publiez la version de l'application si vous souhaitez la rouvrir via son lien web. Publier une version et accorder l'accès à d'autres personnes sont des étapes séparées ; gardez cet exemple d'identité fixe privé.

Au premier lancement, Power Apps peut demander l'autorisation de permettre à l'application d'utiliser Azumuta Sandbox via son flux Power Automate. Vérifiez que l'action listée est Create session token, puis autorisez la connexion pour votre application de test.

The published Azumuta sandbox example canvas app has an Open work instruction button.

Le flux s'exécute à chaque pression de bouton, immédiatement avant la navigation. Ne générez pas de jetons au démarrage de l'application et ne conservez pas de jeton pour rouvrir la page plus tard.

5. Vérifier l'exemple complet

  1. En aperçu de l'application, cliquez sur Open work instruction et autorisez l'ouverture d'un nouvel onglet si le navigateur le demande.
  2. Confirmez que la consigne s'ouvre en tant qu'opérateur sandbox prévu sur Power Apps demo workstation. Vérifiez le texte et les médias.
  3. Vérifiez la barre d'adresse : Azumuta supprime sessionToken après l'avoir lu. L'URL de lancement ne doit contenir aucun apiKey, deviceId ni loginIdentifier.
  4. Inspectez l'exécution du flux. Elle doit réussir, avec les inputs et outputs portant le jeton masqués.
  5. Cliquez à nouveau sur le bouton Power Apps. Il doit demander un nouveau jeton et rouvrir la page.
  6. Pour un test de rejouabilité distinct, ouvrez l'onglet Test du connecteur personnalisé. Entrez le deviceId de l'appareil normal et le loginIdentifier de l'opérateur de test, puis sélectionnez Test operation. Utilisez le token retourné pour construire https://sandbox.azumuta.com/view/WORK_INSTRUCTION_ID?sessionToken=DISPOSABLE_TOKEN, en substituant votre ID de consigne et ce jeton jetable. Ouvrez cette URL exacte deux fois dans des onglets neufs. Seule la première connexion doit réussir. Un rechargement de l'onglet déjà connecté peut reprendre cette session ; ce n'est pas un test de rejouabilité.
  7. Utilisez Test operation à nouveau pour générer un autre jeton jetable, laissez-le inutilisé plus de 60 secondes, et ouvrez son URL dans un onglet neuf. La connexion doit échouer. Cliquez sur le bouton Power Apps pour demander un nouveau jeton. Conservez les entrées et sorties sécurisées du flux activées pendant ces tests.

Ne consignez pas les valeurs de jeton dans des captures d'écran, des exemples d'article ou des notes de test partagées.

Dans l'exemple vérifié, le bouton canvas a ouvert Installing the Motor, Version 10, et les images se sont chargées, à la fois en aperçu Studio et depuis le lecteur de l'application publiée. Le flux a réussi avec les inputs et outputs portant le jeton masqués. La tentative de rejouer un jeton consommé a renvoyé 403 Access denied ; l'ouverture d'un jeton inutilisé après son expiration a renvoyé 403 Expired.

Dépannage

Symptom Check
HTTP 401 La clé API de la connexion et l'hôte sandbox correspondent ; la clé est envoyée dans l'en-tête x-api-key
HTTP 403 mentioning sessiontokens:write L'appareil API a des scopes explicites et Session tokens sélectionné ; full access est insuffisant
HTTP 400 about the target device deviceId désigne un appareil normal, sans scopes API et avec l'authentification par login identifier activée
HTTP 400 about the user L'opérateur est actif et actuellement basculé sur le même workspace
HTTP 403 about user groups L'opérateur appartient à un groupe autorisé sur l'appareil cible
HTTP 404 L'appareil normal et le login identifier de l'opérateur existent dans le workspace de la clé API
Page sign-in fails Demandez un jeton frais et naviguez immédiatement ; les jetons expirés ou consommés ne sont pas réutilisables
Work instruction or media does not load Vérifiez la consigne approuvée, l'accès opérateur et la configuration de l'appareil cible ; conservez les scopes API uniquement sur l'appareil d'intégration
Flow or custom action does not appear Vérifiez que toutes les ressources sont dans le même environnement Power Platform ; laissez les modifications du connecteur se propager, puis actualisez
Published app asks to start a Power Apps trial Vérifiez l'entitlement Power Apps du compte connecté ; disposer d'un environnement développeur et d'un aperçu Studio réussi ne suffit pas

Adapter l'exemple

Pour une application de production, remplacez l'identité de test fixe par un mappage validé côté serveur entre l'appelant Microsoft authentifié et l'opérateur Azumuta autorisé. N'acceptez pas un loginIdentifier ou un deviceId non restreint depuis un champ texte du canvas : la clé de l'appareil autorise l'intégration, pas la personne exécutant l'application. Restreignez qui peut exécuter et éditer le flux, et prévoyez les licences Microsoft requises avant de le partager.

Pour une autre opération REST, ajoutez cette action au connecteur et accordez seulement ses scopes API documentés. Continuez d'envoyer la clé dans l'en-tête. Utilisez la REST API documentation du workspace pour les détails des requêtes et des réponses.

Lorsque l'exemple n'est plus nécessaire, désactivez le flux et révoquez ses identifiants sandbox via la gestion des appareils API de votre workspace.