Freigeben über


Hinzufügen und Ausführen von PowerShell-Skripts mit Standardworkflows in Azure Logic Apps

Gilt für: Azure Logic Apps (Standard)

Um benutzerdefinierte Integrationsaufgaben inline in Ihrem Standardworkflow in Azure Logic Apps auszuführen, können Sie direkt in Ihrem Workflow PowerShell-Code hinzufügen und ausführen. Verwenden Sie für diese Aufgabe die Inlinecode-Aktion namens PowerShell-Code ausführen. Diese Aktion gibt die Ergebnisse Ihres PowerShell-Codes zurück, sodass Sie diese Ausgabe in nachfolgenden Aktionen Ihres Workflows verwenden können.

Diese Funktion bietet die folgenden Vorteile:

  • Schreiben Sie eigene Skripts im Workflow-Designer, um komplexere Integrationsprobleme zu lösen. Es sind keine weiteren Dienstpläne erforderlich.

    Dieser Vorteil reduziert die Komplexität und die Kosten, da Sie mehr Dienste verwalten und die Workflowentwicklung optimieren können.

  • Generieren Sie eine dedizierte Codedatei, die einen personalisierten Skriptbereich in Ihrem Workflow bereitstellt.

  • Integrieren Sie mit Azure Functions PowerShell-Funktionen, die leistungsfähige Funktionen und Vererbung für die erweiterte Aufgabenausführung bieten.

  • Stellen Sie Skripts zusammen mit Ihren Workflows bereit.

In diesem Leitfaden wird gezeigt, wie Sie die Aktion in Ihrem Workflow hinzufügen und den PowerShell-Code hinzufügen, den Sie ausführen möchten.

Voraussetzungen

  • Ein Azure-Konto und ein Azure-Abonnement. Erhalten Sie ein kostenloses Azure-Konto.

  • Die Standardlogik-App-Ressource mit dem Workflow, in dem Sie Ihr PowerShell-Skript hinzufügen möchten.

    Der Workflow muss bereits mit einem Trigger gestartet werden. Sie können jeden trigger für Ihr Szenario verwenden, aber als Beispiel verwendet dieses Handbuch den Anforderungsauslöser namens "Wenn eine HTTP-Anforderung empfangen wird" und auch die Antwortaktion. Der Workflow wird ausgeführt, wenn eine andere Anwendung oder ein anderer Workflow eine Anforderung an die Endpunkt-URL des Triggers sendet. Das Beispielskript gibt die Ergebnisse aus der Codeausführung als Ausgabe zurück, die Sie in nachfolgenden Aktionen verwenden können.

    Wenn Sie über keine Logik-App-Ressource und keinen Workflow verfügen, erstellen Sie sie jetzt, indem Sie die folgenden Schritte ausführen:

Überlegungen

  • Das Azure-Portal speichert Ihr Skript als PowerShell-Skriptdatei (.ps1) im selben Ordner wie Ihre Datei workflow.json, die die JSON-Definition für Ihren Workflow speichert, und stellt die Datei zusammen mit der Workflowdefinition in Ihrer Logik-App-Ressource bereit.

    Mit dem.ps1 Dateiformat können Sie weniger "Textbausteine" schreiben und sich nur auf das Schreiben von PowerShell-Code konzentrieren. Wenn Sie die Aktion umbenennen, wird die Datei ebenfalls umbenannt. Beim Umbenennen der Datei wird die Aktion jedoch nicht umbenannt. Wenn Sie die Datei direkt umbenennen, überschreibt die umbenannte Version die vorherige Version. Wenn der Aktionsname und der Dateiname nicht übereinstimmen, wird die Datei nicht von der Aktion gefunden, und sie versucht, eine neue leere Datei zu erstellen.

  • Das Skript ist lokal für den Workflow. Wenn Sie dasselbe Skript in anderen Workflows verwenden möchten, zeigen Sie die Skriptdatei in der Kudu-Konsole an, und kopieren Sie dann das Skript, um es in anderen Workflows wiederzuverwenden.

Einschränkungen

