Partager via

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

Ce démarrage rapide montre comment vous connecter à Dataverse et utiliser l’API web avec les technologies suivantes :

Technologie Description
JavaScript Un langage de programmation pour le développement web, permettant un contenu interactif. Il s’exécute dans les navigateurs pour les scripts côté client et peut être utilisé côté serveur avec Node.js.
Visual Studio Code Un éditeur de code open source léger avec débogage, surbrillance syntaxique et prise en charge des plug-ins.
Applications à une seule page (SPA) Applications Web qui chargent une seule page HTML et mettent à jour dynamiquement le contenu lorsque l’utilisateur interagit avec l’application. Cette approche offre une expérience utilisateur plus fluide et plus rapide en réduisant le rechargement des pages et en améliorant les performances.
Bibliothèque d’authentification Microsoft pour JavaScript (MSAL.js) Une bibliothèque qui permet l’authentification et l’autorisation pour les applications Web utilisant les plateformes d’identité Microsoft. Il simplifie l’intégration de la connexion sécurisée et de l’acquisition de jetons pour accéder aux ressources protégées.
Partage de ressources cross-origin (CORS) Une application SPA peut utiliser JavaScript côté client avec l’API web Dataverse car CORS est activé. CORS est une fonctionnalité de sécurité dans les navigateurs Web qui permet un accès contrôlé aux ressources d’un serveur Web à partir d’une origine différente. Il permet aux applications web de contourner la stratégie de même origine, ce qui facilite le partage de données entre différents domaines.

Goal

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

  • Ouvrir une session et vous connecter à Dataverse
  • Appeler la fonction WhoAmI et afficher votre valeur UserID.

Exécution du démarrage rapide terminée

L’exécution de ce démarrage rapide vous permet d’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.

Nonte

Ce guide de démarrage rapide ne s’applique pas aux scénarios JavaScript côté client suivants :

Scénario En savoir plus
Scripts de l’application pilotée par modèle - Appliquer la logique métier en utilisant le script client dans les applications pilotées par modèle avec Javascript
- Xrm.WebApi (référence de l’API client)
Power Apps component framework - WebAPI des composants de code
- Mise en œuvre du composant API web
Portails Power Pages Power PagesPortails API web

Dans ces scénarios, le type d’application respectif vous permet d’envoyer des requêtes plutôt que d’utiliser directement l’API Fetch native JavaScript, comme indiqué dans ce démarrage rapide. Les scripts côté client dans les applications pilotées par modèle s’exécutent dans le contexte d’une application authentifiée, de sorte que chaque demande ne nécessite pas de jeton d’accès.

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

Conditions préalables Description
Privilèges pour créer un enregistrement d’application Entra Vous ne pouvez pas exécuter ce démarrage rapide sans la possibilité de créer un enregistrement d’application Microsoft Entra pour l’activer.

Si vous n’êtes pas sûr de pouvoir le faire, essayez la première étape pour Enregistrer une application SPA et découvrez-le.
Visual Studio Code Si Visual Studio Code n’est pas installé sur votre ordinateur, vous devez Télécharger et installer Visual Studio Code pour exécuter ce démarrage rapide.
Node.js Node.js est un environnement d’exécution qui vous permet d’exécuter JavaScript côté serveur. Ce guide de démarrage rapide crée une application SPA qui exécute JavaScript côté client dans un navigateur plutôt que le runtime Node.js. Mais Node Package Manager (npm) est installé avec Node.js et npm est nécessaire pour installer Parcel et la bibliothèque MSAL.js.
Colis Les applications Web modernes ont généralement de nombreuses dépendances aux bibliothèques open source distribuées à l’aide de npm et de scripts qui doivent être gérés et optimisés pendant le processus de génération. Ces outils sont appelés « bundlers ». Le plus courant est webpack. Ce démarrage rapide utilise Parcel car il offre une expérience simplifiée.

Pour des démarrages rapides et des exemples qui montrent des applications SPA utilisant différents cadres et bundlers, consultez Exemples d’applications à une seule page Microsoft Entra. Vous pouvez adapter ces exemples pour utiliser l’API web Dataverse avec les informations présentées dans ce démarrage rapide.
Technologies web Une connaissance de HTML, JavaScript et CSS est nécessaire pour comprendre le fonctionnement de ce démarrage rapide. Il est essentiel de comprendre comment effectuer des requêtes réseau avec JavaScript.

Enregistrer une application SPA

Cette étape est la première, car si vous ne pouvez pas enregistrer une application, vous ne pouvez pas effectuer ce démarrage rapide.

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

Lorsque vous configurez l’application, vous avez besoin d’un ID d’application (client) et de l’ID de votre client Microsoft Entra. Vous devez également choisir un nom descriptif pour l’application afin que les utilisateurs sachent pourquoi l’application a été créée.

Enregistrer votre application

Vous pouvez enregistrer votre demande à l’aide de l’un des moyens suivants :

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

Créer l’enregistrement d’application

  1. Connectez-vous au centre d’administration Microsoft Entra.

  2. Si vous avez accès à plusieurs clients, utilisez l’icône Paramètres dans le menu supérieur pour basculer vers le client dans lequel vous souhaitez enregistrer l’application à partir du menu Répertoires + abonnements.

  3. Accédez à Identité>Applications>Enregistrements d’applications et sélectionnez Nouvel enregistrement.

  4. Entrez un Nom pour l’application, par exemple Dataverse Web API Quickstart SPA.

  5. Pour Types de comptes pris en charge, sous Qui peut utiliser cette application ou accéder à cette API, sélectionnez Comptes dans ce repertoire organisationnel uniquement (<Le nom de votre client> - Client unique).

  6. Pour URI de redirection (facultatif)

    1. Pour Sélectionner une plateforme, sélectionnez Application à une seule page (SPA).
    2. Entrez http://localhost:1234 comme valeur.

  7. Sélectionnez Enregistrer pour appliquer vos modifications.

  8. Dans la fenêtre de l’enregistrement d’application que vous avez créé, dans l’onglet Vue d’ensemble, sous Essentiels, vous pouvez trouver ces valeurs :

    • ID d’application (client)
    • ID du répertoire (locataire)

  9. Copiez ces valeurs, car vous en avez besoin lorsque vous créez le fichier .env pour utiliser les variables d’environnement.

