Schnellstart: Web-API mit clientseitigem JavaScript und Visual Studio Code

Diese Schnellstartanleitung zeigt, wie Sie mit den folgenden Technologien eine Verbindung mit Dataverse herstellen und die Web-API verwenden können.

Goal

Diese Schnellstartanleitung konzentriert sich auf die Verbindung mit der Dataverse-Web-API mit JavaScript unter Verwendung einer SPA-Client-Anwendung mit einer minimalen Anzahl von Schritten. Wenn Sie diese Schnellstartanleitung abgeschlossen haben, haben Sie die folgenden Möglichkeiten:

• Sich bei Dataverse anmelden und eine Verbindung herstellen
• Die WhoAmI-Funktion aufrufen und Ihren UserID-Wert anzeigen.

Wenn Sie diese Schnellstartanleitung abschließen, können Sie das Beispiel für Web-API-Datenvorgänge (clientseitiges JavaScript) ausprobieren, das erweiterte Funktionen demonstriert.

Anforderungen

In der folgenden Tabelle werden die Voraussetzungen für die vollständige Bearbeitung dieser Schnellstartanleitung sowie Beispiele für Web-API-Datenvorgänge (clientseitigs JavaScript) beschrieben.

Eine SPA-Anwendung registrieren

Dieser Schritt ist der erste, denn wenn Sie keine App registrieren können, können Sie diesen Schnellstart nicht abschließen.

Alle die folgenden privilegierten Microsoft Entra-Rollen enthalten die erforderlichen Berechtigungen:

• Anwendungsadministrator
• Anwendungsentwicklungsfachkraft
• Fachkraft für die Cloudanwendungsadministration

Wenn Sie die Anwendung konfigurieren, benötigen Sie eine Anwendungs-ID (Client-ID) und die ID Ihres Microsoft Entra-Mandanten. Sie sollten auch einen aussagekräftigen Namen für die Anwendung wählen, damit die Benutzer wissen, wofür die Anwendung erstellt wurde.

Registrieren Sie die App

Sie können Ihre Anwendung wie folgt registrieren:

• Microsoft Entra-Webanwendungs-Benutzeroberfläche
• Azure PowerShell New-AzADApplication-Cmdlet.

Node.js installieren

1. Gehen Sie zu Node.js herunterladen.

2. Wählen Sie das entsprechende Installationsprogramm für Ihr Betriebssystem (Windows, macOS oder Linux) aus und laden Sie es herunter.

3. Das Installationsprogramm ausführen. Stellen Sie sicher, dass Sie die Standardoption akzeptieren: Npm, den empfohlenen Paketmanager für Node.js, installieren.

4. Überprüfen Sie die Installation, indem Sie ein Terminal oder eine Eingabeaufforderung öffnen, diese Befehle eingeben und die Eingabetaste drücken.

   • node -v
   • npm -v

   Sie sollten etwas sehen, das ungefähr so aussieht:

   PS C:\Users\you> node -v
   v22.14.0
   PS C:\Users\you> npm -v
   9.5.0
   PS C:\Users\you>
   

Projekt erstellen

Die Anweisungen in diesem Abschnitt führen Sie durch die Installation von Abhängigkeiten von npm, das Erstellen der Ordnerstruktur und das Öffnen von Visual Studio Code.

1. Öffnen Sie ein Terminalfenster an einem Ort, an dem Sie ein Projekt erstellen möchten. Wir verwenden für diese Anweisungen C:\projects.

2. Geben Sie die folgenden Befehle ein, und drücken Sie die Eingabetaste, um die folgenden Aktionen auszuführen:

   Command	Aktion
   mkdir quickspa	Erstellen Sie einen neuen Ordner mit dem Namen quickspa.
   cd quickspa	Gehen Sie zum neuen quickspa-Ordner.
   npm install --save-dev parcel	Installieren Sie Parcel und initialisieren Sie das Projekt.
   npm install @azure/msal-browser	Installieren Sie die MSAL.js-Bibliothek.
   npm install dotenv	Installieren Sie dotenv, um auf Umgebungsvariablen zuzugreifen, in denen potenziell vertrauliche Konfigurationsdaten gespeichert sind.
   mkdir src	Erstellen Sie einen src-Ordner, in dem Sie in den folgenden Schritten HTML-, JS- und CSS-Dateien für Ihre App hinzufügen.
   code .	Öffnen Sie Visual Studio Code im Kontext des quickspa-Ordners.