Name Begrenzung Notizen
Skriptausführungsdauer 10 Minuten Wenn Sie Szenarien haben, die längere Dauer benötigen, verwenden Sie die Produktfeedbackoption, um weitere Informationen zu Ihren Anforderungen bereitzustellen.
Ausgabegröße 100 MB Die Ausgabegröße hängt vom Grenzwert für die Ausgabegröße für Aktionen ab, was im Allgemeinen 100 MB beträgt.

Aktualisieren der PowerShell-Version

Sie können die PowerShell-Version in Ihrer Logik-App-Ressource ändern, indem Sie die Anwendungseinstellungen bearbeiten. Berücksichtigen Sie vor dem Upgrade Ihrer App jedoch die folgenden Überlegungen:

Hinweis

Wenn Sie keine PowerShell-Version angeben, verwendet Azure Logic Apps standardmäßig dieselbe Standardversion wie Azure Functions. Derzeit ist PowerShell 7.4 allgemein verfügbar. Weitere Informationen zu verfügbaren Versionen finden Sie im PowerShell-Entwicklerhandbuch für Azure Functions.

Führen Sie basierend darauf, wo Sie die PowerShell-Version aktualisieren möchten, die entsprechenden Schritte aus:

  1. Öffnen Sie im Azure-Portal Ihre Ressource vom Typ „Logic App (Standard)“.

  2. Wählen Sie auf der Randleiste für Ressourcen unter Einstellungen die Option Umgebungsvariablen aus.

  3. Wählen Sie auf der Registerkarte App-Einstellungen die Option + Hinzufügen aus.

  4. Fügen Sie im Bereich Anwendungseinstellung hinzufügen/bearbeiten die folgende neue App-Einstellung hinzu:

    Parameter Wert BESCHREIBUNG
    Name LOGIC_APPS_POWERSHELL_VERSION Der Name der App-Einstellung.
    Wert < PowerShell-Version> Die PowerShell-Version, derzeit 7.4.
  5. Wenn Sie fertig sind, wählen Sie Anwenden aus. Wenn die Neustartwarnung angezeigt wird, wählen Sie Weiter aus.

    Ihre Logik-App wird mit der aktualisierten Version neu gestartet.

Hinzufügen der Aktion „PowerShell-Code ausführen“

  1. Öffnen Sie im Azure-Portal Ihre Ressource vom Typ „Logic App (Standard)“.

  2. Wählen Sie auf der Ressourcen-Randleiste unter Workflows die Option Workflows aus, und wählen Sie dann anschließend Ihren leeren Workflow aus.

  3. Wählen Sie auf der Workflow-Randleiste unter "Extras" den Designer aus, um den Workflow zu öffnen.

  4. Fügen Sie die Aktion "Inlinecodevorgänge " mit dem Namen "PowerShell-Code ausführen " zu Ihrem Workflow hinzu, indem Sie die allgemeinen Schritte ausführen, um eine Aktion hinzuzufügen.

  5. Daraufhin wird der Bereich „Aktionsinformationen“ geöffnet. Aktualisieren Sie dort auf der Registerkarte Parameter im Feld Codedatei den vorab aufgefüllten Beispielcode mit Ihrem eigenen Skriptcode.

    Das folgende Beispiel zeigt die Registerkarte Parameter der Aktion mit dem Beispielskriptcode:

    Screenshot: Azure-Portal, Standardworkflow-Designer, Anforderungstrigger, Aktion „PowerShell-Code ausführen“ mit geöffneter Informationsbereich und Aktion „Antwort“. Der Informationsbereich zeigt ein PowerShell-Beispielskript.

    Das folgende Beispiel zeigt den Beispielskriptcode:

    # Use the following cmdlets to retrieve outputs from prior steps.
    # $triggerOutput = Get-TriggerOutput
    # $ActionOutput = Get-ActionOutput -ActionName <action-name>
    
    $customResponse =  [PSCustomObject]@{
       Message = "Hello world!"
    }
    
    # Use Write-Debug/Write-Host/Write-Output/ to log messages to Application Insights.
    # Write-Host/Write-Output/Write-Debug and 'return' won't return an output to the workflow.
    # Write-Host "Sending to Application Insight logs"
    
    # Use Push-WorkflowOutput to push outputs into subsequent actions.
    Push-WorkflowOutput -Output $customResponse
    

    Das folgende Beispiel zeigt ein benutzerdefiniertes Beispielskript:

    $action = Get-TriggerOutput
    $results = "Hello from PowerShell!"
    Push-WorkflowOutput -Output $results
    
  6. Speichern Sie Ihren Workflow, wenn Sie fertig sind.

