Schnellstart: Web-API mit PowerShell und Visual Studio Code

Erfahren Sie, wie Sie PowerShell mit der Dataverse-Web-API in Visual Studio Code verwenden. 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. Diese Schnellstartanleitung hilft Ihnen bei den ersten Schritten mit PowerShell mit der Dataverse-Web-API in Visual Studio Code. Visual Studio Code mit PowerShell bietet eine Alternative zur Verwendung von API-Clients wie Postman oder Insomnia.

In dieser Schnellstartanleitung wird Folgendes vermittelt:

• Visual Studio Code mit PowerShell verwenden, um sich interaktiv bei Dataverse zu authentifizieren, ohne eine Anwendung zu registrieren.
• Verfassen Sie Anforderungen an die Dataverse-Web-API mithilfe des PowerShell-Cmdlets Invoke-RestMethod.

Anforderungen

Fahren Sie nicht fort, ohne dass jede der folgenden Voraussetzungen erfüllt ist.

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

  Um eine bestehende Installation auf die neueste Version zu aktualisieren, verwenden Sie .

Überprüfen der Installation

1. Öffnen Sie Visual Studio Code.

2. Wählen Sie im Terminal-Menü Neues Terminal aus.

3. Wählen Sie im Visual Studio Code-Navigationsbereich das Symbol für die PowerShell-Erweiterung aus.

4. 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
   

5. Drücken Sie die Eingabetaste. Die Ausgabe sollte wie folgt aussehen:

   PowerShell Version: 7.4.0
   PowerShell Az version: 11.1.0
   

Wenn Sie solche Ergebnisse nicht sehen, installieren oder aktualisieren Sie die erforderlichen 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

1. Wählen Sie in Visual Studio Code "Neue>Textdatei speichern" aus, oder drücken Sie STRG+N , um eine neue Datei zu öffnen.

   Sie müssen die Datei nicht speichern.

2. 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
   $secureToken = (Get-AzAccessToken `
      -ResourceUrl $environmentUrl `
      -AsSecureString).Token
   
   # Convert the secure token to a string
   $token = ConvertFrom-SecureString `
      -SecureString $secureToken `
      -AsPlainText
   
   
   # 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.

3. Bearbeiten Sie den $environmentUrl-Variablenwert (https://yourorg.crm.dynamics.com/), sodass er mit Ihrer Dataverse-Umgebungs-URL übereinstimmt.

4. 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.

5. Ü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": "11bb11bb-cc22-dd33-ee44-55ff55ff55ff",
   "UserId": "22cc22cc-dd33-ee44-ff55-66aa66aa66aa",
   "OrganizationId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
   }
   

6. Geben Sie im Terminalfenster cls ein, um den Terminalinhalt zu löschen.

7. 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 authentifiziert 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 Befehl des Az PowerShell-Moduls Get-AzTenant, um Mandanten abzurufen, die für den aktuellen Benutzer autorisiert sind. Wenn Sie nicht angemeldet sind, gibt dieser Befehl einen Fehler zurück. Das 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 den Befehl Connect-AzAccount , um ein interaktives Browserfenster zu öffnen, in dem Sie Ihre Anmeldeinformationen eingeben oder auswählen können, um sich anzumelden. Erfahren Sie mehr über die interaktive Anmeldung bei Azure PowerShell oder die nicht-interaktive Anmeldung mit einem Dienstprinzipal.

Schließlich verwendet das Skript den Befehl "Get-AzAccessToken" mit dem -ResourceUrl $environmentUrl Parameter, um eine PSAccessToken-Instanz abzurufen, die eine SecureString-Tokeneigenschaft enthält, die Sie in ein Zugriffstoken konvertieren können, das Sie zur Authentifizierung mit Dataverse verwenden können.

Wenn Sie eine Verbindung mit einem anderen Satz von Anmeldeinformationen herstellen möchten, verwenden Sie den Befehl "Disconnect-AzAccount" .

Invoke-RestMethod mit der WhoAmI-Funktion verwenden

Nachdem Sie das Zugriffstoken auf die $token Variable festgelegt haben, verfassen Sie die Anforderung an die Dataverse-Web-API und senden Sie sie mithilfe des Cmdlets Invoke-RestMethod.

Header festlegen

Alle Dataverse-Web-API-Anforderungen müssen eine Reihe 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.

# Common headers
$baseHeaders = @{
   'Authorization'    = 'Bearer ' + $token
   'Accept'           = 'application/json'
   'OData-MaxVersion' = '4.0'
   'OData-Version'    = '4.0'
}

Senden der Anforderung

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. Erfahren Sie mehr über Web-API-Funktionen.

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

# 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, den Body-Parameter fest, 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, verwenden Sie das folgende Skript:

# 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 diesem Schnellstart fehlschlagen:

Wenn ich F5 drücke, passiert nichts

Stellen Sie sicher, dass die Tastatur Funktionstasten aktiviert hat, indem Sie F-TASTE, Fn-TASTE oder Funktionssperre 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, das Zugriff auf die durch den $environmentUrl Parameter angegebene 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 mit dem Browser anmelden, wird möglicherweise diese Warnung angezeigt:

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. Für diese Anfragen 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:

• Wiederverwendbare Funktionen erstellen
• Verarbeiten von Ausnahmen
• Dataverse-Dienstschutzgrenzwerte verwalten
• Debuggen mithilfe von Fiddler
• Das CSDL-$metadata-Dokument für die Dataverse-Web-API herunterladen

Nachdem Sie nun Dataverse-Web-API-Anforderungen mithilfe von PowerShell authentifizieren und senden können, probieren Sie andere Web-API-Vorgänge aus.

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