Ihr Projekt sollte im Visual Studio Code-Explorer wie folgt aussehen:

Die .env-Datei erstellen

Im Hinblick auf die Sicherheit ist es Best Practice, die Konfigurationsdaten in der Umgebung vom Code getrennt zu speichern.

1. Erstellen Sie eine neue Datei namens .env im Stammverzeichnis Ihres quickspa-Ordners.

2. Fügen Sie die Werte aus Ihre App registrieren ein, um die CLIENT_ID- und TENANT_ID-Werte unten zu ersetzen.

   # The environment this application will connect to.
   BASE_URL=https://<yourorg>.api.crm.dynamics.com
   # The registered Entra application id
   CLIENT_ID=11112222-bbbb-3333-cccc-4444dddd5555
   # The Entra tenant id
   TENANT_ID=aaaabbbb-0000-cccc-1111-dddd2222eeee
   # The SPA redirect URI included in the Entra application registration
   REDIRECT_URI=http://localhost:1234
   

3. Legen Sie den BASE_URL-Wert auf die URL der Web-API-URL für die Umgebung fest, mit der Sie eine Verbindung herstellen möchten.

Eine HTML-Seite erstellen

In den Anweisungen in diesem Abschnitt wird beschrieben, wie die HTML-Datei erstellt wird, die die Benutzeroberfläche für die SPA-Anwendung bereitstellt.

1. Erstellen Sie eine neue Datei im src-Ordner namens index.html.

2. Kopieren Sie diesen Inhalt und fügen Sie ihn in die index.html-Seite ein:

   <!DOCTYPE html>
   <html lang="en">
     <head>
       <meta charset="UTF-8" />
       <meta name="viewport" content="width=device-width, initial-scale=1.0" />
       <title>Dataverse Web API JavaScript Quick Start</title>
       <link rel="stylesheet" href="styles/style.css" />
     </head>
     <body>
       <header>
         <h1>Dataverse Web API JavaScript Quick Start</h1>
         <button id="loginButton">Login</button>
         <button id="logoutButton" class="hidden">Logout</button>
       </header>
       <nav id="buttonContainer" class="disabled">
         <button id="whoAmIButton">WhoAmI</button>
       </nav>
       <main id="container"></main>
       <script type="module" src="scripts/index.js"></script>
     </body>
   </html>
   

Diese HTML stellt die folgenden Elemente bereit:

Ein JavaScript-Skript erstellen

Diese Datei enthält die gesamte Logik, die die index.html-Seite dynamisch macht.

1. Erstellen Sie einen neuen Ordner im src-Ordner namens scripts.

2. Erstellen Sie eine neue Datei im scripts-Ordner namens index.js.

