Criar aplicativos JavaScript com o Microsoft Graph
Este tutorial ensina como criar um aplicativo de console JavaScript que usa o microsoft API do Graph para acessar dados em nome de um usuário.
Observação
Para saber como usar o Microsoft Graph para acessar dados usando autenticação somente aplicativo, confira este tutorial de autenticação somente aplicativo.
Neste tutorial, você vai:
Dica
Como alternativa a seguir este tutorial, você pode baixar o código concluído por meio da ferramenta de início rápido , que automatiza o registro e a configuração do aplicativo. O código baixado funciona sem nenhuma modificação necessária.
Você também pode baixar ou clonar o repositório GitHub e seguir as instruções no README para registrar um aplicativo e configurar o projeto.
Pré-requisitos
Antes de iniciar este tutorial, você deve ter Node.js instalado em seu computador de desenvolvimento.
Você também deve ter uma conta de trabalho ou de estudante da Microsoft com uma caixa de correio Exchange Online. Se você não tiver um locatário do Microsoft 365, poderá se qualificar para um por meio do Programa de Desenvolvedores do Microsoft 365; para obter detalhes, confira as perguntas frequentes. Como alternativa, você pode se inscrever para uma avaliação gratuita de 1 mês ou comprar um plano do Microsoft 365.
Observação
Este tutorial foi escrito com Node.js versão 16.14.2. As etapas neste guia podem funcionar com outras versões, mas isso não foi testado.
Registrar o aplicativo no portal
Neste exercício, você registrará um novo aplicativo no Azure Active Directory para habilitar a autenticação do usuário. Você pode registrar um aplicativo usando o centro de administração do Azure Active Directory ou usando o SDK do Microsoft Graph PowerShell.
Registrar aplicativo para autenticação de usuário
Nesta seção, você registrará um aplicativo que dá suporte à autenticação do usuário usando o fluxo de código do dispositivo.
Abra um navegador e navegue até o centro de administração do Azure Active Directory e faça logon usando uma conta de trabalho ou de estudante.
Selecione Azure Active Directory na navegação esquerda e selecione Registros de aplicativos em Gerenciar.
Selecione Novo registro. Insira um nome para seu aplicativo, por exemplo,
Graph User Auth Tutorial
.Defina tipos de conta com suporte conforme desejado. As opções são:
Opção Quem pode entrar? Contas apenas neste diretório organizacional Somente usuários em sua organização do Microsoft 365 Contas em qualquer diretório organizacional Usuários em qualquer organização do Microsoft 365 (contas corporativas ou escolares) Contas em qualquer diretório organizacional... e contas pessoais da Microsoft Usuários em qualquer organização do Microsoft 365 (contas corporativas ou escolares) e contas pessoais da Microsoft Deixe o URI de Redirecionamento vazio.
Selecione Registrar. Na página Visão geral do aplicativo, copie o valor da ID do aplicativo (cliente) e salve-o, você precisará dele na próxima etapa. Se você escolheu Contas neste diretório organizacional apenas para tipos de conta com suporte, copie também a ID do Diretório (locatário) e salve-a.
Selecione Autenticação em Gerenciar. Localize a seção Configurações avançadas e altere a alternância Permitir fluxos de cliente público para Sim e escolha Salvar.
Observação
Observe que você não configurou nenhuma permissão do Microsoft Graph no registro do aplicativo. Isso ocorre porque o exemplo usa o consentimento dinâmico para solicitar permissões específicas para autenticação do usuário.
Criar um aplicativo de console JavaScript
Comece criando um novo projeto de Node.js. Abra sua CLI (interface de linha de comando) em um diretório em que você deseja criar o projeto. Execute o seguinte comando:
npm init
Responda aos prompts fornecendo seus próprios valores ou aceitando os padrões.
Instalar dependências
Antes de seguir em frente, adicione algumas dependências adicionais que você usará posteriormente.
- Biblioteca de clientes do Azure Identity para JavaScript para autenticar o usuário e adquirir tokens de acesso.
- Biblioteca de clientes JavaScript do Microsoft Graph para fazer chamadas para o Microsoft Graph.
- busca isomórfica para adicionar
fetch
API a Node.js. Essa é uma dependência para a biblioteca de clientes JavaScript do Microsoft Graph. - readline-sync para solicitar entrada ao usuário.
Execute os comandos a seguir na CLI para instalar as dependências.
npm install @azure/identity @microsoft/microsoft-graph-client isomorphic-fetch readline-sync
Carregar configurações do aplicativo
Nesta seção, você adicionará os detalhes do registro do aplicativo ao projeto.
Crie um arquivo na raiz do projeto chamado appSettings.js e adicione o código a seguir.
const settings = { 'clientId': 'YOUR_CLIENT_ID_HERE', 'tenantId': 'common', 'graphUserScopes': [ 'user.read', 'mail.read', 'mail.send' ] }; module.exports = settings;
Atualize os valores de
settings
acordo com a tabela a seguir.Configuração Valor clientId
A ID do cliente do registro do aplicativo tenantId
Se você escolheu a opção para permitir apenas que usuários em sua organização entrem, altere esse valor para sua ID de locatário. Caso contrário, deixe como common
.
Design do aplicativo
Nesta seção, você criará um menu simples baseado em console.
Crie um arquivo na raiz do projeto chamado graphHelper.js e adicione o código de espaço reservado a seguir. Você adicionará mais código a este arquivo em etapas posteriores.
module.exports = {};
Crie um arquivo na raiz do projeto chamado index.js e adicione o código a seguir.
const readline = require('readline-sync'); const settings = require('./appSettings'); const graphHelper = require('./graphHelper'); async function main() { console.log('JavaScript Graph Tutorial'); let choice = 0; // Initialize Graph initializeGraph(settings); // Greet the user by name await greetUserAsync(); const choices = [ 'Display access token', 'List my inbox', 'Send mail', 'Make a Graph call' ]; while (choice != -1) { choice = readline.keyInSelect(choices, 'Select an option', { cancel: 'Exit' }); switch (choice) { case -1: // Exit console.log('Goodbye...'); break; case 0: // Display access token await displayAccessTokenAsync(); break; case 1: // List emails from user's inbox await listInboxAsync(); break; case 2: // Send an email message await sendMailAsync(); break; case 3: // Run any Graph code await makeGraphCallAsync(); break; default: console.log('Invalid choice! Please try again.'); } } } main();
Adicione os seguintes métodos de espaço reservado no final do arquivo. Você os implementará em etapas posteriores.
function initializeGraph(settings) { // TODO } async function greetUserAsync() { // TODO } async function displayAccessTokenAsync() { // TODO } async function listInboxAsync() { // TODO } async function sendMailAsync() { // TODO } async function makeGraphCallAsync() { // TODO }
Isso implementa um menu básico e lê a escolha do usuário na linha de comando.
Adicionar autenticação de usuário
Nesta seção, você estenderá o aplicativo do exercício anterior para dar suporte à autenticação com Azure AD. Isso é necessário para obter o token de acesso OAuth necessário para chamar o Microsoft Graph. Nesta etapa, você integrará a biblioteca de clientes da Identidade do Azure para JavaScript no aplicativo e configurará a autenticação para a biblioteca de clientes JavaScript do Microsoft Graph.
A biblioteca de Identidade do Azure fornece várias classes que implementam fluxos de TokenCredential
token OAuth2. A biblioteca de clientes do Microsoft Graph usa essas classes para autenticar chamadas para o Microsoft Graph.
Configurar o cliente graph para autenticação de usuário
Nesta seção, você usará a DeviceCodeCredential
classe para solicitar um token de acesso usando o fluxo de código do dispositivo.
Abra graphHelper.js e substitua seu conteúdo pelo seguinte.
require('isomorphic-fetch'); const azure = require('@azure/identity'); const graph = require('@microsoft/microsoft-graph-client'); const authProviders = require('@microsoft/microsoft-graph-client/authProviders/azureTokenCredentials'); let _settings = undefined; let _deviceCodeCredential = undefined; let _userClient = undefined; function initializeGraphForUserAuth(settings, deviceCodePrompt) { // Ensure settings isn't null if (!settings) { throw new Error('Settings cannot be undefined'); } _settings = settings; _deviceCodeCredential = new azure.DeviceCodeCredential({ clientId: settings.clientId, tenantId: settings.tenantId, userPromptCallback: deviceCodePrompt }); const authProvider = new authProviders.TokenCredentialAuthenticationProvider( _deviceCodeCredential, { scopes: settings.graphUserScopes }); _userClient = graph.Client.initWithMiddleware({ authProvider: authProvider }); } module.exports.initializeGraphForUserAuth = initializeGraphForUserAuth;
Substitua a função vazia
initializeGraph
no index.js pelo seguinte.function initializeGraph(settings) { graphHelper.initializeGraphForUserAuth(settings, (info) => { // Display the device code message to // the user. This tells them // where to go to sign in and provides the // code to use. console.log(info.message); }); }
Esse código declara duas propriedades privadas, um DeviceCodeCredential
objeto e um Client
objeto. A initializeGraphForUserAuth
função cria uma nova instância de DeviceCodeCredential
, em seguida, usa essa instância para criar uma nova instância de Client
. Sempre que uma chamada de API for feita ao Microsoft Graph por meio do _userClient
, ela usará a credencial fornecida para obter um token de acesso.
Testar o DeviceCodeCredential
Em seguida, adicione código para obter um token de acesso do DeviceCodeCredential
.
Adicione a função a seguir ao graphHelper.js.
async function getUserTokenAsync() { // Ensure credential isn't undefined if (!_deviceCodeCredential) { throw new Error('Graph has not been initialized for user auth'); } // Ensure scopes isn't undefined if (!_settings?.graphUserScopes) { throw new Error('Setting "scopes" cannot be undefined'); } // Request token with given scopes const response = await _deviceCodeCredential.getToken(_settings?.graphUserScopes); return response.token; } module.exports.getUserTokenAsync = getUserTokenAsync;
Substitua a função vazia
displayAccessTokenAsync
no index.js pelo seguinte.async function displayAccessTokenAsync() { try { const userToken = await graphHelper.getUserTokenAsync(); console.log(`User token: ${userToken}`); } catch (err) { console.log(`Error getting user access token: ${err}`); } }
Execute o comando a seguir na CLI na raiz do projeto.
node index.js
Insira
1
quando solicitado para uma opção. O aplicativo exibe uma URL e um código de dispositivo.JavaScript Graph Tutorial [1] Display access token [2] List my inbox [3] Send mail [4] Make a Graph call [0] Exit Select an option [1...4 / 0]: 1 To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code RK987NX32 to authenticate.
Abra um navegador e navegue até a URL exibida. Insira o código fornecido e entre.
Importante
Fique atento a todas as contas existentes do Microsoft 365 que são registradas no navegador ao navegar para
https://microsoft.com/devicelogin
. Use recursos do navegador, como perfis, modo convidado ou modo privado para garantir que você se autentique como a conta que pretende usar para teste.Depois de concluído, retorne ao aplicativo para ver o token de acesso.
Dica
Somente para fins de validação e depuração, você pode decodificar tokens de acesso do usuário (somente para contas corporativas ou escolares) usando o analisador de token online da Microsoft em https://jwt.ms. Isso pode ser útil se você encontrar erros de token ao chamar o Microsoft Graph. Por exemplo, verificar se a
scp
declaração no token contém os escopos de permissão esperados do Microsoft Graph.
Obter usuário
Nesta seção, você incorporará o Microsoft Graph ao aplicativo. Você usará a biblioteca de clientes JavaScript do Microsoft Graph para fazer chamadas para o Microsoft Graph.
Abra graphHelper.js e adicione a função a seguir.
async function getUserAsync() { // Ensure client isn't undefined if (!_userClient) { throw new Error('Graph has not been initialized for user auth'); } return _userClient.api('/me') // Only request specific properties .select(['displayName', 'mail', 'userPrincipalName']) .get(); } module.exports.getUserAsync = getUserAsync;
Substitua a função vazia
greetUserAsync
no index.js pelo seguinte.async function greetUserAsync() { try { const user = await graphHelper.getUserAsync(); console.log(`Hello, ${user?.displayName}!`); // For Work/school accounts, email is in mail property // Personal accounts, email is in userPrincipalName console.log(`Email: ${user?.mail ?? user?.userPrincipalName ?? ''}`); } catch (err) { console.log(`Error getting user: ${err}`); } }
Se você executar o aplicativo agora, depois de fazer logon no aplicativo, receberá você pelo nome.
Hello, Megan Bowen!
Email: MeganB@contoso.com
Código explicado
Considere o código na getUserAsync
função. São apenas algumas linhas, mas há alguns detalhes importantes a serem notados.
Acessando 'me'
A função passa /me
para o _userClient.api
construtor de solicitações, que cria uma solicitação para a API obter usuário . Essa API está acessível de duas maneiras:
GET /me
GET /users/{user-id}
Nesse caso, o código chamará o ponto de extremidade da GET /me
API. Este é um método de atalho para obter o usuário autenticado sem saber a ID do usuário.
Observação
Como o ponto de extremidade da GET /me
API obtém o usuário autenticado, ele só está disponível para aplicativos que usam a autenticação do usuário. Aplicativos de autenticação somente aplicativo não podem acessar esse ponto de extremidade.
Solicitando propriedades específicas
A função usa o select
método na solicitação para especificar o conjunto de propriedades de que precisa. Isso adiciona o parâmetro de consulta $select à chamada de API.
Tipo de retorno fortemente tipado
A função retorna um User
objeto desserializado da resposta JSON da API. Como o código usa select
, apenas as propriedades solicitadas terão valores no objeto retornado User
. Todas as outras propriedades terão valores padrão.
Caixa de entrada listar
Nesta seção, você adicionará a capacidade de listar mensagens na caixa de entrada de email do usuário.
Abra graphHelper.js e adicione a função a seguir.
async function getInboxAsync() { // Ensure client isn't undefined if (!_userClient) { throw new Error('Graph has not been initialized for user auth'); } return _userClient.api('/me/mailFolders/inbox/messages') .select(['from', 'isRead', 'receivedDateTime', 'subject']) .top(25) .orderby('receivedDateTime DESC') .get(); } module.exports.getInboxAsync = getInboxAsync;
Substitua a função vazia
ListInboxAsync
no index.js pelo seguinte.async function listInboxAsync() { try { const messagePage = await graphHelper.getInboxAsync(); const messages = messagePage.value; // Output each message's details for (const message of messages) { console.log(`Message: ${message.subject ?? 'NO SUBJECT'}`); console.log(` From: ${message.from?.emailAddress?.name ?? 'UNKNOWN'}`); console.log(` Status: ${message.isRead ? 'Read' : 'Unread'}`); console.log(` Received: ${message.receivedDateTime}`); } // If @odata.nextLink is not undefined, there are more messages // available on the server const moreAvailable = messagePage['@odata.nextLink'] != undefined; console.log(`\nMore messages available? ${moreAvailable}`); } catch (err) { console.log(`Error getting user's inbox: ${err}`); } }
Execute o aplicativo, entre e escolha a opção 2 para listar sua caixa de entrada.
[1] Display access token [2] List my inbox [3] Send mail [4] Make a Graph call [0] Exit Select an option [1...4 / 0]: 2 Message: Updates from Ask HR and other communities From: Contoso Demo on Yammer Status: Read Received: 12/30/2021 4:54:54 AM -05:00 Message: Employee Initiative Thoughts From: Patti Fernandez Status: Read Received: 12/28/2021 5:01:10 PM -05:00 Message: Voice Mail (11 seconds) From: Alex Wilber Status: Unread Received: 12/28/2021 5:00:46 PM -05:00 Message: Our Spring Blog Update From: Alex Wilber Status: Unread Received: 12/28/2021 4:49:46 PM -05:00 Message: Atlanta Flight Reservation From: Alex Wilber Status: Unread Received: 12/28/2021 4:35:42 PM -05:00 Message: Atlanta Trip Itinerary - down time From: Alex Wilber Status: Unread Received: 12/28/2021 4:22:04 PM -05:00 ... More messages available? true
Código explicado
Considere o código na getInboxAsync
função.
Acessando pastas de email bem conhecidas
A função passa /me/mailFolders/inbox/messages
para o _userClient.api
construtor de solicitações, que cria uma solicitação para a API de mensagens de lista . Como inclui a /mailFolders/inbox
parte do ponto de extremidade da API, a API só retornará mensagens na pasta de email solicitada. Nesse caso, como a caixa de entrada é uma pasta padrão e conhecida dentro da caixa de correio de um usuário, ela é acessível por meio de seu nome conhecido. As pastas não padrão são acessadas da mesma maneira, substituindo o nome conhecido pela propriedade ID da pasta de email. Para obter detalhes sobre os nomes de pastas conhecidos disponíveis, consulte o tipo de recurso mailFolder.
Acessando uma coleção
Ao contrário da getUserAsync
função da seção anterior, que retorna um único objeto, esse método retorna uma coleção de mensagens. A maioria das APIs no Microsoft Graph que retornam uma coleção não retorna todos os resultados disponíveis em uma única resposta. Em vez disso, eles usam paginação para retornar uma parte dos resultados, fornecendo um método para os clientes solicitarem a próxima "página".
Tamanhos de página padrão
APIs que usam paginação implementam um tamanho de página padrão. Para mensagens, o valor padrão é 10. Os clientes podem solicitar mais (ou menos) usando o parâmetro de consulta $top . Em getInboxAsync
, isso é realizado com o .top(25)
método.
Observação
O valor passado para .top()
é um limite superior, não um número explícito. A API retorna várias mensagens até o valor especificado.
Obtendo páginas subsequentes
Se houver mais resultados disponíveis no servidor, as respostas de coleção incluirão uma @odata.nextLink
propriedade com uma URL de API para acessar a próxima página. A biblioteca de clientes JavaScript expõe essa propriedade em PageCollection
objetos. Se essa propriedade não estiver indefinida, haverá mais resultados disponíveis.
O valor de @odata.nextLink
pode ser passado para _userClient.api
obter a próxima página de resultados. Como alternativa, você pode usar o PageIterator
objeto da biblioteca de clientes para iterar em todas as páginas disponíveis.
Classificando coleções
A função usa o orderby
método na solicitação para solicitar resultados classificados no momento em que a mensagem é recebida (receivedDateTime
propriedade). Ele inclui o palavra-chave para que as DESC
mensagens recebidas mais recentemente sejam listadas primeiro. Isso adiciona o parâmetro de consulta $orderby à chamada de API.
Enviar email
Nesta seção, você adicionará a capacidade de enviar uma mensagem de email como o usuário autenticado.
Abra graphHelper.js e adicione a função a seguir.
async function sendMailAsync(subject, body, recipient) { // Ensure client isn't undefined if (!_userClient) { throw new Error('Graph has not been initialized for user auth'); } // Create a new message const message = { subject: subject, body: { content: body, contentType: 'text' }, toRecipients: [ { emailAddress: { address: recipient } } ] }; // Send the message return _userClient.api('me/sendMail') .post({ message: message }); } module.exports.sendMailAsync = sendMailAsync;
Substitua a função vazia
sendMailAsync
no index.js pelo seguinte.async function sendMailAsync() { try { // Send mail to the signed-in user // Get the user for their email address const user = await graphHelper.getUserAsync(); const userEmail = user?.mail ?? user?.userPrincipalName; if (!userEmail) { console.log('Couldn\'t get your email address, canceling...'); return; } await graphHelper.sendMailAsync('Testing Microsoft Graph', 'Hello world!', userEmail); console.log('Mail sent.'); } catch (err) { console.log(`Error sending mail: ${err}`); } }
Execute o aplicativo, entre e escolha a opção 3 para enviar um email para si mesmo.
[1] Display access token [2] List my inbox [3] Send mail [4] Make a Graph call [0] Exit Select an option [1...4 / 0]: 3 Mail sent.
Observação
Se você estiver testando com um locatário do desenvolvedor do Microsoft 365 Developer Program, o email enviado talvez não seja entregue e você poderá receber um relatório de não entrega. Se isso acontecer com você, entre em contato com o suporte por meio do Centro de administração do Microsoft 365.
Para verificar se a mensagem foi recebida, escolha a opção 2 para listar sua caixa de entrada.
Código explicado
Considere o código na sendMailAsync
função.
Enviar email
A função passa /me/sendMail
para o _userClient.api
construtor de solicitações, que cria uma solicitação para a API enviar email . O construtor de solicitações usa um Message
objeto que representa a mensagem a ser enviada.
Criando objetos
Ao contrário das chamadas anteriores para o Microsoft Graph que só leem dados, essa chamada cria dados. Para fazer isso com a biblioteca de clientes, você cria uma instância da classe que representa os dados (nesse caso, Message
), defina as propriedades desejadas e envie-as na chamada de API. Como a chamada está enviando dados, o post
método é usado em vez de get
.
Opcional: adicionar seu próprio código
Nesta seção, você adicionará seus próprios recursos do Microsoft Graph ao aplicativo. Isso pode ser um snippet de código da documentação do Microsoft Graph ou do Graph Explorer ou código que você criou. Esta seção é opcional.
Atualizar o aplicativo
Abra graphHelper.js e adicione a função a seguir.
// This function serves as a playground for testing Graph snippets // or other code async function makeGraphCallAsync() { // INSERT YOUR CODE HERE } module.exports.makeGraphCallAsync = makeGraphCallAsync;
Substitua a função vazia
makeGraphCallAsync
no index.js pelo seguinte.async function makeGraphCallAsync() { try { await graphHelper.makeGraphCallAsync(); } catch (err) { console.log(`Error making Graph call: ${err}`); } }
Escolher uma API
Encontre uma API no Microsoft Graph que você gostaria de experimentar. Por exemplo, a API criar eventos . Você pode usar um dos exemplos na documentação da API ou personalizar uma solicitação de API no Graph Explorer e usar o snippet gerado.
Configurar as permissões
Verifique a seção Permissões da documentação de referência da API escolhida para ver quais métodos de autenticação têm suporte. Algumas APIs não dão suporte somente a aplicativos ou contas pessoais da Microsoft, por exemplo.
- Para chamar uma API com autenticação de usuário (se a API dá suporte à autenticação de usuário (delegado), adicione o escopo de permissão necessário em appSettings.js.
- Para chamar uma API com autenticação somente aplicativo, consulte o tutorial de autenticação somente aplicativo .
Adicionar seu código
Copie seu makeGraphCallAsync
código na função no graphHelper.js. Se você estiver copiando um snippet da documentação ou do Graph Explorer, renomeie o client
para _userClient
.
Parabéns!
Você concluiu o tutorial do JavaScript Microsoft Graph. Agora que você tem um aplicativo de trabalho que chama Microsoft Graph, você pode experimentar e adicionar novos recursos.
- Saiba como usar a autenticação somente aplicativo com o SDK javaScript do Microsoft Graph.
- Visite a visão geral do Microsoft Graph para ver todos os dados que você pode acessar com o Microsoft Graph.
Kit de ferramentas do Microsoft Graph
Se você estiver criando aplicativos JavaScript com a interface do usuário, o Microsoft Graph Toolkit oferecerá uma coleção de componentes que podem simplificar o desenvolvimento.
Exemplos de TypeScript/JavaScript
Tem algum problema com essa seção? Se tiver, envie seus comentários para que possamos melhorar esta seção.