顯示使用者的電子郵件

已完成

您已建置 JavaScript 應用程式，然後使用 Microsoft 驗證程式庫將應用程式連線到 Microsoft 365。 現在是擷取使用者的電子郵件，並將它們顯示在您的應用程式中的時候。

決定您的應用程式需要的權限

Microsoft Graph 公開的所有資料都受到保護，而且您的應用程式必須獲與適當權限才能存取它。 您需要的權限取決於您的應用程式需要存取的資訊類型。 例如，若要存取使用者的行事曆，您的應用程式必須擁有 Calendars.Read 權限。 若要存取使用者的電子郵件，您的應用程式需要 Mail.Read 權限。 Microsoft Graph API 參考中提供每項作業所需權限的確切清單。

如果您的應用程式載入不同類型的資料，使用者必須授與其存取此資訊所需的多個權限。 您的應用程式僅應要求您實際上需要的權限。

假設您的應用程式有兩個頁面。 一個頁面顯示使用者的電子郵件，另一個頁面顯示其行事曆。 當使用者第一次登入您的應用程式，您的應用程式只會要求存取其基本設定檔資訊。 當他們前往顯示電子郵件的頁面，您的應用程式會要求讀取其電子郵件的權限。 如果他們從未瀏覽您應用程式中顯示其行事曆的頁面，您的應用程式將無法存取其行事曆資料。

此模式稱為動態同意，而這是依連線至 Microsoft 365 的應用程式要求權限的建議方式。 有了動態同意，使用者可以控制他們與使用的應用程式共用的資料，將安全性風險降至最低。

指定必要權限

呼叫 Microsoft Graph 之前，請確保 Microsoft 驗證程式庫包含 Microsoft Graph 所需的權限清單。 Microsoft 驗證程式庫會自動檢查先前所擷取的存取權杖是否具有必要的範圍。 如果沒有，它會自動嘗試為您取得新的存取權杖。 當您第一次使用應用程式，Microsoft 驗證程式庫會顯示快顯視窗，要求您同意應用程式存取此資訊。

如果您追蹤全域變數中的 Microsoft 驗證程式庫範圍，請在執行呼叫之前，先檢查範圍清單中是否包含必要的權限。 因為您必須在每個呼叫之前確定所需的範圍，您可以將它包裝在協助程式函數中。

function ensureScope (scope) {
  if (!msalRequest.scopes.some((s) => s.toLowerCase() === scope.toLowerCase())) {
    msalRequest.scopes.push(scope);
  }
}

呼叫 Microsoft Graph 以擷取資料時，您會呼叫協助程式函數，以確保包含必要的權限。

async function getEmails() {
  ensureScope('mail.read');
  // ...
}

從 Microsoft Graph 中擷取使用者的電子郵件

若要從 Microsoft Graph 取得使用者的電子郵件，您可以呼叫 /me/messages 端點。 它會傳回已登入使用者信箱中的電子郵件清單。 若要取得使用者的電子郵件，您的應用程式必須獲授與 Mail.Read 權限。 您可以使用 Microsoft Graph SDK 來呼叫 Microsoft Graph 端點。 若要使用它，您可以指定端點以及您想要執行的要求類型。

擷取電子郵件是 GET 要求，執行方式如下：

graphClient.api('/me/messages').get();

Microsoft Graph 端點會以任意順序傳回資料。 為了確保您收到最新的郵件，請以收到郵件的日期遞減排序。

graphClient
  .api('/me/messages')
  .orderby('receivedDateTime desc')
  .get();

當您從 Microsoft Graph 中擷取資料時，應一律僅擷取您需要的資料 (如稍早所述)。 將 Microsoft Graph 透過網路擷取和傳輸到您的資料量最小化，可大幅改善您應用程式的效能。

您可以用兩種方式限制從 Microsoft 365 中擷取的資料量：

• 選取您想要取得的項目數。
• 選取要包含的特定資訊。

若要指定您要擷取的屬性，請使用 select 方法延伸 Microsoft Graph 要求，並傳遞要傳回的逗號分隔屬性清單。 例如，若要取得只包含其主旨和收到日期/時間的電子郵件清單，請使用下列命令：

graphClient
  .api('/me/messages')
  .select('subject,receivedDateTime')
  .orderby('receivedDateTime desc')
  .get();

提示

您可以在 Microsoft Graph API 參考中找到每個端點上可用屬性的完整清單。

您可以執行以限制從 Microsoft 365 傳回的資料量的另一個動作，就是指定您想要取得多少個項目。 若要指定您想要取得多少個項目，請使用 top 方法延伸 Microsoft Graph 要求。 例如，若要擷取收到的前 10 封電子郵件，請使用下列命令：

graphClient
  .api('/me/messages')
  .select('subject,receivedDateTime')
  .orderby('receivedDateTime desc')
  .top(10)
  .get();

後續步驟

讓我們利用您所學習到的所有內容，以練習並延伸您的應用程式，以便顯示目前使用者的收到的前 10 封電子郵件。