Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
En este inicio rápido se muestra cómo autenticar y conectar una aplicación de página única (SPA) de JavaScript a la API web de Dataverse en Visual Studio Code mediante las siguientes tecnologías. Compila una aplicación que inicia sesión en un usuario, llama a la función WhoAmI y muestra el identificador del usuario.
| Tecnología | Description |
|---|---|
| Javascript | Un lenguaje de programación para el desarrollo web, que permite contenido interactivo. Se ejecuta en los navegadores para scripting del lado del cliente y se puede usar en el lado del servidor con Node.js. |
| Código de Visual Studio | Un editor de código ligero y de código abierto con depuración, resaltado de sintaxis y compatibilidad con complementos. |
| Aplicación de una sola página (SPA) | Aplicaciones web que cargan una sola página HTML y actualizan el contenido de forma dinámica a medida que el usuario interactúa con la aplicación. Este enfoque proporciona una experiencia de usuario más fluida y rápida al reducir las recargas de páginas y mejorar el rendimiento. |
| El soporte para Microsoft Authentication Library para JavaScript (MSAL.js) | Una biblioteca que permite la autenticación y autorización de aplicaciones web mediante plataformas de identidad Microsoft. Simplifica la integración del inicio de sesión seguro y la adquisición de tokens para acceder a recursos protegidos. |
| Intercambio de Recursos de Origen Cruzado (CORS) | Una aplicación de SPA puede usar JavaScript del lado cliente con la API web de Dataverse porque CORS está habilitado. CORS es una característica de seguridad en los navegadores web que permite el acceso controlado a los recursos de un servidor web desde un origen diferente. Permite que las aplicaciones web omitan la directiva de mismo origen, facilitando el intercambio seguro de datos entre diferentes dominios. |
Goal
Este inicio rápido se centra en la conexión a la API web de Dataverse con JavaScript mediante una aplicación cliente spa con un número mínimo de pasos. Al completar este inicio rápido, puede hacer lo siguiente:
- Inicie sesión y conéctese a Dataverse.
- Invoque la función WhoAmI y muestre su valor
UserID.
Al completar este inicio rápido, puede probar los ejemplos de operaciones de datos de API web (JavaScript del lado cliente) que muestran funcionalidades más avanzadas.
Nota
Este inicio rápido no se aplica a los siguientes escenarios de JavaScript del lado cliente:
| Escenario | Más información |
|---|---|
| Scripts de aplicaciones basadas en modelos |
-
Aplicar la lógica de negocios usando scripting de cliente en aplicaciones basadas en modelos que usan JavaScript - Xrm.WebApi (referencia de API de cliente) |
| Power Apps marco de componentes |
-
Componentes de código WebAPI - Implementar componente de API web |
| Portales de Power Pages | Power PagesAPI web de portales |
En estos escenarios, el tipo de aplicación correspondiente proporciona una capacidad para enviar solicitudes en lugar de usar la Fetch API nativa de JavaScript directamente, como se muestra en este inicio rápido. Los scripts del lado cliente dentro de las aplicaciones basadas en modelo se ejecutan en el contexto de una aplicación autenticada, por lo que cada solicitud no requiere un token de acceso.
Requisitos previos
En la tabla siguiente se describen los requisitos previos necesarios para completar este inicio rápido y los ejemplos de operaciones de datos de la API web (JavaScript del lado del cliente).
| Requisito previo | Description |
|---|---|
| Privilegios para crear un registro de aplicación Entra | Necesita la capacidad de crear un registro de aplicación Microsoft Entra para completar este inicio rápido. Si no está seguro de si tiene esta capacidad, pruebe el primer paso para registrar una aplicación SPA y averiguarlo. |
| Visual Studio Code | Si Visual Studio Code no está instalado en el equipo, descargue e instale Visual Studio Code para ejecutar este inicio rápido. |
| Node.js | Node.js es un entorno de tiempo de ejecución que le permite ejecutar JavaScript en el lado del servidor. Este inicio rápido crea una aplicación SPA que ejecuta JavaScript en el lado cliente en un navegador en lugar de en el tiempo de ejecución Node.js. Pero Node Administrador de paquetes (npm) se instala con Node.js, y necesita npm para instalar Parcel y la biblioteca MSAL.js. |
| Paquete | Las aplicaciones web modernas suelen tener muchas dependencias de bibliotecas de código abierto distribuidas mediante npm y scripts que deben administrarse y optimizarse durante el proceso de compilación. Estas herramientas se denominan agrupadores. El más común es webpack.
VITE también es popular. En este inicio rápido se usa Parcel porque ofrece una experiencia simplificada. Para obtener inicios rápidos y ejemplos que muestran aplicaciones de SPA con diferentes marcos y empaquetadores, vea Ejemplos de aplicaciones de una sola página de Microsoft Entra. Puede adaptar estos ejemplos para usar la API web de Dataverse con la información que se muestra en este inicio rápido. |
| Tecnologías web | Conocimientos de HTML, JavaScript y CSS son necesarios para comprender cómo funciona este inicio rápido. Comprender cómo realizar solicitudes de red usando JavaScript es esencial. |
Registrar una aplicación de SPA
Este paso es primero porque si no puede registrar una aplicación, no puede completar este inicio rápido.
Cualquiera de los siguientes roles Microsoft Entra con privilegios incluye los permisos necesarios:
- Administrador de aplicaciones
- Desarrollador de aplicaciones
- Administrador de aplicaciones en la nube
Cuando configure la aplicación, necesitará el identificador de aplicación (cliente) y el de su inquilino de Microsoft Entra. Elija un nombre descriptivo para la aplicación para que los usuarios sepan para qué se creó la aplicación.
Registrar su aplicación
Puede registrar la aplicación mediante cualquiera de las siguientes opciones:
- IU de aplicación web de Microsoft Entra
- Azure PowerShell cmdlet New-AzADApplication
Use el Centro de administración Microsoft Entra para crear un registro de aplicación SPA de inquilino único, configurar su URI de redirección, copiar los identificadores de inquilino y la aplicación y agregar el permiso Dataverseuser_impersonation.
Crear el registro de la aplicación
Inicie sesión en el Centro de administración de Microsoft Entra.
Si tiene acceso a varios inquilinos, use el icono Configuración
del menú superior para cambiar al inquilino donde desea registrar la aplicación en el menú Directorios y suscripciones .Vaya a Registros de aplicaciones y seleccione Nuevo registro.
Escriba un Nombre para la aplicación, como
Dataverse Web API Quickstart SPA.En Tipos de cuenta admitidos, en Elegir los tipos de cuenta que pueden usar esta aplicación o acceder a esta API, seleccione Solo inquilino único: <el nombre> del inquilino.
Para URI de redireccionamiento (opcional)
- En Seleccionar una plataforma, elija Aplicación de una sola página (SPA).
- Especifique el valor como
http://localhost:1234/redirect.html.
Seleccione Registrar para guardar los cambios.
En la ventana del registro de la aplicación que creó, en la pestaña Información general , en Essentials, puede encontrar estos valores:
- Identificador de aplicación (cliente)
- Id. de de directorio (inquilino)
Copie estos valores porque los necesita al crear el archivo .env para utilizar variables de entorno.
Agregue un privilegio de Dataverse user_impersonation
- En el área Administrar, seleccione Permisos de API.
- Seleccione Agregar permiso.
- En el área Solicitar permisos de API, seleccione la pestaña API que usa mi organización.
- Escriba 'Dataverse' para buscar el identificador de la aplicación (cliente)
00000007-0000-0000-c000-000000000000. - Seleccione la aplicación Dataverse.
- En Seleccionar permisos, seleccione
user_impersonation. - Seleccione Agregar permisos.
Nota
Si no tiene los privilegios para crear un registro de aplicaciones para su empresa, obtenga un inquilino propio a través del plan para desarrolladores de Power Apps.
Instalar Node.js
Vaya a Descargar Node.js.
Elija el instalador adecuado para su sistema operativo (Windows, macOS o Linux) y descárguelo.
Ejecute el instalador. Asegúrese de aceptar la opción predeterminada para: Instalar npm, el administrador de paquetes recomendado para Node.js.
Para comprobar la instalación, abra un terminal o símbolo del sistema, escriba estos comandos y presione Entrar.
node -vnpm -v
Verá una salida similar a la siguiente:
PS C:\Users\you> node -v v24.19.0 PS C:\Users\you> npm -v 11.17.0 PS C:\Users\you>
Crea un proyecto
Nota
Para omitir estos pasos, clone o descargue el repositorio PowerApps-Samples . La aplicación completa para estos pasos está disponible en /dataverse/webapi/JS/quickspa. Siga las instrucciones del LÉEME.
Esta sección le guía por la instalación de dependencias desde npm, la creación de la estructura de carpetas y la apertura de Visual Studio Code.
Abra una ventana de terminal en una ubicación donde quiera crear un proyecto. Para obtener estas instrucciones, use
C:\projects.Escriba los siguientes comandos y presione Entrar para ejecutar cada comando:
Command Acción mkdir quickspaCree una nueva carpeta llamada quickspa.cd quickspaMueva a la nueva carpeta quickspa.npm install --save-dev parcelInstale Parcel e inicialice el proyecto. npm install @azure/msal-browserInstale la biblioteca MSAL.js. npm install dotenvInstale dotenv para acceder a variables de entorno que almacenan datos de configuración potencialmente confidenciales. mkdir srcCree una carpeta srcdonde agregar archivos HTML, JS y CSS para su aplicación en los siguientes pasos.code .Abra Visual Studio Code en el contexto de la carpeta quickspa.
El proyecto debería tener este aspecto en Visual Studio Code Explorer:
Nota
Visual Studio Code puede mostrar un mensaje: el modo restringido está diseñado para la exploración de código segura. Confíe en esta carpeta para habilitar todas las características. Seleccione Administrar y elija confiar en la carpeta. Más información sobre la confianza del área de trabajo
Crear el archivo .env
Almacenar los datos de configuración en el entorno separados del código es una práctica recomendada de seguridad.
Cree un nuevo archivo llamado
.enven la raíz de su carpetaquickspa.Pegue los valores de Register your app (Registrar la aplicación ) para reemplazar los
CLIENT_IDvalores yTENANT_IDen el código siguiente:# 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.htmlEstablezca el valor
BASE_URLa la URL de la API web URL del entorno al que desea conectarse.
Nota
No marque el .env archivo. En Crear .gitignore archivo, se excluye. Pero es posible que desee crear un archivo .env.example con los valores de marcador de posición para que los usuarios sepan qué datos debe contener.
Crear una página HTML
Las instrucciones de esta sección describen cómo crear el archivo HTML que proporciona la interfaz de usuario para la aplicación SPA.
Cree un nuevo archivo en la carpeta
srcllamadoindex.html.Copie y pegue este contenido en la página
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>
Esta HTML proporciona los siguientes elementos:
| Id. elemento | Tipo de elemento | Description |
|---|---|---|
loginButton |
botón | Para abrir el cuadro de diálogo de inicio de sesión. |
logoutButton |
botón | Para abrir el cuadro de diálogo de cierre de sesión. Oculto de forma predeterminada. |
buttonContainer |
nav | Contiene botones que requieren que el usuario inicie sesión para usarlo. Deshabilitado de forma predeterminada. |
whoAmIButton |
botón | Ejecuta la función WhoAmI para mostrar el identificador del usuario. |
container |
main | Área donde puede mostrar información al usuario. |
| script | Carga el index.js archivo después del resto de los elementos de la página. |
Crear página HTML de redirección
MSAL Browser v5 introdujo compatibilidad con aplicaciones que se sirven con encabezados cross-origin-Opener-Policy (COOP) y ese cambio requiere una página de puente de redirección para pasar de forma segura la respuesta de autenticación a la ventana principal de SPA. Obtenga información sobre cómo configurar la página del puente de redireccionamiento en el explorador MSAL.
Cree un nuevo archivo en la carpeta
srcllamadoredirect.html.Copie y pegue este contenido en la página
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>
Crear un script de JavaScript
Este archivo contiene toda la lógica que hace que la página index.html sea dinámica.
Cree una carpeta nueva en la carpeta
srcllamadascripts.Cree un nuevo archivo en la carpeta
scriptsllamadoindex.js.Copie y pegue este contenido en el
index.jsarchivo: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); } };
El script index.js contiene las siguientes constantes y funciones:
| Item | Description |
|---|---|
config |
Contiene los datos utilizados por la configuración de la biblioteca de autenticación Microsoft (MSAL). |
msalConfig |
Configuración de Biblioteca de autenticación de Microsoft (MSAL). |
msalInstance |
La instancia de MSAL PublicClientApplication. |
container |
Elemento donde se muestran los mensajes. |
getToken |
Recuperar un token de acceso usando MSAL. |
logIn |
Función del agente de escucha de eventos para el botón de inicio de sesión. Abre un cuadro de diálogo de elección de cuenta. |
logOut |
Función del agente de escucha de eventos para el botón de cierre de sesión. Abre un cuadro de diálogo de elección de cuenta. |
whoAmI |
Función asincrónica que llama a la función WhoAmI para recuperar datos de Dataverse. |
Detector de eventos whoAmIButton |
La función que llama a la función whoAmI y administra los cambios en la interfaz de usuario para mostrar el mensaje. |
Cree una página de CSS
El archivo Hoja de estilos en cascada (CSS) hace que la página HTML sea más atractiva y controles cuando los controles están deshabilitados o ocultos.
Cree una carpeta nueva llamada
stylesen la carpetasrc.Cree un nuevo archivo llamado
style.cssen la carpetastyles.Copie y pegue este texto en el archivo
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 */ }
Crear archivo .gitignore
Al comprobar la aplicación en mediante el control de código fuente, agregar un .gitignore archivo impide que se protejan los archivos y carpetas especificados.
Crear un archivo llamado
.gitignore.Agregue el contenido siguiente:
.parcel-cache dist node_modules .env
Las carpetas .parcel-cache y dist aparecen cuando ejecuta la aplicación por primera vez.
No hacer check-in del archivo .env es una práctica recomendada de seguridad. Es posible que desee hacer check-in de un archivo .env.sample provisional con valores provisionales.
El proyecto debería tener este aspecto en Visual Studio Code Explorer:
Configurar el archivo package.json
El package.json archivo debe tener un aspecto similar al del ejemplo siguiente:
{
"devDependencies": {
"parcel": "^2.14.1",
},
"dependencies": {
"@azure/msal-browser": "^5.17.3",
"dotenv": "^17.4.2"
}
}
Agregue los scripts elementos y @parcel/resolver-default después de 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 configuración habilita el comportamiento de resolución de exportaciones de paquetes de Parcel. Esta configuración es necesaria para resolver @azure/msal-browsercorrectamente , que usa el campo de exportaciones en sus metadatos de paquete. En función de la versión de Paquete que use, es posible que esta configuración no sea necesaria, pero se ha conservado para garantizar la compatibilidad con la dependencia msal del ejemplo.
Esta configuración le permite iniciar la aplicación mediante npm start en el paso siguiente.
Pruébelo
En Visual Studio Code, abra una ventana de terminal.
Escriba
npm starty pulse Intro.Nota
Es posible que vea alguna salida escrita en el terminal mientras el proyecto se inicializa por primera vez. Esta salida es La instalación de algunos módulos de Node más para evitar problemas al usar dotenv. Examine y
package.jsonverá algunos elementos nuevos agregados a .devDependenciesVerá la salida al terminal que tiene este aspecto:
Server running at http://localhost:1234 Built in 1.08sPresione Ctrl + haga clic en el http://localhost:1234 enlace para abrir su navegador.
En su navegador, seleccione el botón Iniciar sesión.
Se abre el cuadro de diálogo Iniciar sesión en su cuenta.
En el cuadro de diálogo de inicio de sesión en su cuenta, seleccione la cuenta que tiene acceso a Dataverse.
La primera vez que acceda a Dataverse mediante un nuevo valor de identificador de aplicación (cliente), verá este cuadro de diálogo Permisos solicitado :
Seleccione Aceptar en el cuadro de diálogo Permisos solicitados.
Seleccione el botón WhoAmI.
El mensaje ¡Enhorabuena! Se conectó a Dataverse través de la API web. se muestra con su valor
UserIddel tipo complejo WhoAmIResponse.
Troubleshooting
Esta sección contiene errores que puede encontrar al ejecutar este inicio rápido.
Nota
Si tiene problemas para completar los pasos descritos en este inicio rápido, pruebe a clonar o descargar el repositorio PowerApps-Samples . La aplicación completa para estos pasos está disponible en /dataverse/webapi/JS/quickspa. Siga las instrucciones del LÉEME. Si eso no funciona, cree un problema de GitHub que haga referencia a esta quickspa aplicación de ejemplo.
La cuenta de usuario seleccionada no existe en el inquilino
Cuando la cuenta que selecciona no pertenece al mismo inquilino de Microsoft Entra que la aplicación registrada, aparece este error en el cuadro de diálogo Elegir una cuenta :
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.
Resolución: Asegúrese de elegir el usuario correcto.
Pasos siguientes
Pruebe otros ejemplos que usen JavaScript del lado cliente.
Aprender más acerca de las Capacidades de API web de Dataverse mediante la comprensión de los documentos de servicio.