Schnellstart-Web-API mit PowerShell und Visual Studio Code

Artikel
02/01/2024

PowerShell ist eine leistungsstarke Skriptsprache, die sich wiederholende Aufgaben automatisieren und Workflows optimieren kann, was sie zu einem idealen Tool für die Integration mit Dataverse macht. Dieser Schnellstart konzentriert sich darauf, Ihnen den Einstieg in die Verwendung von PowerShell mit der Dataverse-Web-API in Visual Studio Code zu erleichtern. Visual Studio Code mit PowerShell bietet eine Alternative zur Verwendung von API-Clients wie Postman oder Insomnia.

In diesem Schnellstart erfahren Sie, wie Sie:

Visual Studio Code mit PowerShell verwenden, um sich interaktiv bei Dataverse zu authentifizieren, ohne eine Anwendung zu registrieren.
Anforderungen an die Dataverse-Web-API mit dem PowerShell Invoke-RestMethod-Cmdlet verfassen.

Hinweis

In diesem Schnellstartartikel werden nur grundlegende Konzepte vorgestellt. Dies sollte für grundlegende Tests ausreichen. Nachdem Sie die Schritte in diesem Artikel erledigt haben, gehen Sie zu PowerShell und Visual Studio Code mit der Dataverse-Web-API verwenden, um mehr über erweiterte Funktionen zu erfahren, mit denen Sie produktiver arbeiten können, wie zum Beispiel:

Die Anweisungen in diesem Artikel sollten für Windows, Linux und macOS funktionieren. Die Schritte wurden jedoch nur mit Windows getestet. Falls Änderungen erforderlich sind, teilen Sie uns dies bitte über den Abschnitt Feedback am Ende dieses Artikels mit.

Anforderungen

Fahren Sie nicht fort, ohne sicherzustellen, dass alle der folgenden Voraussetzungen erfüllt sind.

Installieren Sie Folgendes oder überprüfen Sie, ob es vorhanden ist

Installieren Sie Visual Studio Code. Siehe Visual Studio Code herunterladen
Installieren Sie die PowerShell-Erweiterung für Visual Studio Code. Siehe PowerShell für Visual Studio Code
Installieren Sie PowerShell 7.4 oder höher. Siehe PowerShell unter Windows, Linux und macOS installieren
Installieren Sie die Az-PowerShell-Modulversion 11.1.0 oder höher. Siehe Azure PowerShell richtig installieren

Verwenden Sie Update-Module -Name Az -Force, um eine bestehende Installation auf die neueste Version zu aktualisieren

Überprüfen der Installation

Öffnen Sie Visual Studio Code.
Wählen Sie im Terminal-Menü Neues Terminal aus.
Wählen Sie im Visual Studio Code-Navigationsbereich das -Symbol für die PowerShell-Erweiterung aus.

Kopieren und fügen Sie das folgende Skript im Terminalfenster von Visual Studio Code aus:

Write-Host 'PowerShell Version:'$PSVersionTable.PSVersion.ToString()
Write-Host 'PowerShell Az version:'(Get-InstalledModule Az).Version

Drücken Sie die Eingabetaste. Die Ausgabe sollte wie folgt aussehen:
```
PowerShell Version: 7.4.0
PowerShell Az version: 11.1.0
```

Wenn Sie keine derartigen Ergebnisse sehen, installieren oder aktualisieren Sie die Voraussetzungen.

Darüber hinaus brauchen Sie

Ein gültiges Benutzerkonto für eine Dataverse-Umgebung
Die URL zur Dataverse-Umgebung, mit der Sie eine Verbindung herstellen möchten. Unter Entwicklerressourcen anzeigen erfahren Sie, wie Sie ihn finden. Sie sieht ungefähr so aus: https://yourorg.crm.dynamics.com/, wobei yourorg.crm anders ist.
Grundlegende Kenntnisse über die PowerShell-Skriptsprache

Ausprobieren

