Verbinden Sie Microsoft Power Apps mit Azumuta per Geräte-API-Token

Aktualisiert

Hinweis: Dieser Artikel ist technisch; wir empfehlen, eine Person mit der passenden technischen Fachkenntnis hinzuzuziehen. Wenn Sie Fragen haben oder Hilfe bei der Einrichtung benötigen, kontaktieren Sie support@azumuta.com.

Dieses Beispiel fügt einer Microsoft Power Apps Canvas-App einen Button Arbeitsanweisung öffnen hinzu. Der Button ruft einen Power Automate-Flow auf, der von Azumuta ein Session-Token anfordert und es an die App zurückgibt. Power Apps öffnet anschließend die Arbeitsanweisung in der Azumuta App.

Der langlebige Geräte-API-Schlüssel verbleibt in einer Power Platform-Verbindung. Der Flow liefert der Canvas-App nur ein Session-Token zurück. Dieses kann sich innerhalb von 60 Sekunden einmal anmelden; nach der Anmeldung verwendet die Seite die normale Azumuta-Session. Dieses Beispiel öffnet eine Arbeitsanweisung zur Betrachtung über /view/, was normalerweise eine Konsultationsaufzeichnung erzeugt. Wenn die Konsultationsaufzeichnung für die Anweisung deaktiviert ist, öffnet die Seite stattdessen eine eigenständige Vorschau.

Wie die Verbindung funktioniert

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 führt den Flow aus, wenn der Benutzer den Button drückt.
  2. Power Automate ruft POST /api/v1/auth/sessionTokens mit dem Integrations-API-Schlüssel im x-api-key-Header sowie dem Ziel-deviceId und loginIdentifier im JSON-Body auf.
  3. Azumuta validiert die Anfrage und liefert ein einmalig verwendbares Token zurück. Der Flow gibt dieses Token an Power Apps weiter.
  4. Power Apps öffnet /view/WORK_INSTRUCTION_ID?sessionToken=.... Der Integrations-API-Schlüssel ist niemals Teil dieser URL.
  5. Die Azumuta-Seite meldet sich als der erlaubte Operator auf dem normalen Gerät an, entfernt das Token aus der Adresszeile und lädt die Arbeitsanweisung und Medien.

Andere Azumuta App-Seiten öffnen

Dieses Beispiel öffnet eine Arbeitsanweisung. Derselbe Connector und Flow können auch andere Seiten öffnen, z. B. eine Aufzeichnung, eine Produktbestellung oder einen Spot. Ändern Sie die Ziel-URL im Power Apps-Button und fordern Sie jedes Mal ein neues Token an. Siehe Open Azumuta App pages from another application für die verfügbaren Seiten und deren Optionen.

Das laufende Beispiel

Das Beispiel wurde am 16. November 2026 mit folgenden Ressourcen verifiziert:

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

Verwenden Sie beim Befolgen der Schritte Ihren eigenen Sandbox-Zugang und Ihren Testoperator. Alle unten aufgeführten Schlüssel, Login-Identifiers und Dokument-IDs sind Platzhalter; das Beispiel verteilt keine Zugangsdaten für die Sandbox.

Im fertigen Beispiel listet der App-Reiter Flows AzumutaOpenInstruction. Der Umgebungswähler befindet sich in der oberen rechten Ecke.

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

Bevor Sie beginnen

Sie benötigen:

  • Einen Azumuta-Sandbox-Arbeitsbereich und Berechtigungen zum Verwalten von Geräten und Anzeigen von Benutzern.
  • Zugriff auf die In-App-REST-API-Dokumentation des Arbeitsbereichs.
  • Einen aktiven Sandbox-Operator mit einem Login-Identifier, der gerade auf diesen Arbeitsbereich gewechselt hat.
  • Eine genehmigte Arbeitsanweisung, die der Operator konsultieren kann.
  • Ein Microsoft Arbeits- oder Schulkonto, eine Power Platform-Entwicklungsumgebung und Berechtigungen zum Erstellen eines benutzerdefinierten Connectors, eines Cloud-Flows und einer Canvas-App in dieser Umgebung.

