Adicionar capacidades de e-mail a aplicações TypeScript com o Microsoft Graph

Neste artigo, vai expandir a aplicação que criou em Criar aplicações TypeScript com o Microsoft Graph com as APIs de correio do Microsoft Graph. Utilize o Microsoft Graph para listar a caixa de entrada do utilizador e enviar um e-mail.

Listar a caixa de entrada do utilizador

Comece por listar mensagens na caixa de entrada do e-mail do utilizador.

1. Abra graphHelper.ts e adicione a seguinte função.

   export async function getInboxAsync(): Promise<PageCollection> {
     // 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();
   }
   

2. Substitua a função empty ListInboxAsync no index.ts pelo seguinte.

   async function listInboxAsync() {
     try {
       const messagePage = await graphHelper.getInboxAsync();
       const messages: Message[] = 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}`);
     }
   }
   

3. Execute a aplicação, inicie sessão e selecione a opção 2 para listar a 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
   

getInboxAsync explicado

Considere o código na getInboxAsync função .

Aceder a pastas de correio conhecidas

A função passa /me/mailFolders/inbox/messages para o _userClient.api construtor de pedidos, que cria um pedido para a API Listar mensagens . Uma vez que inclui a /mailFolders/inbox parte do ponto final da API, a API só devolve mensagens na pasta de correio pedida. Neste caso, uma vez que a caixa de entrada é uma pasta predefinida e conhecida dentro da caixa de correio de um utilizador, é acessível através do nome conhecido. As pastas não predefinidas são acedidas da mesma forma ao substituir o nome conhecido pela propriedade ID da pasta de correio. Para obter detalhes sobre os nomes de pastas conhecidos disponíveis, consulte mailFolder resource type (Tipo de recurso mailFolder).

Aceder a uma coleção

Ao contrário da getUserAsync função da secção anterior, que devolve um único objeto, este método devolve uma coleção de mensagens. A maioria das APIs no Microsoft Graph que devolvem uma coleção não devolve todos os resultados disponíveis numa única resposta. Em vez disso, utilizam a paginação para devolver uma parte dos resultados ao fornecer um método para os clientes solicitarem a página seguinte.

Tamanhos de página predefinidos

As APIs que utilizam a paginação implementam um tamanho de página predefinido. Para mensagens, o valor predefinido é 10. Os clientes podem pedir mais (ou menos) através do parâmetro de consulta $top . No getInboxAsync, a adição $top é efetuada com o .top(25) método .

Obter páginas subsequentes

Se existirem mais resultados disponíveis no servidor, as respostas da coleção incluem uma @odata.nextLink propriedade com um URL de API para aceder à página seguinte. A biblioteca de cliente JavaScript expõe esta propriedade em PageCollection objetos. Se esta propriedade não for indefinida, existem mais resultados disponíveis.

O valor de @odata.nextLink pode ser transmitido para _userClient.api para obter a página seguinte dos resultados. Em alternativa, pode utilizar o PageIterator objeto da biblioteca de cliente para iterar em todas as páginas disponíveis.

Classificando coleções

A função utiliza o orderby método no pedido para pedir resultados ordenados quando a mensagem é recebida (receivedDateTime propriedade). Inclui o DESC palavra-chave para que as mensagens recebidas mais recentemente sejam listadas em primeiro lugar. Este método adiciona o parâmetro de consulta $orderby à chamada à API.

Enviar email

Agora, adicione a capacidade de enviar uma mensagem de e-mail como o utilizador autenticado.

1. Abra graphHelper.ts e adicione a seguinte função.

   export async function sendMailAsync(
     subject: string,
     body: string,
     recipient: string,
   ) {
     // Ensure client isn't undefined
     if (!_userClient) {
       throw new Error('Graph has not been initialized for user auth');
     }
   
     // Create a new message
     const message: Message = {
       subject: subject,
       body: {
         content: body,
         contentType: 'text',
       },
       toRecipients: [
         {
           emailAddress: {
             address: recipient,
           },
         },
       ],
     };
   
     // Send the message
     return _userClient.api('me/sendMail').post({ message: message });
   }
   

2. Substitua a função empty sendMailAsync no index.ts 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}`);
     }
   }
   

3. Execute a aplicação, inicie sessão e selecione a opção 3 para enviar um e-mail para si próprio.

   [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 estiver a testar com um inquilino de programador do Programa para Programadores do Microsoft 365, o e-mail que enviar poderá não ser entregue e poderá receber um relatório não dinâmico. Se quiser desbloquear o envio de correio do seu inquilino, contacte o suporte através do Centro de administração do Microsoft 365.

4. Para verificar se a mensagem foi recebida, selecione a opção 2 para listar a sua caixa de entrada.

sendMailAsync explicado

Considere o código na sendMailAsync função .

Enviar correio

A função passa /me/sendMail para o _userClient.api construtor de pedidos, que cria um pedido para a API enviar correio . O construtor de pedidos utiliza um Message objeto que representa a mensagem a enviar.

Criar objetos

Ao contrário das chamadas anteriores para o Microsoft Graph que só leem dados, esta chamada cria dados. Para criar itens com a biblioteca de cliente, crie uma instância da classe que representa os dados (neste caso, Message), defina as propriedades pretendidas e, em seguida, envie-as na chamada à API. Uma vez que a chamada está a enviar dados, o post método é utilizado em vez de get.

Próxima etapa