Nachdem Sie Ihren Workflow ausgeführt haben, können Sie die Workflowausgabe in Application Insights überprüfen, sofern dieses Tool aktiviert ist. Weitere Informationen finden Sie im Abschnitt zum Anzeigen der Ausgabe in Application Insights.

Access-Workflowtrigger und Aktionsausgabe in Ihrem Skript

Die Ausgabewerte des Triggers und der vorherigen Aktionen werden mithilfe eines benutzerdefinierten Objekts mit mehreren Parametern zurückgegeben. Um auf diese Ausgaben zuzugreifen und sicherzustellen, dass Sie den gewünschten Wert zurückgeben, verwenden Sie die Cmdlets "Get-TriggerOutput", "Get-ActionOutput" und "Push-WorkflowOutput" sowie alle in der folgenden Tabelle beschriebenen entsprechenden Parameter, z. B.:

$trigger = Get-TriggerOutput
$statusCode = $trigger.status.ToString();
$action = Get-ActionOutput -ActionName Compose
$actionOutput = $action.outputs['actionOutput'].ToString();
$populatedString = "Send the $statusCode for the trigger status and $actionOutputName."

Push-WorkflowOutput -Output $populatedString

Hinweis

Wenn Sie in PowerShell auf ein Objekt verweisen, das den JValue-Typ innerhalb eines komplexen Objekts aufweist und Sie dieses Objekt einer Zeichenfolge hinzufügen, erhalten Sie eine Formatausnahme. Um diesen Fehler zu vermeiden, verwenden Sie ToString().

Antwortausgaben von Triggern und Aktionen

In der folgenden Tabelle sind die Ausgaben aufgeführt, die beim Aufrufen von Get-ActionOutput oder Get-TriggerOutput generiert werden. Der Rückgabewert ist ein komplexes Objekt, PowershellWorkflowOperationResultdas die folgenden Ausgaben enthält.

Name type BESCHREIBUNG
Name Schnur Der Name für den Trigger oder die Aktion
Eingaben JToken Die Eingabewerte, die an den Trigger oder die Aktion übergeben werden
Ausgaben JToken Die Ausgaben des ausgeführten Triggers oder der ausgeführten Aktion
StartTime Datum/Uhrzeit Die Startzeit für den Trigger oder die Aktion
EndTime Datum/Uhrzeit Die Endzeit für den Trigger oder die Aktion
ScheduledTime Datum/Uhrzeit Die geplante Zeit für die Ausführung des Triggers oder der Aktion
OriginHistoryName Schnur Der Name des Ursprungsverlaufs für Trigger, die die splitOn Eigenschaft verwenden
SourceHistoryName Schnur Der Name des Quellverlaufs für einen erneut ausgegebenen Trigger
TrackingId Schnur Die Vorgangsverfolgungs-ID
Code Schnur Der Statuscode für das Ergebnis
Status Schnur Der Ausführungsstatus für den Trigger oder die Aktion, z. B. "Erfolgreich" oder "Fehlgeschlagen".
Fehler JToken Der HTTP-Fehlercode
TrackedProperties JToken Alle nachverfolgten Eigenschaften, die Sie eingerichtet haben

Zurückgeben von Ausgaben an Ihren Workflow

Um alle Ausgaben an Ihren Workflow zurückzugeben, müssen Sie das cmdletPush-WorkflowOutput verwenden.

Benutzerdefinierte PowerShell-Befehle

Die Aktion PowerShell-Code ausführen umfasst die folgenden benutzerdefinierten PowerShell-Befehle (Cmdlets) für die Interaktion mit Ihrem Workflow und anderen Vorgängen in Ihrem Workflow:

Get-TriggerOutput

Ruft die Ausgabe des Workflowtriggers ab.

Syntax

Get-TriggerOutput

Parameter

Keine.

Get-ActionOutput

Ruft die Ausgabe aus einer anderen Aktion im Workflow ab und gibt ein Objekt mit dem Namen PowershellWorkflowOperationResultzurück.

Syntax

Get-ActionOutput [ -ActionName <String> ]

Parameter

Parameter type BESCHREIBUNG
ActionName Schnur Der Name der Aktion im Workflow, auf deren Ausgabe Sie verweisen möchten

Push-WorkflowOutput

Pusht die Ausgabe der Aktion PowerShell-Code ausführen an Ihren Workflow, der ein Objekt beliebigen Typs zurückgegeben kann. Wenn der Rückgabewert NULL ist, erhalten Sie vom Cmdlet einen Fehler vom Typ „NULL-Objekt“.

Hinweis

Die Cmdlets Write-Debug, Write-Host und Write-Output geben keine Werte an Ihren Workflow zurück. Die return Anweisung gibt auch keine Werte an Ihren Workflow zurück. Sie können diese Cmdlets jedoch verwenden, um Ablaufverfolgungsmeldungen zu schreiben, die in Application Insights angezeigt werden. Weitere Informationen finden Sie unter Microsoft.PowerShell.Utility.

Syntax

Push-WorkflowOutput [-Output <Object>] [-Clobber]

Parameter

Parameter type BESCHREIBUNG
Ausgabe Variiert Die Ausgabe, die Sie an den Workflow zurückgeben möchten. Diese Ausgabe kann einen beliebigen Typ aufweisen.
Clobber Variiert Ein optionaler Switch-Parameter, mit dem Sie die zuvor gepushte Ausgabe überschreiben können.

Authentifizieren und Autorisieren des Zugriffs mit einer verwalteten Identität mithilfe von PowerShell

Mit einer verwalteten Identität können Ihre Logik-App-Ressource und Ihr Logik-App-Workflow den Zugriff auf alle Azure-Dienste und -Ressourcen, die die Microsoft Entra-Authentifizierung unterstützen, authentifizieren und autorisieren, ohne dass Sie Anmeldeinformationen in Ihren Code einschließen.

In der Aktion PowerShell-Code ausführen können Sie den Zugriff mit einer verwalteten Identität authentifizieren und autorisieren, sodass Sie Aktionen für andere Azure-Ressourcen ausführen können, für die Sie den Zugriff aktiviert haben. Sie können beispielsweise eine VM neu starten oder die Ausführungsdetails eines anderen Logik-App-Workflows abrufen.

Um die verwaltete Identität innerhalb der Aktion PowerShell-Code ausführen zu verwenden, müssen Sie die folgenden Schritte ausführen:

  1. Richten Sie die verwaltete Identität in Ihrer Logik-App ein, und gewähren Sie der verwalteten Identität Zugriff auf die Azure-Zielressource. Ausführliche Schritte finden Sie unter Authentifizieren des Zugriffs und der Verbindungen mit Azure-Ressourcen mit verwalteten Identitäten.

    Überprüfen Sie für die Azure-Zielressource Folgendes:

    • Auf der Registerkarte Rolle reicht normalerweise die Rolle Mitwirkender aus.

    • Stellen Sie auf der Seite Rollenzuweisung hinzufügen sicher, dass auf der Registerkarte Mitglieder für die Eigenschaft Zugriff zuweisen zu die Option Verwaltete Identität ausgewählt ist.

    • Wählen Sie Mitglieder auswählen und dann im Bereich Wählen Sie verwaltete Identitäten aus die verwaltete Identität aus, die Sie verwenden möchten.

  2. Fügen Sie in Ihrer Aktion PowerShell-Code ausführen den folgenden Code als erste Anweisung hinzu:

    Connect-AzAccount -Identity
    
  3. Jetzt können Sie mithilfe von Cmdlets und Modulen mit der Azure-Ressource arbeiten.