Der Power Apps Developer Plan unterstützt Entwicklung und Tests mit benutzerdefinierten Connectors. Melden Sie das Konto an, das dieses Beispiel erstellen und ausführen wird. Das bloße Erstellen einer Umgebung weist diesem Konto keinen Power Apps-Plan zu: die App kann zwar in der Studio-Vorschau funktionieren, während der veröffentlichte Player weiterhin eine Lizenz verlangt. Eine Mitgliedschaft im Microsoft 365 Developer Program allein ist nicht ausreichend.

Befolgen Sie die aktuellen Anforderungen zur Bereitstellung von Umgebungen von Microsoft. Ab dem 15. November 2026 erstellt die Developer-Plan-Anmeldung keine Umgebung mehr automatisch. Bitten Sie Ihren Administrator um eine verwaltete Entwicklerumgebung oder verwenden Sie eine geeignete Testumgebung. Verwaltete Umgebungen erfordern eine zusätzliche Premium-Lizenz, selbst wenn ein Creator eine eigene Test-App oder einen Flow betreibt; der kostenlose Developer Plan beinhaltet diese Nutzungsrechte nicht. Für den Produktionseinsatz sind ebenfalls passende Microsoft-Lizenzen erforderlich.

Das laufende Beispiel wurde in einer unverwalteten Entwicklerumgebung verifiziert. Microsoft plant, diese Umgebungen ab 15. Dezember 2026 zu pausieren und ab 15. Januar 2027 zu löschen. Behandeln Sie sie als temporäre Tests und richten Sie rechtzeitig eine lizenzierte Umgebung ein oder verschieben Sie die Lösung vor der Stilllegung. Siehe die Developer Plan lifecycle guidance von Microsoft.

Behalten Sie App, Flow und Connector während der gesamten Prozedur in derselben Power Platform-Umgebung.

1. Zwei Azumuta-Geräte vorbereiten

Die Integration und die Operator-Seite verwenden unterschiedliche Geräte:

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

Integration-API-Gerät erstellen

  1. Öffnen Sie in Azumuta im Web Management > Devices > API.
  2. Verwenden Sie das gelbe Plus-Menü, um Add device zu wählen.
  3. Geben Sie Power Apps documentation demo ein und wählen Sie als Typ Api Device.
  4. Öffnen Sie Security. Aktivieren Sie Restrict this API key to a subset of operations, falls noch nicht aktiviert.
  5. Entfernen Sie die normalen Scopes mit (select all). Wählen Sie unter Sensitive scopes Session tokens (sessiontokens:write). Für dieses Beispiel lassen Sie alle anderen Scopes nicht ausgewählt.
  6. Klicken Sie auf Add und verwenden Sie dann das Zeilenmenü des Geräts, um Copy API key zu wählen. Bewahren Sie diesen Schlüssel für die Power Platform-Verbindung in Schritt 2 auf.

Full access und (select all) schließen den sensiblen Session-Token-Scope nicht ein. Sie müssen diesen explizit auswählen. Siehe Create and manage API keys für allgemeine Schlüsselverwaltung.

Operator-Gerät und Benutzer vorbereiten

  1. Fügen Sie unter Devices > Overview ein dediziertes normales Gerät namens Power Apps demo workstation hinzu. Wählen Sie Api Device nicht aus.
  2. Unter Security lassen Sie Restrict this API key to a subset of operations ausgeschaltet. Aktivieren Sie Allow authentication using login identifier. Beschränken Sie User groups allowed to authenticate with login identifier auf die Gruppe des Sandbox-Operators.
  3. Speichern Sie das Gerät und kopieren Sie seine Device ID aus den Details. Dies ist die Ziel-deviceId; verwenden Sie nicht die ID des Integrations-API-Geräts.
  4. Unter Management > Users prüfen Sie den Login identifier des Testoperators und seine Gruppenmitgliedschaft. Ein Login-Identifier ist nicht notwendigerweise die E-Mail-Adresse oder der Microsoft-Kontoname des Operators.
  5. Öffnen Sie die genehmigte Arbeitsanweisung in Azumuta im Web. Öffnen Sie Help (das Fragezeichen oben rechts) > API attributes und kopieren Sie Work instruction ID. Die separate Tree node ID in diesem Dialog, die auch in der Adresse /nodes/workinstruction/... verwendet wird, funktioniert nicht in /view/. Siehe Using your data in the REST API zum Auffinden von API-Attributen.

