Arbeiten mit Daten mithilfe der Dataverse CLI (Vorschau)

Note

• Dies ist eine Vorschaufunktion.
• Funktionen in der Vorschauversion sind nicht für den Produktionseinsatz gedacht und können eine eingeschränkte Funktionalität aufweisen. Diese Funktionen sind vor einer offiziellen Veröffentlichung verfügbar, damit Kunden frühzeitig zugreifen und Feedback geben können.

Die Dataverse CLI ist ein plattformübergreifendes Befehlszeilentool für Microsoft Dataverse. Verwenden Sie sie, um Authentifizierungsprofile zu verwalten, Daten abzufragen und zu ändern, APIs zu ermitteln und aufzurufen, mit verknüpften ERP-Umgebungen zu arbeiten und einen MCP-Server (Model Context Protocol) auszuführen, mit dem KI-Assistenten mit Ihrer Umgebung interagieren können.

Die CLI wird als @microsoft/dataverse npm-Paket verteilt. Zu den Schlüsselfunktionen gehören:

• Profilbasierte Authentifizierung, die mit Microsoft Power Platform CLI-Authentifizierungsprofilen kompatibel ist.
• Umgebungsbefehle (org / env) zum Anzeigen der aktuellen Organisations- und Listenumgebung.
• Datenbefehle zum Abfragen, Abrufen, Erstellen, Aktualisieren, Upsert, Löschen und Zählen von Datensätzen; Dateien in Dateispalten hochladen; und Zuordnen oder Aufheben der Zuordnung verwandter Datensätze.
• Dynamische Befehle zum Ermitteln, Beschreiben und Aufrufen von benutzerdefinierten api Dataverse-APIs und ERP-aufrufbaren Dienstendpunkten oder zum Senden von unformatierten authentifizierten HTTP-Anforderungen.
• skill Befehle zum Hochladen, Herunterladen, Auflisten und Löschen von Dataverse-Fähigkeiten, die von KI-Agents verwendet werden.
• Ein MCP-Server für KI-Clients wie Claude Desktop.
• --json Ausgabe für unterstützte Befehle für skripting.

Eine vollständige Liste der Befehle und deren Parameter finden Sie in der Dataverse CLI-Referenz.

Voraussetzungen

Um die CLI zu installieren und auszuführen, benötigen Sie Node.js (einschließlich npm) auf einer unterstützten Plattform installiert.

Bevor Sie sich mit dem MCP-Server authentifizieren und eine Verbindung mit einer Dataverse-Umgebung herstellen können, muss ein Administrator die folgenden drei Setupschritte ausführen:

1. Erteilen der Administratorzustimmung (Azure Mandantenadministrator). Ein Azure Mandantenadministrator gewährt Administratorzustimmungen für die Dataverse MCP CLI-Toolanwendung, indem er zu https://login.microsoftonline.com/{your-tenant-id}/adminconsent?client_id=0c412cc3-0dd6-449b-987f-05b053db9457den angeforderten Berechtigungen navigiert, sich anmeldet und akzeptiert. Ersetzen Sie sie {your-tenant-id} durch Ihre tatsächliche Azure Mandanten-ID.

2. Aktivieren Sie den MCP-Server (Dataverse-Administrator). Ein Dataverse-Organisationsadministrator aktiviert das MCP-Serverfeature für die Umgebung. Siehe Enable Dataverse MCP (Production) oder Enable Dataverse MCP (Vorschau).

3. Allow the MCP CLI tool (Dataverse admin). Ein Dataverse-Organisationsadministrator fügt das Dataverse MCP CLI-Tool zur Liste der zulässigen Clientanwendungen hinzu, indem er der McP-Clientliste folgt und die Anwendung mit der App-ID 0c412cc3-0dd6-449b-987f-05b053db9457hinzufügt. Sie wird als Dataverse MCP CLI-Tool in der Benutzeroberfläche angezeigt.

   Alternativ kann ein Benutzer mit Dataverse-Administratorberechtigungen die Anwendung mithilfe des mcp allow Befehls hinzufügen.

Note

Sie müssen alle drei Schritte ausführen, bevor Sie sich erfolgreich authentifizieren und eine Verbindung mit Ihrer Dataverse-Umgebung über den MCP-Server herstellen können.

Unterstützte Plattformen

Die Dataverse CLI unterstützt die folgenden Plattformen:

• Windows (x64, Arm64)
• macOS (x64, Arm64 / Apple Silicon)
• Linux (x64, Arm64)

Installieren der Dataverse CLI

Installieren Sie die CLI global mithilfe von npm:

npm install -g @microsoft/dataverse

Alternativ können Sie die CLI ausführen, ohne sie mithilfe npxvon :

npx @microsoft/dataverse <command> [options]

Um eine bestimmte Version zu installieren oder auf die neueste Version zu aktualisieren, verwenden Sie den install Befehl:

dataverse install latest
dataverse install 1.0.0

Die CLI überprüft npm automatisch auf neuere Versionen, wenn Sie einen Befehl ausführen. Wenn eine neuere Version verfügbar ist, benachrichtigt sie Sie, damit Sie aktualisieren können.

Verwendung mit Claude Desktop

Sie können die CLI als MCP-Server ausführen, damit Claude Desktop mit Ihrer Dataverse-Umgebung interagieren kann.

Der schnellste Weg, es hinzuzufügen, ist mit der Claude CLI:

claude mcp add dataverse -t stdio -- npx -y @microsoft/dataverse mcp https://yourorg.crm.dynamics.com

Um Claude Desktop manuell zu konfigurieren, bearbeiten Sie die MCP-Konfigurationsdatei:

• Fenster: %APPDATA%\Claude\claude_desktop_config.json
• Macos: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Fügen Sie den Server zum mcpServers Abschnitt hinzu:

{
  "mcpServers": {
    "dataverse": {
      "command": "npx",
      "args": ["-y", "@microsoft/dataverse", "mcp", "https://yourorg.crm.dynamics.com"],
      "type": "stdio"
    }
  }
}

Um detaillierte Diagnosen zu erfassen, fügen Sie dem args Array die --log-level Debug Optionen und --log-file Optionen hinzu. Um den VORSCHAU-MCP-Endpunkt zu verwenden, fügen Sie die --preview Option hinzu. Starten Sie Claude Desktop neu, nachdem Sie die Konfiguration geändert haben.

Weitere Informationen zum Starten des Servers finden Sie im mcp Befehl.

Authentication

Die CLI verwendet die Microsoft Authentication Library (MSAL) (MSAL) für die Authentifizierung. Es speichert Authentifizierungsprofile und Token lokal zwischen. Diese Profile funktionieren mit Microsoft Power Platform CLI-Authentifizierungsprofilen.

Erstellen Sie ein Profil bei der ersten Verbindung mithilfe des auth create Befehls:

dataverse auth create --environment https://myorg.crm.dynamics.com

Mit diesem Befehl wird ein Browser- oder Systemauthentifizierungsdialogfeld geöffnet. Nachdem Sie sich angemeldet haben, wird das Profil gespeichert. Nachfolgende Befehle, einschließlich mcp, verwenden die zwischengespeicherten Token, ohne Sie erneut aufzufordern.

Wenn Sie mit mehr als einer Umgebung arbeiten möchten, erstellen Sie ein benanntes Profil für jede Umgebung. Wechseln Zwischen ihnen mithilfe des auth select Befehls:

dataverse auth create --environment https://dev.crm.dynamics.com --name dev
dataverse auth create --environment https://prod.crm.dynamics.com --name prod
dataverse auth select --name dev

Für unbeaufsichtigte Szenarien wie CI/CD authentifizieren Sie sich mit einem Dienstprinzipal:

dataverse auth create --applicationId <appId> --clientSecret <secret> --tenant <tenantId> --environment https://myorg.crm.dynamics.com

Verwenden Sie für Umgebungen ohne Browser den Gerätecodefluss, indem Sie die --deviceCode Option hinzufügen. Um alle Authentifizierungsoptionen anzuzeigen, einschließlich Zertifikat, verwalteter Identität und Verbundauthentifizierung, führen Sie dataverse auth create --helpaus. Informationen zum Überprüfen, Auflisten und Entfernen von Profilen finden Sie in den auth whoBefehlen , auth list, und auth remove

Hilfe erhalten

Jeder Befehl und jeder Unterbefehl unterstützt die --help Option. Sie listet Die Verwendung, Optionen und Beispiele auf. Beispiel:

dataverse --help
dataverse auth --help
dataverse auth create --help
dataverse org --help
dataverse mcp --help
dataverse data query --help

Unterstützte MCP-Vorgänge

Der MCP-Server unterstützt die folgenden Vorgänge:

• Tools: Auflisten und Aufrufen von Dataverse-Tools.
• Eingabeaufforderungen: Auflisten und Abrufen von Eingabeaufforderungen.
• Ressourcen: Auflisten und Lesen von Dataverse-Ressourcen.

Wenn es sich bei der Umgebungs-URL um einen ERP-Host (Finance and Operations) handelt, z https://myorg.operations.dynamics.com. B. wird der mcp Befehl automatisch an den ERP-MCP-Server weitergeleitet.

Problembehandlung

Überprüfen Sie Ihr Setup

Bevor Sie den Server starten, überprüfen Sie die Authentifizierungs- und MCP-Konfiguration mithilfe der --validate Option:

dataverse mcp https://yourorg.crm.dynamics.com --validate

Mit dieser Option werden die GA- und Vorschauendpunkte überprüft und überprüft, ob die Authentifizierung funktioniert, der MCP-Server aktiviert ist, und das MCP CLI-Tool befindet sich in der Liste der zulässigen Anwendungen. Wenn die Überprüfung fehlschlägt, gibt die Ausgabe an, welcher erforderliche Schritt abgeschlossen werden soll.

Protokollierung aktivieren

Wenn Probleme auftreten, aktivieren Sie die Dateiprotokollierung, um detaillierte Diagnoseinformationen zu erfassen:

dataverse mcp https://yourorg.crm.dynamics.com --log-level Debug --log-file

Protokolldateien werden in das temporäre Verzeichnis Ihres Systems geschrieben. Der genaue Speicherort wird angezeigt, wenn die Protokollierung gestartet wird.

Häufig auftretende Probleme

Keine kompatible Binärdatei für Ihre Plattform gefunden

Die CLI unterstützt Windows (x64, Arm64), macOS (x64, Arm64) und Linux (x64, Arm64). Andere Plattformen werden von den vordefinierten Binärdateien nicht unterstützt.

Authentifizierungsfehler

• Vergewissern Sie sich, dass Sie Zugriff auf die Dataverse-Umgebung haben.
• Vergewissern Sie sich, dass die Umgebungs-URL korrekt ist.
• Löschen Sie den Tokencache, und authentifizieren Sie es erneut, indem Sie den auth create Befehl verwenden.

MCP-Verbindungsprobleme in Claude Desktop

• Stellen Sie sicher, dass die JSON-Konfigurationssyntax korrekt ist.
• Stellen Sie sicher, dass auf die Umgebungs-URL zugegriffen werden kann.
• Fügen Sie die --log-file Option zum Erfassen detaillierter Fehlermeldungen hinzu.
• Starten Sie Claude Desktop neu, nachdem Sie die Konfiguration geändert haben.

Siehe auch

Dataverse CLI-Referenz