Criar aplicativos JavaScript com o Microsoft Graph
Este tutorial ensina como criar um aplicativo de console JavaScript que usa o Microsoft API do Graph.
Dica
Se você preferir apenas baixar o tutorial concluído, poderá baixar ou clonar o GitHub repositório.
Pré-requisitos
Antes de iniciar este tutorial, você deve ter os Node.js instalados em seu computador de desenvolvimento.
Você também deve ter uma conta microsoft pessoal com uma caixa de correio no Outlook.com ou uma conta corporativa ou de estudante da Microsoft. Se você não tiver uma conta da Microsoft, há algumas opções para obter uma conta gratuita:
- Você pode se inscrever para uma nova conta pessoal da Microsoft.
- Você pode se inscrever no Microsoft 365 Developer Program para obter uma assinatura Microsoft 365 assinatura gratuita.
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 Azure Active Directory de administração 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 de usuário usando o fluxo de código do dispositivo.
Abra um navegador, navegue até o centro de administração do Azure Active Directory e faça logon usando uma conta pessoal (também conhecida como conta da Microsoft) ou Conta Corporativa 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,
JavaScript Graph Tutorial.Defina os tipos de conta com suporte conforme desejado. As opções são:
Opção Who pode entrar? Contas apenas neste diretório organizacional Somente usuários em sua Microsoft 365 organização Contas em qualquer diretório organizacional Usuários em qualquer Microsoft 365 (contas corporativas ou de estudante) Contas em qualquer diretório organizacional... e contas pessoais da Microsoft Usuários em qualquer organização Microsoft 365 (contas corporativas ou de estudante) 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 do cliente público para Sim e, em seguida, 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 usará 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 Node.js projeto. 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 continuar, adicione algumas dependências adicionais que você usará posteriormente.
- Biblioteca de clientes de Identidade do Azure para JavaScript para autenticar o usuário e adquirir tokens de acesso.
- Microsoft Graph biblioteca de clientes JavaScript para fazer chamadas para o Microsoft Graph.
- isomorphic-fetch para adicionar
fetchAPI ao Node.js. Essa é uma dependência da biblioteca de clientes do Microsoft Graph JavaScript. - readline-sync para solicitar a entrada do 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.
Atualize os valores de
settingsacordo com a tabela a seguir.Configuração Valor clientIdA ID do cliente do registro do aplicativo authTenantSe você escolheu a opção para permitir que apenas os usuários em sua organização se conectem, 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 esse arquivo em etapas posteriores.
module.exports = {};Crie um arquivo na raiz do projeto chamado index.js e adicione o código a seguir.
Adicione os métodos de espaço reservado a seguir ao 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 listUsersAsync() { // 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 do Azure Identity para JavaScript ao aplicativo e configurará a autenticação para a biblioteca de clientes JavaScript do Microsoft Graph.
A biblioteca de identidade do Azure fornece várias TokenCredential classes que implementam fluxos de token OAuth2. A biblioteca de Graph microsoft usa essas classes para autenticar chamadas para o Microsoft Graph. Neste exemplo, usaremos as classes a TokenCredential seguir.
DeviceCodeCredentialimplementa o fluxo de código do dispositivo para autenticação do usuário.ClientSecretCredentialimplementa o fluxo de credenciais do cliente para autenticação somente de aplicativo. Você usará essa classe nas seções opcionais somente de aplicativo.
Configurar Graph cliente para autenticação de usuário
Nesta seção, você usará a classe para DeviceCodeCredential solicitar um token de acesso usando o fluxo de código do dispositivo.
Crie um novo arquivo na raiz do projeto chamado graphHelper.js e adicione o código a seguir a esse arquivo.
Substitua a função
initializeGraphvazia no index.js pelo seguinte.
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 à API for feita ao Microsoft Graph_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 de DeviceCodeCredential.
Adicione a seguinte função a graphHelper.js.
Substitua a função
displayAccessTokenAsyncvazia no index.js pelo seguinte.Execute o comando a seguir na CLI na raiz do projeto.
node index.jsInsira
1quando for solicitada uma opção. O aplicativo exibe uma URL e um código do dispositivo.JavaScript Graph Tutorial [1] Display access token [2] List my inbox [3] Send mail [4] List users (requires app-only) [5] Make a Graph call [0] Exit Select an option [1...5 / 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
Lembre-se de todas as contas Microsoft 365 existentes que estão conectadas ao seu navegador ao navegar até
https://microsoft.com/devicelogin. Use recursos do navegador, como perfis, modo de 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 de estudante) 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 declaração
scpno token contém os escopos de permissão Graph Microsoft esperados.
Obter usuário
Nesta seção, você incorporará o microsoft Graph no aplicativo. Você usará a biblioteca de clientes JavaScript do Microsoft Graph para fazer chamadas ao Microsoft Graph.
Abra graphHelper.js e adicione a função a seguir.
Substitua a função
greetUserAsyncvazia no index.js pelo seguinte.
Se você executar o aplicativo agora, depois de fazer logon, o 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 notado.
Acessando 'eu'
A função passa para /me o construtor _userClient.api de solicitações, que cria uma solicitação para a API Obter usuário . Essa API pode ser acessada de duas maneiras:
GET /me
GET /users/{user-id}
Nesse caso, o código chamará o ponto de extremidade GET /me da API. Esse é um método de atalho para obter o usuário autenticado sem saber sua ID de usuário.
Observação
Como o GET /me ponto de extremidade da API obtém o usuário autenticado, ele só está disponível para aplicativos que usam autenticação de usuário. Os aplicativos de autenticação somente de 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 $select de consulta à chamada à 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, somente as propriedades solicitadas terão valores no objeto User retornado. Todas as outras propriedades terão valores padrão.
Caixa de entrada de lista
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.
Substitua a função
ListInboxAsyncvazia no index.js pelo seguinte.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] List users (requires app-only) [5] Make a Graph call [0] Exit Select an option [1...5 / 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 conhecidas
A função passa para /me/mailFolders/inbox/messages o construtor _userClient.api de solicitações, que cria uma solicitação para a API listar mensagens . Como ele inclui a parte /mailFolders/inbox do ponto de extremidade da API, a API retornará apenas 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 de ID da pasta de email. Para obter detalhes sobre os nomes de pasta conhecidos disponíveis, consulte o tipo de recurso mailFolder.
Acessando uma coleção
Ao contrário getUserAsync da 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 a 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
As 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 $top consulta. Em getInboxAsync, isso é feito com o .top(25) método.
Observação
O valor passado é .top() um limite superior, não um número explícito. A API retorna um número de mensagens até o valor especificado.
Obtendo páginas subsequentes
Se houver mais resultados disponíveis no servidor, @odata.nextLink as respostas da coleção incluirão uma propriedade com uma URL de API para acessar a próxima página. A biblioteca de clientes Java expõe essa propriedade em PageCollection objetos. Se essa propriedade não for 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 objeto PageIterator 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 pelo momento em que a mensagem é recebida (receivedDateTime propriedade). Ele inclui a palavra-chave DESC para que as mensagens recebidas mais recentemente sejam listadas primeiro. Isso adiciona o $orderby de consulta à chamada à 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.
Substitua a função
sendMailAsyncvazia no index.js pelo seguinte.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] List users (requires app-only) [5] Make a Graph call [0] Exit Select an option [1...5 / 0]: 3 Mail sent.Observação
Se você estiver testando com um locatário de desenvolvedor do Microsoft 365 Developer Program, o email enviado poderá não ser 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.
Código explicado
Considere o código na sendMailAsync função.
Enviar email
A função passa para /me/sendMail o construtor _userClient.api 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 ao Microsoft Graph que somente leem dados, essa chamada cria dados. Para fazer isso com a biblioteca de clientes, crie uma instância da classe que representa os dados (nesse caso), Messagedefina as propriedades desejadas e, em seguida, envie-a na chamada à API. Como a chamada está enviando dados, o post método é usado em vez de get.
Opcional: configurar a autenticação somente de aplicativo
Nesta seção, você atualizará o registro do aplicativo da seção anterior para dar suporte à autenticação somente de aplicativo. A autenticação somente de aplicativo é uma boa opção para serviços em segundo plano e também há algumas APIs que dão suporte apenas à autenticação somente de aplicativo. Você só precisará concluir esta seção se pretende usar as partes somente de aplicativo deste tutorial. Caso contrário, você pode pular com segurança para a próxima etapa.
Importante
As etapas nesta seção exigem uma conta corporativa/de estudante com a Administrador global função.
Abra o registro do aplicativo na seção anterior no Azure AD de administração.
Selecione Permissões de API em Gerenciar.
Remova a permissão User.Read padrão em Permissões configuradas selecionando as reticências (...) em sua linha e selecionando Remover permissão.
Selecione Adicionar uma permissão e, em seguida, Microsoft Graph.
Selecione Permissões de aplicativo.
Selecione User.Read.All e, em seguida, selecione Adicionar permissões.
Selecione Conceder consentimento do administrador para... e, em seguida, selecione Sim para fornecer consentimento do administrador para a permissão selecionada.
Selecione Certificados e segredos em Gerenciar e, em seguida, selecione Novo segredo do cliente.
Insira uma descrição, escolha uma duração e selecione Adicionar.
Copie o segredo da coluna Valor , você precisará dele nas próximas etapas.
Importante
Este segredo do cliente nunca é mostrado novamente, portanto, certifique-se de copiá-lo agora.
Observação
Observe que, ao contrário das etapas ao se registrar para autenticação do usuário, nesta seção você configurou as permissões do Microsoft Graph no registro do aplicativo. Isso ocorre porque a autenticação somente de aplicativo usa o fluxo de credenciais do cliente, o que exige que as permissões sejam configuradas no registro do aplicativo. Consulte o escopo .default para obter detalhes.
Opcional: adicionar autenticação somente de aplicativo
Nesta seção, você adicionará a autenticação somente de aplicativo ao aplicativo. Esta seção é opcional e requer a conclusão de Opcional: configurar a autenticação somente de aplicativo. Essas etapas só podem ser concluídas com uma conta corporativa ou de estudante.
Configurar Graph cliente para autenticação somente de aplicativo
Nesta seção, você usará a classe para ClientSecretCredential solicitar um token de acesso usando o fluxo de credenciais do cliente.
Atualize os valores de
settingsacordo com a tabela a seguir.Configuração Valor tenantIdID do locatário da sua organização clientSecretO segredo do cliente gerado na etapa anterior Atualize os valores em
tenantIdappsettings.js com a ID de locatário da sua organização.Abra graphHelper.js e adicione o código a seguir.
Opcional: listar usuários
Nesta seção, você adicionará a capacidade de listar todos os usuários em seu Azure Active Directory usando a autenticação somente de aplicativo. Esta seção é opcional e requer a conclusão de Opcional: configurar a autenticação somente de aplicativo e Opcional: adicionar autenticação somente de aplicativo. Essas etapas só podem ser concluídas com uma conta corporativa ou de estudante.
Abra graphHelper.js e adicione a função a seguir.
Substitua a função
listUsersAsyncvazia no index.js pelo seguinte.Execute o aplicativo, entre e escolha a opção 4 para listar usuários.
[1] Display access token [2] List my inbox [3] Send mail [4] List users (requires app-only) [5] Make a Graph call [0] Exit Select an option [1...5 / 0]: 4 User: Adele Vance ID: 05fb57bf-2653-4396-846d-2f210a91d9cf Email: AdeleV@contoso.com User: Alex Wilber ID: a36fe267-a437-4d24-b39e-7344774d606c Email: AlexW@contoso.com User: Allan Deyoung ID: 54cebbaa-2c56-47ec-b878-c8ff309746b0 Email: AllanD@contoso.com User: Bianca Pisani ID: 9a7dcbd0-72f0-48a9-a9fa-03cd46641d49 Email: NO EMAIL User: Brian Johnson (TAILSPIN) ID: a8989e40-be57-4c2e-bf0b-7cdc471e9cc4 Email: BrianJ@contoso.com ... More users available? true
Código explicado
Considere o código na getUsersAsync função. É muito semelhante ao código em getInboxAsync:
- Ele obtém uma coleção de usuários
- Ele usa para
selectsolicitar propriedades específicas - Ele usa
toppara limitar o número de usuários retornados - Ele usa
orderBypara classificar a resposta
A principal diferença é que esse código usa o _appClient, não o _userClient. Ambos os clientes usam a mesma sintaxe e construtores de solicitação, mas foram configurados com credenciais diferentes.
Opcional: adicionar seu próprio código
Nesta seção, você adicionará seus próprios recursos Graph Microsoft ao aplicativo. Pode ser um snippet de código da documentação do Microsoft Graph ou 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.
Substitua a função
makeGraphCallAsyncvazia no index.js pelo seguinte.
Escolher uma API
Encontre uma API no Microsoft Graph que você gostaria de experimentar. Por exemplo, a API criar evento . 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 der suporte à autenticação de usuário (delegada), adicione o escopo de permissão necessário appSettings.js.
- Para chamar uma API com autenticação somente de aplicativo (se a API der suporte a ela), adicione o escopo de permissão necessário no Azure AD de administração.
Adicionar seu código
Copie seu código para a makeGraphCallAsync função em graphHelper.js. Se você estiver copiando um snippet de documentação ou Graph Explorer, client renomeie-o para o cliente apropriado: _userClient ou _appClient.
Parabéns!
Você concluiu o tutorial do Microsoft Graph JavaScript. Agora que você tem um aplicativo funcional que chama o Microsoft Graph, você pode experimentar e adicionar novos recursos. 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 oferece 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.