Die Scope-Einschränkung muss auf dem Zielgerät deaktiviert sein. Wenn sie eingeschaltet ist und alle Scopes abgewählt sind, konfiguriert das eine leere Scope-Liste, die vom Session-Token-Endpunkt abgelehnt wird. Die Operator-Seite verwendet dieses normale Gerät für eigene Anfragen nach der Anmeldung, einschließlich Medien-Downloads.

2. Einen Custom Connector erstellen

Der Connector speichert den Geräte-API-Schlüssel in einer Verbindung und sendet ihn an Azumuta als Request-Header. Die Canvas-App ruft später den Flow auf, statt diesen Schlüssel zu erhalten.

  1. Öffnen Sie Power Automate und wählen Sie Ihre Entwicklungsumgebung.

  2. Öffnen Sie More > Discover all. Wählen Sie unter Data Custom connectors, dann New custom connector > Create from blank. Benennen Sie ihn Azumuta Sandbox. Falls Custom connectors bereits in der linken Navigation sichtbar ist, öffnen Sie es direkt.

  3. Unter General konfigurieren Sie:

    Field Value
    Scheme HTTPS
    Host sandbox.azumuta.com
    Base URL /
  4. Unter Security wählen Sie API Key-Authentifizierung:

    Field Value
    Parameter label Azumuta device API key
    Parameter name x-api-key
    Parameter location Header
  5. Unter Definition fügen Sie eine Aktion mit Summary Create session token und Operation ID CreateSessionToken hinzu.

  6. In Request wählen Sie Import from sample. Verwenden Sie Verb POST, URL https://sandbox.azumuta.com/api/v1/auth/sessionTokens und diesen Body; ersetzen Sie beide Werte durch Ihre Sandbox-Werte:

    {
      "deviceId": "NORMAL_DEVICE_ID",
      "loginIdentifier": "SANDBOX_OPERATOR_LOGIN_IDENTIFIER"
    }
    
  7. Machen Sie beide Body-Eigenschaften erforderlich. Setzen Sie den Request-Content-Type auf application/json. Fügen Sie den API-Schlüssel nicht in den Sample-Body, die URL oder die Action-Parameter ein.

  8. Unter Response fügen Sie eine Default-Response mit dieser Beispielstruktur hinzu:

    {
      "object": "sessionToken",
      "token": "EXAMPLE_ONLY_NOT_A_VALID_TOKEN",
      "expiresAt": 1794826860000
    }
    
  9. Speichern Sie den Connector und beheben Sie etwaige Validierungsfehler in der Definition.

  10. Unter Test wählen Sie New connection und geben den API-Schlüssel des Integrationsgeräts ein. Geben Sie den Schlüssel allein ein, ohne Bearer-Präfix. Erstellen Sie die Verbindung.

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

Für den kompletten Connector-Assistenten siehe Microsofts Anleitung Create a custom connector from scratch.

Eine tatsächlich erfolgreiche Anfrage liefert HTTP 200 mit object, token und expiresAt. Die Ablaufzeit ist ein Zeitstempel in Millisekunden seit der Unix-Epoche. Ein im Testpanel des Connectors erzeugtes Token ist unabhängig von dem Token, das die App später anfordert; speichern Sie es nicht zur Wiederverwendung.

3. Den Power Automate-Flow erstellen

Für dieses private Beispiel fixieren Sie Operator und Gerät im Flow. Der Power Apps-Trigger benötigt keine Eingaben. Beschränken Sie den Flow auf die testende Person: jeder erfolgreiche Aufruf erlaubt die Anmeldung als dieser Sandbox-Operator.

  1. Erstellen Sie in Power Automate einen Instant cloud flow namens AzumutaOpenInstruction mit dem Trigger When Power Apps calls a flow (V2).

  2. Fügen Sie die Aktion Create session token von Azumuta Sandbox hinzu und verwenden Sie die soeben erstellte Verbindung. Falls der Designer nach einer Verbindung fragt, geben Sie einen Verbindungsnamen und denselben dedizierten Sandbox-API-Schlüssel dort ein.

  3. Benennen Sie die Aktion in CreateSessionToken um. Setzen Sie deviceId und loginIdentifier auf die fixen Sandbox-Werte aus Schritt 1.

  4. Öffnen Sie die Settings der Aktion und aktivieren Sie Secure inputs und Secure outputs, bevor Sie sie ausführen.

  5. Fügen Sie Respond to a Power App or flow hinzu. Fügen Sie eine Text-Ausgabe namens sessionToken hinzu und wählen Sie body/token aus CreateSessionToken im Dynamic Content Picker. Im Ausdruckseditor ist das Äquivalent:

    body('CreateSessionToken')?['token']
    
  6. Aktivieren Sie Secure inputs für die Response-Aktion; dessen Einstellungen erklären, dass dadurch auch die Outputs geschützt werden. Lassen Sie Asynchronous response ausgeschaltet und die Run-After-Bedingung auf die erfolgreiche Ausführung von CreateSessionToken gesetzt.

  7. Speichern Sie den Flow. Fügen Sie den API-Schlüssel nicht zur Response hinzu.

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