3. Kopieren Sie diesen Inhalt und fügen Sie ihn in die index.js-Seite ein:

   import { PublicClientApplication } from "@azure/msal-browser";
   import 'dotenv/config'
   
   // Load the environment variables from the .env file
   const config = {
      baseUrl: process.env.BASE_URL,
      clientId: process.env.CLIENT_ID,
      tenantId: process.env.TENANT_ID,
      redirectUri: process.env.REDIRECT_URI,
   };
   
   // Microsoft Authentication Library (MSAL) configuration
   const msalConfig = {
     auth: {
       clientId: config.clientId,
       authority: "https://login.microsoftonline.com/" + config.tenantId,
       redirectUri: config.redirectUri,
       postLogoutRedirectUri: config.redirectUri,
     },
     cache: {
       cacheLocation: "sessionStorage", // This configures where your cache will be stored
       storeAuthStateInCookie: true,
     },
   };
   
   // Create an instance of MSAL
   const msalInstance = new PublicClientApplication(msalConfig);
   
   // body/main element where messages are displayed
   const container = document.getElementById("container");
   
   // Event handler for login button
   async function logIn() {
     await msalInstance.initialize();
   
     if (!msalInstance.getActiveAccount()) {
       const request = {
         scopes: ["User.Read", config.baseUrl + "/user_impersonation"],
       };
       try {
         const response = await msalInstance.loginPopup(request);
         msalInstance.setActiveAccount(response.account);
   
         // Hide the loginButton so it won't get pressed twice
         document.getElementById("loginButton").style.display = "none";
   
         // Show the logoutButton
         const logoutButton = document.getElementById("logoutButton");
         logoutButton.innerHTML = "Logout " + response.account.name;
         logoutButton.style.display = "block";
         // Enable any buttons in the nav element
         document.getElementsByTagName("nav")[0].classList.remove("disabled");
       } catch (error) {
         let p = document.createElement("p");
         p.textContent = "Error logging in: " + error;
         p.className = "error";
         container.append(p);
       }
     } else {
       // Clear the active account and try again
       msalInstance.setActiveAccount(null);
       this.click();
     }
   }
   
   // Event handler for logout button
   async function logOut() {
     const activeAccount = await msalInstance.getActiveAccount();
     const logoutRequest = {
       account: activeAccount,
       mainWindowRedirectUri: config.redirectUri,
     };
   
     try {
       await msalInstance.logoutPopup(logoutRequest);
   
       document.getElementById("loginButton").style.display = "block";
   
       this.innerHTML = "Logout ";
       this.style.display = "none";
       document.getElementsByTagName("nav")[0].classList.remove("disabled");
     } catch (error) {
       console.error("Error logging out: ", error);
     }
   }
   
   /**
    * Retrieves an access token using MSAL (Microsoft Authentication Library).
    * Set as the getToken function for the DataverseWebAPI client in the login function.
    *
    * @async
    * @function getToken
    * @returns {Promise<string>} The access token.
    * @throws {Error} If token acquisition fails and is not an interaction required error.
    */
   async function getToken() {
     const request = {
       scopes: [config.baseUrl + "/.default"],
     };
   
     try {
       const response = await msalInstance.acquireTokenSilent(request);
       return response.accessToken;
     } catch (error) {
       if (error instanceof msal.InteractionRequiredAuthError) {
         const response = await msalInstance.acquireTokenPopup(request);
         return response.accessToken;
       } else {
         console.error(error);
         throw error;
       }
     }
   }
   
   // Add event listener to the login button
   document.getElementById("loginButton").onclick = logIn;
   
   // Add event listener to the logout button
   document.getElementById("logoutButton").onclick = logOut;
   
   /// Function to get the current user's information
   /// using the WhoAmI function of the Dataverse Web API.
   async function whoAmI() {
     const token = await getToken();
     const request = new Request(config.baseUrl + "/api/data/v9.2/WhoAmI", {
       method: "GET",
       headers: {
         Authorization: `Bearer ${token}`,
         "Content-Type": "application/json",
         Accept: "application/json",
         "OData-Version": "4.0",
         "OData-MaxVersion": "4.0",
       },
     });
     // Send the request to the API
     const response = await fetch(request);
     // Handle the response
     if (!response.ok) {
       throw new Error("Network response was not ok: " + response.statusText);
     }
     // Successfully received response
     return await response.json();
   }
   
   // Add event listener to the whoAmI button
   document.getElementById("whoAmIButton").onclick = async function () {
     // Clear any previous messages
     container.replaceChildren();
     try {
       const response = await whoAmI();
       let p1 = document.createElement("p");
       p1.textContent =
         "Congratulations! You connected to Dataverse using the Web API.";
       container.append(p1);
       let p2 = document.createElement("p");
       p2.textContent = "User ID: " + response.UserId;
       container.append(p2);
     } catch (error) {
       let p = document.createElement("p");
       p.textContent = "Error fetching user info: " + error;
       p.className = "error";
       container.append(p);
     }
   };
   

Das index.js-Skript enthält die folgenden Konstanten und Funktionen:

Eine CSS-Seite erstellen

Die CSS-Datei (Cascading Style Sheet) macht die HTML-Seite attraktiver und spielt eine Rolle bei der Steuerung, wann Steuerelemente deaktiviert oder ausgeblendet werden.

1. Erstellen Sie einen neuen Ordner namens styles im src-Ordner.

2. Erstellen Sie eine neue Datei namens style.cssim styles-Ordner.

3. Kopieren Sie diesen Text und fügen Sie ihn in die style.css-Datei ein:

   .disabled {
      pointer-events: none;
      opacity: 0.5;
      /* Optional: to visually indicate the element is disabled */
   }
   
   .hidden {
      display: none;
   }
   
   .error {
      color: red;
   }
   
   .expectedError {
      color: green;
   }
   
   body {
      font-family: 'Roboto', sans-serif;
      font-size: 16px;
      line-height: 1.6;
      color: #333;
      background-color: #f9f9f9;
   }
   
   h1,
   h2,
   h3 {
      color: #2c3e50;
   }
   
   button {
      background-color: #3498db;
      color: #fff;
      border: none;
      padding: 10px 20px;
      border-radius: 5px;
      box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
      transition: background-color 0.3s ease;
      margin: 5px;
      /* Adjust the value as needed */
   }
   
   button:hover {
      background-color: #2980b9;
   }
   
   header {
      padding-bottom: 10px;
      /* Adjust the value as needed */
   }
   

