Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Este início rápido mostra como autenticar e conectar um SPA (aplicativo de página única) JavaScript à API Web do Dataverse em Visual Studio Code usando as tecnologias a seguir. Você cria um aplicativo que entra em um usuário, chama a função WhoAmI e exibe a ID do usuário.
| Tecnologia | Descrição |
|---|---|
| JavaScript | Uma linguagem de programação para desenvolvimento na Web, habilitando conteúdo interativo. Ele é executado em navegadores para scripts do lado do cliente e pode ser usado no lado do servidor com Node.js. |
| Código do Visual Studio | Um editor de código leve e de software livre com depuração, realce de sintaxe e suporte a plug-in. |
| SPAs (aplicativos de página única) | Aplicativos Web que carregam uma única página HTML e atualizam dinamicamente o conteúdo à medida que o usuário interage com o aplicativo. Essa abordagem fornece uma experiência de usuário mais suave e rápida, reduzindo os recarregamentos de páginas e melhorando o desempenho. |
| Biblioteca de Autenticação da Microsoft para JavaScript (MSAL.js) | Uma biblioteca que permite autenticação e autorização para aplicativos Web usando Microsoft plataformas de identidade. Ele simplifica a integração de entrada segura e aquisição de token para acessar recursos protegidos. |
| CORS (Compartilhamento de Recursos entre Origens) | Um aplicativo SPA pode usar o JavaScript do lado do cliente com a API Web do Dataverse porque o CORS está habilitado. CORS é um recurso de segurança em navegadores da Web que permite acesso controlado a recursos em um servidor Web de uma origem diferente. Ele permite que os aplicativos Web ignorem a política de mesma origem, facilitando o compartilhamento de dados seguro e seguro em diferentes domínios. |
Objetivo
Este guia de início rápido concentra-se na conexão à API Web do Dataverse com JavaScript usando um aplicativo cliente SPA com um número mínimo de etapas. Ao concluir este início rápido, você poderá:
- Entre e conecte-se ao Dataverse.
- Invoque a função WhoAmI e exiba seu
UserIDvalor.
Ao concluir este início rápido, você pode experimentar os Exemplos de Operações de Dados da API Web (JavaScript do lado do cliente) que demonstram recursos mais avançados.
Note
Este início rápido não se aplica aos seguintes cenários javaScript do lado do cliente:
| Scenario | Saiba mais |
|---|---|
| Scripts de aplicativo controlados por modelo |
-
Aplicar lógica de negócios usando scripts de cliente em aplicativos controlados por modelo usando JavaScript - Xrm.WebApi (referência da API do cliente) |
| Estrutura de componentes do Power Apps |
-
WebAPI de componentes de código - Implementando o componente da API Web |
| Portais de Power Pages | API Web dos portais de Power Pages |
Nesses cenários, o respectivo tipo de aplicativo fornece uma funcionalidade para você enviar solicitações em vez de usar a API de Busca nativa do JavaScript diretamente, conforme mostrado neste início rápido. Scripts do lado do cliente em aplicativos controlados por modelo são executados no contexto de um aplicativo autenticado, portanto, cada solicitação não requer um token de acesso.
Pré-requisitos
A tabela a seguir descreve os pré-requisitos necessários para concluir este início rápido e exemplos de operações de dados da API Web (JavaScript do lado do cliente).
| Pré-requisito | Descrição |
|---|---|
| Privilégios para criar um registro do Aplicativo Entra | Você precisa da capacidade de criar um registro de aplicativo Microsoft Entra para concluir este início rápido. Se você não tiver certeza se tem essa capacidade, tente a primeira etapa para registrar um aplicativo SPA e descubra. |
| Código do Visual Studio | Se Visual Studio Code não estiver instalado em seu computador, baixe e instale Visual Studio Code para executar este início rápido. |
| Node.js | Node.js é um ambiente de runtime que permite executar o JavaScript no lado do servidor. Este início rápido cria um aplicativo SPA que executa o JavaScript no lado do cliente em um navegador, em vez do runtime Node.js. Mas o Node Gerenciador de Pacotes (npm) é instalado com Node.jse você precisa do npm para instalar o Parcel e a biblioteca de MSAL.js. |
| Pacote | Os aplicativos Web modernos normalmente têm muitas dependências em bibliotecas código aberto distribuídas usando npm e scripts que precisam ser gerenciados e otimizados durante o processo de build. Essas ferramentas são chamadas de empacotadores. O mais comum é o webpack.
O VITE também é popular. Este início rápido usa o Parcel porque oferece uma experiência simplificada. Para obter inícios rápidos e exemplos que mostram aplicativos SPA usando estruturas e empacotadores diferentes, consulte Microsoft Entra exemplos de aplicativos de página única. Você pode adaptar esses exemplos para usar a API Web do Dataverse com as informações mostradas neste início rápido. |
| Tecnologias web | O conhecimento de HTML, JavaScript e CSS é necessário para entender como esse início rápido funciona. Entender como fazer solicitações de rede com JavaScript é essencial. |
Registrar um aplicativo SPA
Esta etapa é a primeira porque, se você não conseguir registrar um aplicativo, não poderá concluir este início rápido.
Qualquer uma das seguintes funções de Microsoft Entra com privilégios inclui as permissões necessárias:
Ao configurar o aplicativo, você precisará de uma ID do aplicativo (cliente) e da ID do locatário do Microsoft Entra. Escolha um nome descritivo para o aplicativo para que as pessoas saibam para que o aplicativo foi criado.
Registrar seu aplicativo
Você pode registrar seu aplicativo usando uma das seguintes opções:
- Microsoft Entra interface do usuário do aplicativo Web
- Azure PowerShell cmdlet New-AzADApplication
Use o centro de administração do Microsoft Entra para criar um registro de aplicativo SPA de locatário único, configurar seu URI de redirecionamento, copiar o aplicativo e as IDs de locatário e adicionar a permissão dataverseuser_impersonation.
Criar o registro do aplicativo
Faça login no centro de administração do Microsoft Entra.
Se você tiver acesso a vários locatários, use o ícone Configurações
no menu superior para alternar para o locatário em que deseja registrar o aplicativo no menu Diretórios + assinaturas .Navegue até registros de aplicativo e selecione Novo registro.
Insira um Nome para o aplicativo, como
Dataverse Web API Quickstart SPA.Para tipos de conta com suporte, em Escolher os tipos de conta que podem usar esse aplicativo ou acessar essa API, selecione somente locatário único – <seu nome> de locatário.
Para URI de Redirecionamento (opcional)
- Para Selecionar uma plataforma, escolha SPA (aplicativo de página única).
- Insira
http://localhost:1234/redirect.htmlcomo o valor.
Selecione Registrar para salvar suas alterações.
Na janela do registro de aplicativo que você criou, na guia Visão geral , em Essentials, você pode encontrar estes valores:
- ID do aplicativo (cliente)
- ID do Diretório (locatário)
Copie esses valores porque você precisa deles ao criar o arquivo .env para usar variáveis de ambiente.
Adicionar privilégio do Dataverse user_impersonation
- Na área Gerenciar , selecione permissões de API.
- Selecione Adicionar uma permissão.
- No submenu Solicitar permissões de API , selecione as APIs que minha organização usa a guia.
- Digite 'Dataverse' para localizar a ID
00000007-0000-0000-c000-000000000000do aplicativo (cliente). - Selecione o aplicativo Dataverse.
- Em Selecionar permissões, selecione
user_impersonation. - Selecione Adicionar permissões.
Note
Se você não tiver os privilégios para criar um registro de aplicativo para sua empresa, obtenha um locatário próprio por meio do plano de desenvolvedor do Power Apps.
Instalar o Node.js
Vá para Baixar Node.js.
Escolha o instalador apropriado para o sistema operacional (Windows, macOS ou Linux) e baixe-o.
Rode o instalador. Aceite a opção padrão para: Instalar o npm, o gerenciador de pacotes recomendado para Node.js.
Verifique a instalação abrindo um terminal ou prompt de comando, digitando esses comandos e pressionando Enter.
node -vnpm -v
Você verá uma saída semelhante a esta:
PS C:\Users\you> node -v v24.19.0 PS C:\Users\you> npm -v 11.17.0 PS C:\Users\you>
Criar um projeto
Note
Para ignorar essas etapas, clone ou baixe o repositório PowerApps-Samples . O aplicativo concluído para essas etapas está disponível em /dataverse/webapi/JS/quickspa. Siga as instruções no README.
Esta seção orienta você pela instalação de dependências do npm, criação da estrutura de pastas e abertura de Visual Studio Code.
Abra uma janela de terminal para um local onde você deseja criar um projeto. Para estas instruções, use
C:\projects.Digite os seguintes comandos e pressione Enter para executar cada comando:
Command Ação mkdir quickspaCrie uma pasta chamada quickspa.cd quickspaMova para a nova quickspapasta.npm install --save-dev parcelInstale o Parcel e inicialize o projeto. npm install @azure/msal-browserInstale a biblioteca de MSAL.js. npm install dotenvInstale o dotenv para acessar variáveis de ambiente que armazenam dados de configuração potencialmente confidenciais. mkdir srcCrie uma srcpasta em que você adicione arquivos HTML, JS e CSS para seu aplicativo nas etapas a seguir.code .Abra Visual Studio Code no contexto da quickspapasta.
Seu projeto deve ter esta aparência no Visual Studio Code Explorer:
Note
Visual Studio Code pode exibir um prompt: o Modo Restrito destina-se à navegação segura de código. Confie nessa pasta para habilitar todos os recursos. Selecione Gerenciar e escolha confiar na pasta. Saiba mais sobre a Confiança do Workspace
Criar o arquivo .env
Armazenar dados de configuração no ambiente separado do código é uma prática recomendada de segurança.
Crie um novo arquivo nomeado
.envna raiz da pastaquickspa.Cole os valores de Registrar seu aplicativo para substituir os valores e
TENANT_IDosCLIENT_IDvalores no seguinte código:# 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.htmlDefina o
BASE_URLvalor como a URL da URL da API Web para o ambiente ao qual você deseja se conectar.
Note
Não faça check-in no .env arquivo. Em Criar .gitignore arquivo, exclua-o. Mas talvez você queira criar um .env.example arquivo usando os valores de espaço reservado para que as pessoas saibam quais dados ele deve conter.
Criar uma página HTML
As instruções nesta seção descrevem como criar o arquivo HTML que fornece a interface do usuário para o aplicativo SPA.
Crie um novo arquivo na
srcpasta chamadaindex.html.Copie e cole este conteúdo na
index.htmlpágina:<!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>
Este HTML fornece os seguintes elementos:
| ID do elemento | Tipo de elemento | Descrição |
|---|---|---|
loginButton |
botão | Para abrir a caixa de diálogo de entrada. |
logoutButton |
botão | Para abrir a caixa de diálogo de saída. Oculto por padrão. |
buttonContainer |
navegação | Contém botões que exigem que o usuário entre para usar. Desabilitado por padrão. |
whoAmIButton |
botão | Executa a função WhoAmI para exibir a ID do usuário. |
container |
principal | Área em que você pode exibir informações para o usuário. |
| roteiro | Carrega o index.js arquivo após o restante dos elementos da página ser carregado. |
Criar página HTML de redirecionamento
O MSAL Browser v5 introduziu suporte para aplicativos que são atendidos com cabeçalhos COOP (entre origens)Opener-Policy e essa alteração requer uma página de ponte de redirecionamento para passar a resposta de autenticação com segurança de volta para a janela principal do SPA. Saiba como configurar a página de ponte de redirecionamento no MSAL Browser
Crie um novo arquivo na
srcpasta chamadaredirect.html.Copie e cole este conteúdo na
redirect.htmlpágina:<!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>
Criar um script JavaScript
Esse arquivo contém toda a lógica que torna a index.html página dinâmica.
Crie uma nova pasta na
srcpasta chamadascripts.Crie um novo arquivo na
scriptspasta chamadaindex.js.Copie e cole esse conteúdo no
index.jsarquivo: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); } };
O index.js script contém as seguintes constantes e funções:
| Item | Descrição |
|---|---|
config |
Contém os dados usados pela configuração de Biblioteca do Microsoft Authenticator (MSAL). |
msalConfig |
configuração de Biblioteca do Microsoft Authenticator (MSAL). |
msalInstance |
A instância de PublicClientApplication da MSAL. |
container |
O elemento em que as mensagens são exibidas. |
getToken |
Recupera um token de acesso usando MSAL. |
logIn |
Função ouvinte de eventos para o botão de entrada. Abre uma caixa de diálogo Escolher conta. |
logOut |
Função de ouvinte de eventos para o botão de saída. Abre uma caixa de diálogo Escolher conta. |
whoAmI |
Função assíncrona que chama a função WhoAmI para recuperar dados do Dataverse. |
whoAmIButton ouvinte de eventos |
A função que chama a whoAmI função e gerencia as alterações da interface do usuário para mostrar a mensagem. |
Criar uma página do CSS
O arquivo CSS (Folha de Estilos em Cascata) torna a página HTML mais atraente e controla quando os controles são desabilitados ou ocultos.
Crie uma nova pasta nomeada
stylesnasrcpasta.Crie um novo arquivo chamado
style.cssna pastastyles.Copie e cole este texto no
style.cssarquivo:.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 */ }
Criar arquivo .gitignore
Quando você verifica seu aplicativo usando o controle do código-fonte, adicionar um .gitignore arquivo impede que você faça check-in em arquivos e pastas especificados.
Crie um arquivo chamado
.gitignore.Adicione o seguinte conteúdo:
.parcel-cache dist node_modules .env
O e dist as .parcel-cache pastas aparecem quando você executa o aplicativo pela primeira vez.
Não fazer check-in no .env arquivo é uma prática recomendada de segurança. Talvez você queira verificar um arquivo de espaço reservado .env.sample com valores de espaço reservado.
Seu projeto deve ter esta aparência no Visual Studio Code Explorer:
Configurar seu arquivo de package.json
Seu package.json arquivo deve ser semelhante ao exemplo a seguir:
{
"devDependencies": {
"parcel": "^2.14.1",
},
"dependencies": {
"@azure/msal-browser": "^5.17.3",
"dotenv": "^17.4.2"
}
}
Adicione o scripts item e @parcel/resolver-default depois 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
}
A @parcel/resolver-default configuração habilita o comportamento de resolução de exportações de pacote do Parcel. Essa configuração é necessária para resolver @azure/msal-browsercorretamente, que usa o campo exportações em seus metadados de pacote. Dependendo da versão de Pacote usada, essa configuração pode não ser necessária, mas foi mantida para garantir a compatibilidade com a dependência MSAL do exemplo.
Essa configuração permite que você inicie o aplicativo usando npm start na próxima etapa.
Experimente
Em Visual Studio Code, abra uma janela do terminal.
Digite
npm starte pressione Enter.Note
Você pode ver alguma saída gravada no terminal enquanto o projeto é inicializado pela primeira vez. Essa saída é o Parcel instalando mais alguns módulos do Nó para evitar problemas ao usar o dotenv. Olhe para o
package.jsone você vê alguns novos itens adicionados aodevDependencies.Você verá a saída para o terminal com esta aparência:
Server running at http://localhost:1234 Built in 1.08sPressione Ctrl + clique no http://localhost:1234 link para abrir o navegador.
No navegador, selecione o botão Logon .
A caixa de diálogo Entrar na sua conta é aberta.
Na caixa de diálogo Entrar na sua conta , selecione a conta que tem acesso ao Dataverse.
Na primeira vez que acessar o Dataverse usando um novo valor de ID do aplicativo (cliente), você verá esta caixa de diálogo Permissões solicitadas :
Selecione Aceitar na caixa de diálogo Permissões solicitadas .
Selecione o botão WhoAmI .
A mensagem Parabéns! Você se conectou ao Dataverse usando a API Web. é exibido com seu
UserIdvalor do tipo complexo WhoAmIResponse.
Troubleshooting
Esta seção contém erros que você pode encontrar ao executar este início rápido.
Note
Se você tiver problemas para concluir as etapas neste início rápido, tente clonar ou baixar o repositório PowerApps-Samples . O aplicativo concluído para essas etapas está disponível em /dataverse/webapi/JS/quickspa. Siga as instruções no README. Se isso não funcionar, crie um problema GitHub referenciando este quickspa aplicativo de exemplo.
A conta de usuário selecionada não existe no locatário
Quando a conta selecionada não pertence ao mesmo locatário Microsoft Entra que o aplicativo registrado, você recebe esse erro na caixa de diálogo Escolher uma conta:
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.
Resolução: certifique-se de escolher o usuário correto.
Próximas Etapas
Experimente outros exemplos que usam JavaScript do lado do cliente.
Saiba mais sobre os recursos da API Web do Dataverse compreendendo os documentos de serviço.