Wählen Sie in Visual Studio Code Datei > Neue Textdatei oder Strg+N aus, um eine neue Datei zu öffnen.

Sie müssen die Datei nicht speichern.

Kopieren Sie das folgende Skript in die neue Datei.

$environmentUrl = 'https://yourorg.crm.dynamics.com/' # change this
## Login if not already logged in
if ($null -eq (Get-AzTenant -ErrorAction SilentlyContinue)) {
   Connect-AzAccount | Out-Null
}
# Get an access token
$token = (Get-AzAccessToken -ResourceUrl $environmentUrl).Token
# Common headers
$baseHeaders = @{
   'Authorization'    = 'Bearer ' + $token
   'Accept'           = 'application/json'
   'OData-MaxVersion' = '4.0'
   'OData-Version'    = '4.0'
}
# Invoke WhoAmI Function
Invoke-RestMethod -Uri ($environmentUrl + 'api/data/v9.2/WhoAmI') -Method Get -Headers $baseHeaders
| ConvertTo-Json

Visual Studio Code sollte automatisch erkennen, dass es sich um ein PowerShell-Skript handelt.

Bearbeiten Sie den $environmentUrl-Variablenwert (https://yourorg.crm.dynamics.com/), sodass er mit Ihrer Dataverse-Umgebungs-URL übereinstimmt.
Drücken Sie F5 oder verwenden Sie den Visual Studio Code-Menübefehl Ausführen > Debuggen starten.

Ein neues Browserfenster wird geöffnet. Geben Sie im Browserfenster die Anmeldeinformationen ein bzw. wählen Sie diejenigen aus, die Sie zur Authentifizierung verwenden möchten.

Überprüfen Sie die Ausgabe im Visual Studio Code-Terminal-Fenster.

Unten im Terminal finden Sie den Wert des komplexen WhoAmIResponse-Typs, der für die WhoAmI-Funktion erwartet wird. Sie sollte ungefähr so aussehen:

{
"@odata.context": "https://yourorg.crm.dynamics.com/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.WhoAmIResponse",
"BusinessUnitId": "639dea3c-505c-4c3a-b8b5-d916cb507e1e",
"UserId": "d2159662-498a-406b-83cd-f515b7e561d6",
"OrganizationId": "83e197ed-ede1-4886-81f2-f41fe9395297"
}

Geben Sie im Terminalfenster cls ein, um den Terminalinhalt zu löschen.
Drücken Sie F5 oder verwenden Sie den Visual Studio Code-Menübefehl Ausführen > Debuggen starten, um das Skript erneut auszuführen.

Da Sie bereits angemeldet sind, wird das Browserfenster nicht geöffnet. Sie können Ihr Skript weiterhin bearbeiten und ausführen, um verschiedene Anforderungen auszuprobieren.

Funktionsweise

In diesem Abschnitt werden die Details des PowerShell-Skripts beschrieben, das im Ausprobieren-Abschnitt enthalten ist.

Authentifizierung

Das Skript verwendet den Az-PowerShell-Modulbefehl Get-AzTenant, um Mandanten für den aktuellen Benutzenden zu autorisieren. Wenn Sie nicht angemeldet sind, gibt dieser Befehl einen Fehler zurück. Dieses Skript verwendet den -ErrorAction SilentlyContinue-Parameter, um den Fehler zu ignorieren und nichts zurückzugeben.

Wenn der Get-AzTenant-Befehl nichts zurückgibt, verwendet das Skript Connect-AzAccount, um ein interaktives Browserfenster zu öffnen, in dem Sie Ihre Anmeldeinformationen zum Anmelden eingeben oder auswählen können. Erfahren Sie mehr über die interaktive oder nicht interaktive Anmeldung bei Azure PowerShell mit einem Dienstprinzipal.

Schließlich verwendet das Skript den Befehl Get-AzAccessToken mit dem -ResourceUrl $environmentUrl, um eine PSAccessToken-Instanz abzurufen, die eine Zeichenfolgen-Token-Eigenschaft enthält, bei der es sich um einen Zugriffstoken handelt, mit dem Sie sich bei Dataverse authentifizieren können.

Wenn Sie eine Verbindung mit anderen Anmeldeinformationen herstellen möchten, müssen Sie den Disconnect-AzAccount-Befehl verwenden.

Sich mithilfe verschiedener Shell-Umgebungen authentifizieren

Azure PowerShell funktioniert mit Windows-PowerShell- und PowerShell-Shell-Umgebungen, jedoch nicht mit Cmd- und Bash-Shell-Umgebungen. Wenn Sie sich mit Cmd- oder Bash-Shell-Umgebungen authentifizieren möchten, können Sie die Azure CLI verwenden.

Dieses Skript verwendet Azure CLI-Befehle zur Authentifizierung:

$environmentUrl = 'https://yourorg.crm.dynamics.com/' # change this
## <a name="login-if-not-already-logged-in"></a>Login if not already logged in
if ($null -eq (az account tenant list  --only-show-errors)) {
   az login --allow-no-subscriptions | Out-Null
}
# <a name="get-token"></a>Get token
$token = az account get-access-token --resource=$environmentUrl --query accessToken --output tsv

Diese Tabelle zeigt die entsprechenden Az-PowerShell- und Azure CLI-Befehle:

Az PowerShell	Azure-CLI	Beschreibung
Get-AzTenant	az account tenant list	Versuchen Sie, eine Liste der Mandanten abzurufen, um festzustellen, ob Sie bereits angemeldet sind
Connect-AzAccount	az login	Zur Anmeldung bei Azure
Get-AzAccessToken	az account get-access-token	Zum Abrufen eines Zugriffstokens
Disconnect-AzAccount	az logout	Abmeldung auf Azure

`Invoke-RestMethod` mit der WhoAmI-Funktion verwenden

Sobald Sie Zugriffstoken auf die $token-Variable gesetzt haben, müssen Sie die Anforderung an die Dataverse-Web-API verfassen und sie mit dem Invoke-RestMethod-Cmdlet senden

Header festlegen

Alle Dataverse-Web-API-Anforderungen müssen einen Satz allgemeiner HTTP-Anforderungsheader enthalten, einschließlich eines Authorization-Headers, der den Zugriffstokenwert enthält. Einige Vorgänge erfordern mehr Header. Erfahren Sie mehr über Dataverse-Web API-Anforderungsheader

# <a name="common-headers"></a>Common headers
$baseHeaders = @{
   'Authorization'    = 'Bearer ' + $token
   'Accept'           = 'application/json'
   'OData-MaxVersion' = '4.0'
   'OData-Version'    = '4.0'
}

Die Anforderung senden

Die WhoAmI-Funktion ist einer der einfachsten Dataverse-Vorgänge, den Sie ausführen können. Da es sich um eine OData-Funktion und nicht um eine Aktion handelt, muss die GET HTTP-Methode verwendet werden. Weitere Informationen zu -Web-API-Funktionen

Verwenden Sie die Invoke-RestMethod Cmdlet-Uri, -Method und -Headers, um diese Anforderung zu senden.

# <a name="invoke-whoami-function"></a>Invoke WhoAmI Function
Invoke-RestMethod -Uri ($environmentUrl + 'api/data/v9.2/WhoAmI') -Method Get -Headers $baseHeaders
| ConvertTo-Json

Legen Sie für Vorgänge, die POST- oder PATCH-HTTP-Methoden verwenden, fest, dass Sie den Body-Parameter verwenden, um die JSON-Nutzlast zu senden.

Das ConvertTo-Json-Cmdlet konvertiert das zurückgegebene Objekt in eine JSON-formatierte Zeichenfolge, die im Terminal leicht sichtbar ist.

Wenn Sie nur die UserId-Eigenschaft der Antwort erfassen möchten, können Sie stattdessen das folgende Skript verwenden:

# <a name="get-userid"></a>Get UserId
$userId = (
   Invoke-RestMethod `
   -Uri ($environmentUrl + 'api/data/v9.2/WhoAmI') `
   -Method 'Get' `
   -Headers $baseHeaders
   ).UserId
Write-Host $userId

Problembehandlung

Stellen Sie sicher, dass alle erforderlichen Programme installiert sind, wie unter Überprüfen der Installation beschrieben.

Die folgenden Situationen können dazu führen, dass die Anweisungen in dieser Schnellstartanleitung fehlschlagen:

Wenn ich `F5` drücke, passiert nichts

Stellen Sie sicher, dass die Funktionstasten auf Ihrer Tastatur aktiviert sind, indem Sie die F-Taste, Fn-Taste oder Funktionstaste auf Ihrer Tastatur drücken.

Sie können stattdessen auch den Visual Studio Code-Menübefehl Ausführen > Debugging starten verwenden.

Kein solcher Host bekannt

Wenn dieser Fehler nach der Ausführung des Skripts angezeigt wird:

Invoke-RestMethod: untitled:Untitled-1:14:1
Line |
14 |  Invoke-RestMethod -Uri ($environmentUrl + 'api/data/v9.2/WhoAmI') -Me …
   |  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   | No such host is known.

Prüfen Sie, ob $environmentUrl für eine Umgebung steht, auf die Sie Zugriff haben. Stellen Sie sicher, dass Sie den Standardwert (https://yourorg.crm.dynamics.com/) geändert haben.

Der Benutzende ist kein Mitglied der Organisation

Wenn dieser Fehler nach der Ausführung des Skripts angezeigt wird:

Invoke-RestMethod: untitled:Untitled-1:14:1                                                                             
Line |
14 |  Invoke-RestMethod -Uri ($environmentUrl + 'api/data/v9.2/WhoAmI') -Me …
   |  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   |  {   "error": {     "code": "0x80072560",     "message": "The user is not a member of the organization."   } }

Stellen Sie sicher, dass das Konto, das Sie im Browserfenster auswählen, Zugriff auf die durch den $environmentUrl-Parameter spezifizierte Dataverse-Umgebung hat.

Wenn Sie andere Anmeldeinformationen als zuvor verwenden, verwenden Sie den Disconnect-AzAccount-Befehl im Terminalfenster.

WARNUNG: TenantId „<Ihre Mandanten-ID>“ enthält mehr als ein aktives Abonnement

Wenn Sie das Skript zum ersten Mal ausführen und sich über den Browser anmelden, erhalten Sie möglicherweise diese Warnung:

WARNING: TenantId '<your tenant id>' contains more than one active subscription. First one will be selected for further use. 
To select another subscription, use Set-AzContext. 
To override which subscription Connect-AzAccount selects by default, use `Update-AzConfig -DefaultSubscriptionForLogin 00000000-0000-0000-0000-000000000000`. 
Go to https://go.microsoft.com/fwlink/?linkid=2200610 for more information.

Sie können diese Warnung ignorieren, wenn Sie sie sehen. Für diese Anforderungen ist kein Abonnement erforderlich.

Nächste Schritte,

Erfahren Sie mehr über erweiterte Funktionen, mit denen Sie mit PowerShell und Visual Studio Code mit der Dataverse-Web-API produktiver sein können, wie zum Beispiel:

PowerShell und Visual Studio Code in der Dataverse-Web-API verwenden

Da Sie nun die Möglichkeit haben, Dataverse-Web-API-Anforderungen mithilfe von PowerShell zu authentifizieren und zu senden, können Sie andere Web-API-Vorgänge ausprobieren.

Erfahren Sie mehr über Dataverse-Web-API-Funktionen durch Verständnis der Servicedokumente.

Internet API-Typen und -Vorgänge