Die .gitignore-Datei erstellen

Wenn Ihre App mit der Quellcodeverwaltung eingecheckt ist, verhindert das Hinzufügen einer .gitignore-Datei das Einchecken der angegebenen Dateien und Ordner.

1. Erstellen Sie eine Datei namens .gitignore.

2. Fügen Sie die folgenden Inhalte hinzu:

   .parcel-cache
   dist
   node_modules
   .env
   

Die .parcel-cache- und dist-Ordner werden angezeigt, wenn Sie die App zum ersten Mal ausführen.

Das Nichteinchecken der .env-Datei ist Best Practice im Hinblick auf die Sicherheit. Möglicherweise möchten Sie eine .env.sample-Platzhalterdatei mit Platzhalterwerten einchecken.

Ihr Projekt sollte im Visual Studio Code-Explorer wie folgt aussehen:

package.json Datei konfigurieren

Ihre package.json-Datei sollte in etwa so aussehen:

{
  "devDependencies": {
    "parcel": "^2.14.1",
  },
  "dependencies": {
    "@azure/msal-browser": "^4.7.0",
    "dotenv": "^16.4.7"
  }
}

Fügen Sie dieses scripts-Element unterhalb von dependencies hinzu:

  "dependencies": {
    "@azure/msal-browser": "^4.7.0",
    "dotenv": "^16.4.7"
  },
  "scripts": {
    "start": "parcel src/index.html"
  }

Mit dieser Konfiguration können Sie die Anwendung mithilfe von npm start im nächsten Schritt starten.

Ausprobieren

1. Öffnen Sie in Visual Studio Code ein Terminalfenster

2. Geben Sie npm start ein, und drücken Sie die Eingabetaste.

   Anmerkung

   Möglicherweise wird eine Ausgabe in das Terminal geschrieben, während das Projekt zum ersten Mal initialisiert wird. Das ist Parcel, das einige weitere Node-Module installiert, um Probleme bei der Verwendung von dotenv einzudämmen. Schauen Sie sich die package.json an. Sie sollten einige neue Elemente in der devDependencies sehen.

   Sie sollten eine Ausgabe an das Terminal erwarten, die wie folgt aussieht:

   Server running at http://localhost:1234
   Built in 1.08s
   

3. Drücken Sie Strg und klicken Sie auf den Link http://localhost:1234, um Ihren Browser zu öffnen.

4. Wählen Sie in Ihrem Browser die Schaltfläche Anmelden aus.

   Das Dialogfeld Bei Ihrem Konto anmelden wird geöffnet.

5. Wählen Sie im Dialogfeld Bei Ihrem Konto anmelden das Konto aus, das Zugriff auf Dataverse hat.

   Wenn Sie zum ersten Mal mit einem neuen Wert für die Anwendungs-ID (Client) zugreifen, wird dieses Dialogfeld Berechtigungen angefordert angezeigt:

   

6. Wählen Sie im Dialogfeld Berechtigungen angefordert die Option Annehmen aus.

7. Wählen Sie die WhoAmI-Schaltfläche aus.

   Die Nachricht Herzlichen Glückwunsch! Sie haben eine Verbindung mit Dataverse mithilfe der Web-API hergestellt. wird mit Ihrem UserId-Wert aus dem komplexen Typ WhoAmIResponse angezeigt.

Problembehandlung

Dieser Abschnitt enthält Fehler, die bei der Ausführung dieses Schnellstarts auftreten können.

Ausgewähltes Benutzerkonto ist im Mandanten nicht vorhanden

Wenn das von Ihnen ausgewählte Konto nicht zum selben Microsoft Entra-Mandanten wie die registrierte Anwendung gehört, wird im Dialogfeld Konto auswählen die folgende Fehlermeldung angezeigt:

Selected user account does not exist in tenant '{Your tenant name}' and cannot access the application '{Your application ID}' in that tenant. The account needs to be added as an external user in the tenant first. Please use a different account.

Lösung: Stellen Sie sicher, dass Sie den richtigen Benutzenden auswählen.

Nächste Schritte,

Versuchen Sie es mit anderen Beispielen, in denen clientseitiges JavaScript verwendet wird.

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