Compartir a través de

Inicio rápido: API web con JavaScript del lado cliente y Visual Studio Code

En este inicio rápido se muestra cómo puede conectarse a Dataverse y usar la API web con las siguientes tecnologías:

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.
Visual Studio Code 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.
Cross-Origin Resource Sharing (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 de SPA con un número mínimo de pasos. Al completar esta guía de inicio rápido, podrá:

  • Iniciar sesión y conectar a Dataverse
  • Invoque la función WhoAmI y muestre su valor UserID.

Ejecución de inicio rápido completada

Al completar este inicio rápido, podrá probar los ejemplos de operaciones de datos de la API web (JavaScript del lado del cliente), que demuestran capacidades 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 component framework - 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 No puede completar este inicio rápido sin poder crear un registro de la aplicación Microsoft Entra para habilitarlo.

Si no está seguro de poder hacerlo, pruebe el primer paso para registrar una aplicación SPA y descúbralo.
Visual Studio Code Si Visual Studio Code no está instalado en su equipo, debe descargar e instalar Visual Studio Code para ejecutar esta guía de 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 Package Manager (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 'bundlers'. El más común es webpack. Este inicio rápido utiliza 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 el 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:

Cuando configure la aplicación, necesitará el identificador de aplicación (cliente) y el de su inquilino de Microsoft Entra. También debe elegir un nombre descriptivo para la aplicación para que las personas sepan para qué se creó la aplicación.

Registrar su aplicación

Puede registrar su aplicación usando ya sea el:

Crear el registro de la aplicación

  1. Inicie sesión en el Centro de administración de Microsoft Entra.

  2. Si tiene acceso a varios inquilinos, use el icono de Configuración en el menú superior para cambiar al inquilino en el que desea registrar la aplicación desde el menú Directorios + suscripciones.

  3. Vaya a Identidad>Aplicaciones>Registros de aplicaciones y seleccione Registro nuevo.

  4. Escriba un Nombre para la aplicación, como Dataverse Web API Quickstart SPA.

  5. En Tipos de cuentas admitidos, en Quién puede usar esta aplicación o acceder a esta API, seleccione Solo cuentas en este directorio organizativo (<Nombre de su inquilino>: inquilino único).

  6. Para URI de redireccionamiento (opcional)

    1. En Seleccionar una plataforma, elija Aplicación de una sola página (SPA).
    2. Especifique el valor como http://localhost:1234.

  7. Seleccione Registrar para guardar los cambios.

  8. En la ventana del registro de la aplicación que creó, en la pestaña Información general, debajo de Esenciales, puede encontrar estos valores:

    • Identificador de aplicación (cliente)
    • Id. de de directorio (inquilino)

  9. Copie estos valores porque los necesita al crear el archivo .env para utilizar variables de entorno.

Agregue un privilegio de Dataverse user_impersonation

  1. En el área Administrar, seleccione Permisos de API.
  2. Seleccione Agregar permiso.
  3. En el área Solicitar permisos de API, seleccione la pestaña API que usa mi organización.
  4. Escriba 'Dataverse' para buscar el identificador de la aplicación (cliente) 00000007-0000-0000-c000-000000000000.
  5. Seleccione la aplicación Dataverse.
  6. En Seleccionar permisos, user_impersonation es el único permiso delegado disponible. Selecciónelo.
  7. Seleccione Agregar permisos.

Nota

Si no tiene los privilegios para crear un registro de aplicación para su empresa, obtenga un inquilino propio a través del plan de desarrollador de Power Apps.

Instalar Node.js

  1. Vaya a Descargar Node.js.

  2. Elija el instalador adecuado para su sistema operativo (Windows, macOS o Linux) y descárguelo.

  3. Ejecute el instalador. Asegúrese de aceptar la opción predeterminada para: Instalar npm, el administrador de paquetes recomendado para Node.js.

  4. Verifique la instalación abriendo un terminal o símbolo del sistema, escribiendo estos comandos y presionando Intro.

    • node -v
    • npm -v

    Debería ver algo como esto:

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

Crea un proyecto

Nota

Puede omitir estos pasos clonando o descargando el repositorio de PowerApps-Ejemplos . La aplicación completa para estos pasos está disponible en /dataverse/webapi/JS/quickspa. Siga las instrucciones del LÉEME.

Las instrucciones de esta sección le guían para instalar dependencias desde npm, crear la estructura de carpetas y abrir Visual Studio Code.

  1. Abra una ventana de terminal en un lugar donde desee crear un proyecto. Para estas instrucciones, usamos C:\projects.

  2. Escriba los siguientes comandos y presione Intro para realizar las siguientes acciones:

    Command Acción
    mkdir quickspa Cree una nueva carpeta llamada quickspa.
    cd quickspa Mueva a la nueva carpeta quickspa.
    npm install --save-dev parcel Instale Parcel e inicialice el proyecto.
    npm install @azure/msal-browser Instale la biblioteca MSAL.js.
    npm install dotenv Instale dotenv para acceder a variables de entorno que almacenan datos de configuración potencialmente confidenciales.
    mkdir src Cree una carpeta src donde 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:

Muestra el proyecto quickspa recién creado antes de que se agreguen los archivos.

Crear el archivo .env

Almacenar los datos de configuración en el entorno separados del código es una práctica recomendada de seguridad.

  1. Cree un nuevo archivo llamado .env en la raíz de su carpeta quickspa.

  2. Pegue los valores de Registrar la aplicación para reemplazar los valores CLIENT_ID y TENANT_ID que aparecen a continuación.

    # 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. Establezca el valor BASE_URL a la URL de la API web URL del entorno al que desea conectarse.

Nota

No confirmará el archivo .env. En Crear archivo .gitignore, lo excluirá. 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.

  1. Cree un nuevo archivo en la carpeta src llamado index.html.

  2. 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 haya iniciado sesión para usarlos. Deshabilitado de forma predeterminada.
whoAmIButton botón Ejecuta la función WhoAmI para mostrar el identificador del usuario.
container main Área donde se puede mostrar información al usuario.
script Carga el archivo index.js después de que se carguen los demás elementos de la página.

Crear un script de JavaScript

Este archivo contiene toda la lógica que hace que la página index.html sea dinámica.

  1. Cree una carpeta nueva en la carpeta src llamada scripts.

  2. Cree un archivo nuevo en la carpeta scripts llamado index.js.

  3. Copie y pegue este contenido en la página 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);
  }
};

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 Microsoft Authentication Library (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 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 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 de hoja de estilo en cascada (CSS) hace que la página HTML sea más atractiva y tiene un papel en el control de cuándo los controles están deshabilitados u ocultos.

  1. Cree una carpeta nueva llamada styles en la carpeta src.

  2. Cree un nuevo archivo llamado style.css en la carpeta styles.

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

Cuando la aplicación se registra con el control de código fuente, al agregar un archivo .gitignore se impide hacer check-in de los archivos y carpetas que se especifican.

  1. Crear un archivo llamado .gitignore.

  2. 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:

Muestra el proyecto quickspa después de agregar los archivos.

Configurar el archivo package.json

Su archivo package.json deberá ser ahora similar a esto:

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

Agregue este elemento scripts debajo de dependencies:

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

Esta configuración le permite iniciar la aplicación utilizando npm start en el siguiente paso.

Pruébelo

  1. Abra una ventana de terminal en Visual Studio Code

  2. Escriba npm start y pulse Intro.

    Nota

    Es posible que vea alguna salida escrita en el terminal mientras el proyecto se inicializa por primera vez. Esto es parcel instalando algunos módulos de nodo adicionales para mitigar problemas al usar dotenv. Mire el package.json y debería ver algunos elementos nuevos agregados a la devDependencies.

    Debería esperar una salida al terminal que se ve así:

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

  3. Presione Ctrl + haga clic en el http://localhost:1234 enlace para abrir su navegador.

  4. En su navegador, seleccione el botón Iniciar sesión.

    Se abre el cuadro de diálogo Iniciar sesión en su cuenta.

  5. 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 con un nuevo valor de ID de aplicación (cliente), verá este cuadro de diálogo Permisos solicitados:

    Cuadro de diálogo Permisos solicitados

  6. Seleccione Aceptar en el cuadro de diálogo Permisos solicitados.

  7. Seleccione el botón WhoAmI.

    El mensaje ¡Enhorabuena! Se conectó a Dataverse través de la API web. se muestra con su valor UserId del tipo complejo WhoAmIResponse.

Solución de problemas

Esta sección contiene errores que puede encontrar al ejecutar este inicio rápido.

Nota

Si tiene problemas para completar los pasos de este inicio rápido, intente clonar o descargar el repositorio PowerApps-Ejemplos . 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 aplicación de ejemplo quickspa.

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.

Ejemplo de operaciones de datos de la API web (JavaScript del lado del cliente)

Aprender más acerca de las Capacidades de API web de Dataverse mediante la comprensión de los documentos de servicio.

Tipos y operaciones de API web