Secure inputs und outputs verbergen sensible Werte in der Run-History. Sie verhindern nicht, dass ein Flow-Eigentümer den Flow bearbeitet. Microsofts Guidance on securing cloud-flow data erklärt diese Einstellungen.

4. Den Power Apps-Button hinzufügen

  1. In Power Apps wählen Sie dieselbe Entwicklungsumgebung. Wählen Sie Start with design > Create from blank > Tablet. Speichern Sie die Canvas-App als Azumuta sandbox example.

  2. Öffnen Sie in Power Apps Studio das Power Automate-Fenster und fügen Sie den vorhandenen Flow AzumutaOpenInstruction hinzu.

  3. Fügen Sie einen Button mit der Beschriftung Arbeitsanweisung öffnen ein.

  4. Setzen Sie die OnSelect-Eigenschaft des Buttons auf die folgende Formel. Ersetzen Sie WORK_INSTRUCTION_ID durch die ID Ihrer genehmigten Arbeitsanweisung:

    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. Prüfen Sie den von Power Apps vorgeschlagenen Namen des Response-Felds. Verwenden Sie den generierten Namen, falls dessen Groß-/Kleinschreibung von sessiontoken abweicht. Falls der Flow nach dem Hinzufügen zur App geändert wurde, aktualisieren Sie ihn oder entfernen und fügen Sie den Flow erneut hinzu.

  6. Speichern Sie die App und testen Sie sie in der Vorschau. In Sprachregionen, die Semikolons als Power Fx-Argumenttrenner verwenden, passen Sie die Formel entsprechend an die Editor-Lokalisierung an.

Nach dem Testen speichern und veröffentlichen Sie die App-Version, wenn Sie sie über ihren Weblink erneut öffnen möchten. Das Veröffentlichen einer Version und das Gewähren von Zugriffsrechten sind getrennte Schritte; halten Sie dieses Beispiel mit fester Identität privat.

Beim ersten Start kann Power Apps verlangen, dass die App Azumuta Sandbox über ihren Power Automate-Flow verwenden darf. Prüfen Sie, dass die aufgelistete Aktion Create session token ist, und erlauben Sie die Verbindung für Ihre Test-App.

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

Der Flow läuft bei jedem Buttondruck, unmittelbar vor der Navigation. Generieren Sie Tokens nicht beim App-Start und bewahren Sie kein Token auf, um die Seite später erneut zu öffnen.

5. Das komplette Beispiel verifizieren

  1. Klicken Sie in der App-Vorschau auf Arbeitsanweisung öffnen und erlauben Sie ggf. den neuen Browser-Tab.
  2. Bestätigen Sie, dass die Arbeitsanweisung als der beabsichtigte Sandbox-Operator auf Power Apps demo workstation geöffnet wird. Prüfen Sie Text und Medien.
  3. Prüfen Sie die Adresszeile: Azumuta entfernt sessionToken nach dem Lesen. Die Start-URL darf keine apiKey, deviceId oder loginIdentifier enthalten.
  4. Untersuchen Sie den Flow-Run. Er sollte erfolgreich sein, wobei die tokenführenden Action-Inputs und -Outputs verborgen sind.
  5. Klicken Sie den Power Apps-Button erneut. Er sollte ein frisches Token anfordern und die Seite wieder öffnen.
  6. Für einen separaten Replay-Test öffnen Sie den Test-Tab des Custom Connectors. Geben Sie die deviceId des normalen Geräts und den loginIdentifier des Testoperators ein und wählen Sie Test operation. Verwenden Sie das zurückgegebene token, um https://sandbox.azumuta.com/view/WORK_INSTRUCTION_ID?sessionToken=DISPOSABLE_TOKEN zu konstruieren, wobei Sie Ihre Instruction-ID und dieses Einmal-Token einsetzen. Öffnen Sie diese exakte URL zweimal in neuen Tabs. Nur die erste Anmeldung sollte erfolgreich sein. Ein Neuladen des bereits eingeloggten Tabs kann diese Session wieder aufnehmen; das ist kein Replay-Test.
  7. Verwenden Sie Test operation erneut, um ein weiteres Einmal-Token zu generieren, lassen Sie es länger als 60 Sekunden ungenutzt und öffnen Sie seine URL in einem frischen Tab. Die Anmeldung sollte fehlschlagen. Klicken Sie den Power Apps-Button, um ein neues Token anzufordern. Lassen Sie die Secure inputs und outputs des Flows während dieser Tests aktiviert.

