Démarrage rapide : API web avec JavaScript côté client et Visual Studio Code

Ce guide de démarrage rapide vous montre comment authentifier et connecter une application monopage JavaScript à l’API Web Dataverse dans Visual Studio Code à l’aide des technologies suivantes. Vous créez une application qui connecte un utilisateur, appelle la fonction WhoAmI et affiche l’ID de l’utilisateur.

Goal

Ce guide de démarrage rapide se concentre sur la connexion à l’API web Dataverse avec JavaScript à l’aide d’une application cliente SPA avec un nombre minimal d’étapes. Lorsque vous avez terminé ce guide de démarrage rapide, vous pouvez :

• Connectez-vous et connectez-vous à Dataverse.
• Appeler la fonction WhoAmI et afficher votre valeur UserID.

En suivant ce guide de démarrage rapide, vous pouvez essayer les exemples d’opérations de données de l’API web (JavaScript côté client) qui illustrent des fonctionnalités plus avancées.

Prérequis

Le tableau suivant décrit les conditions préalables nécessaires pour exécuter ce guide de démarrage rapide et les exemples d’opérations de données de l’API web (JavaScript côté client).

Enregistrer une application SPA

Cette étape est d’abord due au fait que si vous ne pouvez pas inscrire une application, vous ne pouvez pas suivre ce guide de démarrage rapide.

N’importe lequel des rôles Microsoft Entra privilégiés suivants inclut les autorisations requises :

• Administrateur d’application
• Développeur d’applications
• Administrateur d’applications cloud

Lorsque vous configurez l’application, vous avez besoin d’un ID d’application (client) et de l’ID de votre client Microsoft Entra. Choisissez un nom descriptif pour l’application afin que les personnes sachent à quoi l’application a été créée.

Enregistrer votre application

Vous pouvez inscrire votre application à l’aide de l’une des options suivantes :

• Interface utilisateur de l’application web Microsoft Entra
• Azure PowerShell applet de commande New-AzADApplication

Installer Node.js

1. Accédez à Télécharger Node.js.

2. Choisissez le programme d’installation approprié pour votre système d’exploitation (Windows, macOS ou Linux) et téléchargez-le.

3. Exécutez le programme d’installation. Assurez-vous d’accepter l’option par défaut pour : Installer npm, le gestionnaire de package recommandé pour Node.js.

4. Vérifiez l’installation en ouvrant un terminal ou une invite de commandes, en tapant ces commandes et en appuyant sur Entrée.

   • node -v
   • npm -v

   Vous voyez une sortie similaire à celle-ci :

   PS C:\Users\you> node -v
   v24.19.0
   PS C:\Users\you> npm -v
   11.17.0
   PS C:\Users\you>
   

Créer un projet

Cette section vous guide tout au long de l’installation des dépendances à partir de npm, la création de la structure de dossiers et l’ouverture de Visual Studio Code.

1. Ouvrez une fenêtre de terminal à un emplacement où vous souhaitez créer un projet. Pour ces instructions, utilisez C:\projects.

2. Tapez les commandes suivantes et appuyez sur Entrée pour exécuter chaque commande :

   Command	Action
   mkdir quickspa	Créez un dossier appelé quickspa.
   cd quickspa	Accédez au nouveau dossier quickspa.
   npm install --save-dev parcel	Installez Parcel et initialisez le projet.
   npm install @azure/msal-browser	Installez la bibliothèque MSAL.js.
   npm install dotenv	Installez dotenv pour accéder aux variables d’environnement qui stockent des données de configuration potentiellement sensibles.
   mkdir src	Créez un dossier src dans lequel vous ajoutez des fichiers HTML, JS et CSS pour votre application dans les étapes suivantes.
   code .	Ouvrez Visual Studio Code dans le contexte du dossier quickspa.

Votre projet devrait ressembler à ceci dans l’Explorateur Visual Studio Code :

Créer le fichier .env

Le stockage des données de configuration dans l’environnement, séparé du code, est une bonne pratique de sécurité.

1. Créez un nouveau fichier nommé .env dans la racine de votre dossier quickspa.

2. Collez les valeurs de Register your app pour remplacer les valeurs et TENANT_ID les CLIENT_ID valeurs dans le code suivant :

   # 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/redirect.html
   

3. Définissez la valeur BASE_URL sur l’URL de l’API web pour l’environnement auquel vous souhaitez vous connecter.

Créer une page HTML

Les instructions de cette section décrivent comment créer le fichier HTML qui fournit l’interface utilisateur de l’application SPA.

1. Créez un nouveau fichier dans le dossier src nommé index.html.

2. Copiez et collez ce contenu sur la page index.html :

   <!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>
   

Cette page HTML fournit les éléments suivants :

Créer une page HTML de redirection

MSAL Browser v5 a introduit la prise en charge des applications qui sont traitées avec des en-têtes Cross-Origin-Opener-Policy (COOP), et cette modification nécessite une page de pont de redirection pour passer en toute sécurité la réponse d’authentification à la fenêtre SPA principale. Découvrez comment configurer la page pont de redirection dans MSAL Browser

1. Créez un nouveau fichier dans le dossier src nommé redirect.html.