Ansehen der Skriptdatei

  1. Öffnen Sie im Azure-Portal Ihre Ressource vom Typ „Logic App (Standard)“.

  2. Wählen Sie auf der Ressourcen-Randleiste unter "Entwicklungstools" die Option "Erweiterte Tools" aus.

  3. Wählen Sie auf der Seite "Erweiterte Tools" die Option "Gehe zu" aus, wodurch die Kudu-Konsole geöffnet wird.

  4. Öffnen Sie das Menü Debugkonsole, und wählen Sie CMD aus.

  5. Wechseln Sie zum Stammspeicherort Ihrer Logik-App: website/wwwroot

  6. Wechseln Sie zum Ordner Ihres Workflows, der die Datei mit der erweiterung.ps1 entlang dieses Pfads enthält: site/wwwroot/{workflow-name}

  7. Wählen Sie neben dem Dateinamen Bearbeiten aus, um die Datei zu öffnen und anzuzeigen.

Anzeigen von Protokollen in Application Insights

  1. Wählen Sie im Azure-Portal auf der Seitenleiste der Logik-App unter "Überwachung" die Option "Application Insights " (nicht "Insights") aus.

  2. Wählen Sie den Link zu Ihrer Application Insights-Ressource aus.

  3. Wählen Sie auf der Ressourcen-Randleiste "Application Insights" unter "Überwachung" die Option "Protokolle" aus.

  4. Erstellen Sie eine Abfrage, um Ablaufverfolgungen oder Fehler der Workflowausführung zu finden, z. B.:

    union traces, errors
    | project TIMESTAMP, message
    

Module

PowerShell-Module sind eigenständige, wiederverwendbare Einheiten, die verschiedene Komponenten enthalten, z. B.:

  • Cmdlets: Einzelne Befehle, die bestimmte Aufgaben ausführen
  • Anbieter: Ermöglichen den Zugriff auf Datenspeicher (z. B. die Registrierung oder das Dateisystem) als wären sie Laufwerke
  • Funktionen: Wiederverwendbare Codeblöcke, die bestimmte Aktionen ausführen
  • Variablen: Speichern Daten zur Verwendung im Modul
  • Andere Ressourcentypen

Ein Modul organisiert PowerShell-Code und erleichtert seine Verteilung. Sie können z. B. eigene Module erstellen, um zusammengehörige Funktionen zu verpacken, damit sie leichter verwaltet und geteilt werden können. Mit der Aktion PowerShell-Code ausführen können Sie öffentliche und private PowerShell-Module importieren.

Öffentliche Module

Öffentlich verfügbare Module finden Sie im PowerShell-Katalog. Eine Logik-App-Standardressource kann bis zu zehn öffentliche Module unterstützen. Um ein öffentliches Modul zu verwenden, müssen Sie diese Funktion wie folgt aktivieren:

  1. Wählen Sie im Azure-Portal auf der Seitenleiste der Logik-App unter "Entwicklungstools" die Option "Erweiterte Tools" aus.

  2. Wählen Sie auf der Seite Erweiterte Tools die Option Los aus.

  3. Wählen Sie auf der Kudu-Symbolleiste im Menü der Debugging-KonsoleCMD aus.

  4. Navigieren Sie in der Verzeichnisstruktur oder mithilfe der Befehlszeile zur Stammebene Ihrer Logik-App unter C:\home\site\wwwroot.

  5. Öffnen Sie die host.json Datei des Workflows, und legen Sie die Eigenschaft ManagedDependency.enabled auf true fest, die bereits standardmäßig voreingestellt ist.

    "managedDependency": {
        "enabled": true
    }
    
  6. Öffnen Sie die Datei requirements.psd1. Geben Sie den Namen und die Version für das gewünschte Modul mit der folgenden Syntax ein: MajorNumber.* oder die genaue Modulversion, z. B.:

    @{
        Az = '1.*'
        SqlServer = '21.1.18147'
    } 
    

Überlegungen zu öffentlichen Modulen