Zeichnen Sie Token-Werte nicht in Screenshots, Artikelbeispielen oder gemeinsamen Testnotizen auf.

Im verifizierten Beispiel öffnete der Canvas-Button Installing the Motor, Version 10 und die Bilder wurden geladen, sowohl in der Studio-Vorschau als auch im veröffentlichten App-Player. Der Flow war erfolgreich und die tokenführenden Actions zeigten verborgene Inputs und Outputs. Ein erneuter Versuch mit einem bereits verbrauchten Token lieferte 403 Access denied; das Öffnen eines ungenutzten Tokens nach Ablauf ergab 403 Expired.

Fehlerbehebung

Symptom Check
HTTP 401 Der API-Schlüssel der Verbindung und der Sandbox-Host stimmen überein; der Schlüssel wird im x-api-key-Header gesendet
HTTP 403 mentioning sessiontokens:write Das API-Gerät hat explizite Scopes und Session tokens ist ausgewählt; Full access ist unzureichend
HTTP 400 about the target device deviceId bezeichnet ein normales Gerät, ohne API-Scopes und mit aktiviertem Login-Identifier-Authentifizierungsmodus
HTTP 400 about the user Der Operator ist aktiv und derzeit auf denselben Arbeitsbereich umgeschaltet
HTTP 403 about user groups Der Operator gehört zu einer Gruppe, die auf dem Zielgerät erlaubt ist
HTTP 404 Das normale Gerät und der Operator-Login-Identifier existieren im Workspace des API-Schlüssels
Page sign-in fails Fordern Sie ein frisches Token an und navigieren Sie sofort; abgelaufene oder bereits verwendete Tokens sind nicht wiederverwendbar
Work instruction or media does not load Prüfen Sie die genehmigte Anweisung, den Operator-Zugriff und die Konfiguration des Zielgeräts; halten Sie API-Scopes nur auf dem Integrationsgerät
Flow or custom action does not appear Prüfen Sie, dass alle Ressourcen in derselben Power Platform-Umgebung sind; erlauben Sie Connector-Änderungen zu propagieren und aktualisieren Sie dann
Published app asks to start a Power Apps trial Prüfen Sie die Power Apps-Berechtigung des angemeldeten Kontos; eine Entwicklerumgebung und erfolgreiche Studio-Vorschau sind nicht ausreichend

Beispiel anpassen

Für eine Produktions-App ersetzen Sie die feste Testidentität durch ein servervalidiertes Mapping vom authentifizierten Microsoft-Aufrufer zum erlaubten Azumuta-Operator. Akzeptieren Sie nicht einen uneingeschränkten loginIdentifier oder ein Ziel-deviceId aus einem Canvas-Textfeld: der Geräte-Schlüssel autorisiert die Integration, nicht die Person, die die App ausführt. Beschränken Sie, wer den Flow ausführen und bearbeiten darf, und stellen Sie die erforderlichen Microsoft-Lizenzen bereit, bevor Sie die Lösung freigeben.

Für eine andere REST-Operation fügen Sie dem Connector die entsprechende Aktion hinzu und gewähren nur die dokumentierten API-Scopes. Senden Sie den Schlüssel weiterhin im Header. Verwenden Sie die REST API documentation des Arbeitsbereichs für Request- und Response-Details.

Wenn das Beispiel nicht mehr benötigt wird, deaktivieren Sie den Flow und widerrufen Sie das Sandbox-Credential über das API-Gerätemanagement Ihres Arbeitsbereichs.