2. Copiez et collez ce contenu sur la page redirect.html :

   <!DOCTYPE html>
   <html lang="en">
     <head>
       <meta charset="UTF-8" />
       <meta name="viewport" content="width=device-width, initial-scale=1.0" />
       <title>Signing in</title>
     </head>
     <body>
       <p>Processing authentication...</p>
       <script type="module">
         import { broadcastResponseToMainFrame } from "@azure/msal-browser/redirect-bridge";
   
         broadcastResponseToMainFrame().catch((error) => {
           console.error("Error broadcasting authentication response:", error);
         });
       </script>
     </body>
   </html>
   

Créer un script JavaScript

Ce fichier contient toute la logique qui rend la page index.html dynamique.

1. Créez un nouveau dossier dans le dossier src nommé scripts.

2. Créez un nouveau fichier dans le dossier scripts nommé index.js.

3. Copiez et collez ce contenu dans le index.js fichier :

   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);
     }
   };
   

Le script index.js contient les constantes et les fonctions suivantes :

Créer une page CSS

Le fichier feuille de style en cascade (CSS) rend la page HTML plus attrayante et les contrôles lorsque les contrôles sont désactivés ou masqués.

1. Créez un nouveau dossier nommé styles dans le dossier src.

2. Créez un nouveau fichier nommé style.css dans le dossier styles.

3. Copiez et collez ce texte dans le fichier style.css :

   .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 */
   }
   

Créer un fichier .gitignore

Lorsque vous vérifiez votre application à l’aide du contrôle de code source, l’ajout d’un .gitignore fichier vous empêche d’archiver les fichiers et dossiers spécifiés.

1. Créez un fichier nommé .gitignore.

2. Ajoutez le contenu suivant :

   .parcel-cache
   dist
   node_modules
   .env
   

Les dossiers .parcel-cache et dist s’affichent lorsque vous exécutez l’application pour la première fois.

Ne pas enregistrer le fichier .env est une bonne pratique de sécurité. Vous souhaiterez peut-être enregistrer un fichier .env.sample d’espace réservé contenant des valeurs d’espace réservé.

Votre projet devrait ressembler à ceci dans l’Explorateur Visual Studio Code :

Configurer votre fichier package.json

Votre package.json fichier doit ressembler à l’exemple suivant :

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

Ajoutez les éléments et @parcel/resolver-default les scripts éléments après dependencies:

  "dependencies": {
    "@azure/msal-browser": "^5.17.3",
    "dotenv": "^17.4.2"
  },
  "scripts": {
    "start": "parcel src/index.html src/redirect.html"
  },
  "@parcel/resolver-default": {
    "packageExports": true
  }

La @parcel/resolver-default configuration active le comportement de résolution des exportations de package de Packages. Cette configuration est nécessaire pour résoudre @azure/msal-browsercorrectement , qui utilise le champ d’exportation dans ses métadonnées de package. Selon la version de Colis que vous utilisez, ce paramètre n’est peut-être pas nécessaire, mais il a été conservé pour garantir la compatibilité avec la dépendance MSAL de l’exemple.

Cette configuration vous permet de démarrer l’application à l’aide npm start de l’étape suivante.

Essayez-le

1. Dans Visual Studio Code, ouvrez une fenêtre de terminal.

2. Tapez npm start, puis appuyez sur Entrée.

   Nonte

   Il se peut qu’une sortie soit écrite dans le terminal lorsque le projet s’initialise pour la première fois. Cette sortie est l’installation de modules Node supplémentaires pour éviter les problèmes lors de l’utilisation de dotenv. Examinez les package.json éléments et vous voyez quelques nouveaux éléments ajoutés à l’élément devDependencies.

   Vous voyez la sortie vers le terminal qui ressemble à ceci :

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

3. Appuyez sur Ctrl + clic sur le lien http://localhost:1234 pour ouvrir votre navigateur.

4. Dans votre navigateur, sélectionnez le bouton Connexion.

   La boîte de dialogue Se connecter à votre compte s’ouvre.

5. Dans la boîte de dialogue Se connecter à votre compte, sélectionnez le compte ayant accès à Dataverse.

   La première fois que vous accédez à Dataverse à l’aide d’une nouvelle valeur d’ID d’application (client), vous voyez cette boîte de dialogue Autorisations demandées :

   

6. Sélectionnez Accepter dans la boîte de dialogue Autorisations demandées.

7. Sélectionnez le bouton WhoAmI.

   Le message Félicitations ! Vous vous êtes connecté à Dataverse l’aide de l’API web. s’affiche avec votre valeur UserId du type complexe WhoAmIResponse.

Résolution des problèmes

Cette section contient des erreurs que vous pouvez rencontrer lors de l’exécution de ce démarrage rapide.

Le compte d’utilisateur sélectionné n’existe pas dans le client

Lorsque le compte que vous sélectionnez n’appartient pas au même client Microsoft Entra que l’application enregistrée, vous obtenez cette erreur dans la boîte de dialogue Choisir un compte :

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.

Résolution : assurez-vous de choisir l’utilisateur correct.

Étapes suivantes

Essayez d’autres exemples qui utilisent JavaScript côté client.

En savoir plus sur les fonctionnalités de l’API web Dataverse en comprenant les documents de service.