Berücksichtigen Sie Folgendes, wenn Sie die Abhängigkeitsverwaltung verwenden:

  • Bei öffentlichen Modulen benötigen Sie zum Herunterladen Zugriff auf den PowerShell-Katalog.

  • Verwaltete Abhängigkeiten unterstützen derzeit keine Module, die erfordern, dass Sie eine Lizenz akzeptieren, entweder durch interaktives Akzeptieren der Lizenz oder durch Bereitstellen der -AcceptLicense Option, wenn Sie Install-Module ausführen.

Private Module

Sie können eigene private PowerShell-Module generieren. Informationen zum Erstellen Ihres ersten PowerShell-Moduls finden Sie unter Schreiben eines PowerShell-Skriptmoduls.

  1. Wählen Sie im Azure-Portal unter "Entwicklungstools" auf den Seitenleisten Ihrer Logik-App die Option "Erweiterte Tools" aus.

  2. Wählen Sie auf der Seite Erweiterte Tools die Option Los aus.

  3. Wählen Sie auf der Kudu-Symbolleiste im Menü der Debugging-KonsoleCMD aus.

  4. Navigieren Sie in der Verzeichnisstruktur oder mithilfe der Befehlszeile zur Stammebene Ihrer Logik-App unter C:\home\site\wwwroot.

  5. Erstellen Sie einen Ordner mit dem Namen Modules.

  6. Erstellen Sie im Ordner Modules einen Unterordner mit dem Namen Ihres privaten Moduls.

  7. Fügen Sie in Ihrem privaten Modulordner Ihre private PowerShell-Moduldatei mit der Erweiterung PSM1 hinzu. Sie können auch eine optionale PowerShell-Manifestdatei mit der Erweiterung PSD1 einschließen.

Wenn Sie fertig sind, sieht die vollständige Logik-App-Dateistruktur in etwa wie folgt aus:

MyLogicApp
-- execute_powershell_script.ps1
-- mytestworkflow.json
Modules
-- MyPrivateModule
--- MyPrivateModule.psd1
--- MyPrivateModule.psm1
-- MyPrivateModule2
--- MyPrivateModule2.psd1
--- MyPrivateModule2.psm1
requirements.psd1
host.json

Kompilierungsfehler

In dieser Version enthält der webbasierte Editor eingeschränkte IntelliSense-Unterstützung, die noch verbessert wird. Alle Kompilierungsfehler werden erkannt, wenn Sie Ihren Workflow speichern, und die Azure Logic Apps-Laufzeit kompiliert Ihr Skript. Diese Fehler werden in den Fehlerprotokollen Ihrer Logik-App über Application Insights angezeigt.

Laufzeitfehler

Eine Workflowaktion gibt keine Ausgabe zurück.

Stellen Sie sicher, dass Sie das Push-WorkflowOutput Cmdlet verwenden.

Fehler bei der Aktion „PowerShell-Code ausführen“: Die Benennung „{some-text}“ wurde nicht erkannt...“

Wenn Sie in der Datei requirements.psd1 fälschlicherweise auf ein öffentliches Modul verweisen oder ihr privates Modul nicht im Pfad "C:\home\site\wwwroot\Modules{module-name}" vorhanden ist, wird die folgende Fehlermeldung angezeigt:

"Der Begriff '{some-text}' wird nicht als Name eines Cmdlets, einer Funktion, einer Skriptdatei oder eines ausführbaren Programms erkannt. Überprüfen Sie die Schreibweise des Namens, oder überprüfen Sie, ob ein Pfad enthalten ist, überprüfen Sie, ob der Pfad korrekt ist, und versuchen Sie es erneut."

Hinweis

Standardmäßig werden die Az*-Module in der Datei requirements.psd1 angezeigt, sie sind bei der Dateierstellung jedoch auskommentiert. Wenn Sie im Modul auf ein Cmdlet verweisen, müssen Sie die Auskommentierung des Moduls aufheben.

Fehler bei der Aktion „PowerShell-Code ausführen“: „Das Argument kann nicht an den Parameter „Output“ gebunden werden, da es NULL ist.“

Dieser Fehler tritt auf, wenn Sie versuchen, ein NULL-Objekt an den Workflow zu pushen. Stellen Sie sicher, dass das Objekt, das Sie mit Push-WorkflowOutput senden, nicht NULL ist.