Ajouter le privilège user_impersonation de Dataverse

  1. Dans la zone Gérer, sélectionnez Autorisations de l’API.
  2. Sélectionnez Ajouter une autorisation.
  3. Dans la zone Demander les autorisations de l’API, sélectionnez l’onglet API utilisées par mon organisation.
  4. Tapez « Dataverse » pour trouver l’ID d’application (client) 00000007-0000-0000-c000-000000000000.
  5. Sélectionnez l’application Dataverse.
  6. Dans Sélectionner les autorisations, user_impersonation est la seule autorisation déléguée disponible. Sélectionnez-le.
  7. Sélectionnez Ajouter des autorisations.

Nonte

Si vous n’avez pas les privilèges nécessaires pour créer un enregistrement d’application pour votre entreprise, obtenez votre propre client via le Plan pour développeur Power Apps.

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 devriez voir un message similaire au suivant :

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

Créer un projet

Nonte

Vous pouvez ignorer ces étapes en clonant ou en téléchargeant le référentiel PowerApps-Samples. L'application complétée pour ces étapes est disponible à l’adresse /dataverse/webapi/JS/quickspa. Suivez les instructions du fichier LISEZMOI.

Les instructions de cette section vous aident à installer les dépendances à partir de npm, à créer la structure de dossiers et à ouvrir Visual Studio Code.

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

  2. Tapez les commandes suivantes et appuyez sur Entrée pour effectuer les actions suivantes :

    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 :

Affiche le projet quickspa nouvellement créé avant l’ajout des fichiers.

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 à partir de Enregistrer votre application pour remplacer les valeurs CLIENT_ID et TENANT_ID ci-dessous.

    # 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. Définissez la valeur BASE_URL sur l’URL de l’API web pour l’environnement auquel vous souhaitez vous connecter.

Nonte

Vous n’enregistrerez pas le fichier .env. Dans Créer un fichier .gitignore, vous l’exclurez. Mais vous souhaiterez peut-être créer un fichier .env.example en utilisant les valeurs d’espace réservé afin que les utilisateurs sachent quelles données il doit contenir.

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 :

ID de l’élément Type d’élément Description
loginButton bouton Pour ouvrir la boîte de dialogue de connexion.
logoutButton bouton Pour ouvrir la boîte de dialogue de déconnexion. Masqué par défaut.
buttonContainer nav Contient des boutons qui nécessitent que l’utilisateur soit connecté pour être utilisés. Désactivé par défaut.
whoAmIButton bouton Exécute la fonction WhoAmI pour afficher l’ID de l’utilisateur.
container principal Zone où les informations peuvent être affichées à l’utilisateur.
script Charge le fichier index.js après le chargement du reste des éléments de la page.

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 la page index.js :

    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 :

Item Description
config Contient les données utilisées par la configuration de la bibliothèque d’authentification Microsoft (MSAL).
msalConfig Configuration de la bibliothèque d’authentification Microsoft (MSAL)
msalInstance Instance PublicClientApplication de MSAL.
container Élément dans lequel les messages sont affichés.
getToken Récupère un jeton d’accès à l’aide de MSAL.
logIn Fonction d’écoute d’événements pour le bouton de connexion. Ouvre une boîte de dialogue de choix de compte.
logOut Fonction d’écouteur d’événements pour le bouton de déconnexion. Ouvre une boîte de dialogue de choix de compte.
whoAmI Fonction asynchrone qui appelle la fonction WhoAmI pour récupérer des données de Dataverse.
Écouteur d’événements whoAmIButton Fonction qui appelle la fonction whoAmI et gère les modifications de l’interface utilisateur pour afficher le message.

Créer une page CSS

Le fichier Feuille de style en cascade (CSS) rend la page HTML plus attrayante et joue un rôle dans le contrôle de la désactivation ou du masquage des contrôles.

  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 votre application est enregistrée avec le contrôle de code source, l’ajout d’un fichier .gitignore empêche l’enregistrement des 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 :

Affiche le projet quickspa après l’ajout des fichiers.

Configurer votre fichier package.json

Votre fichier package.json doit ressembler à ce qui suit :

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

Ajoutez cet élément scripts sous dependencies :

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

Cette configuration vous permet de démarrer l’application en utilisant npm start dans 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. Parcel installe des modules Node.js supplémentaires pour atténuer les problèmes lors de l’utilisation de dotenv. Recherchez le fichier package.json et vous devriez voir de nouveaux éléments ajoutés à devDependencies.

    Vous devez vous attendre à une 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 en utilisant une nouvelle valeur d’ID d’application (client), cette boîte de dialogue Autorisations demandées s’affiche :

    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.

Nonte

Si vous rencontrez des problèmes lors de l’exécution des étapes de ce démarrage rapide, essayez de cloner ou de télécharger le référentiel PowerApps-Samples. L'application complétée pour ces étapes est disponible à l’adresse /dataverse/webapi/JS/quickspa. Suivez les instructions du fichier LISEZMOI. Si cela ne fonctionne pas, créez un problème GitHub faisant référence à cet exemple d’application quickspa.

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.

Exemples d’opérations de données de l’API Web (JavaScript côté client)

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

Types d’API web et opérations