使用 適用於端點的 Microsoft Defender API

適用於：

• 適用於端點的 Microsoft Defender 方案 1
• 適用於端點的 Microsoft Defender 方案 2
• 適用於企業的 Microsoft Defender

重要事項

商務用Defender不包含進階搜捕功能。

想要體驗適用於端點的 Microsoft Defender 嗎？ 注册免費試用版。

注意事項

如果您是美國政府客戶，請使用美國政府客戶 適用於端點的 Microsoft Defender 中所列的 URI。

提示

為了獲得更好的效能，您可以使用更接近您地理位置的伺服器：

• us.api.security.microsoft.com
• eu.api.security.microsoft.com
• uk.api.security.microsoft.com
• au.api.security.microsoft.com
• swa.api.security.microsoft.com

此頁面描述如何建立應用程式，以程式設計方式代表使用者存取適用於端點的 Defender。

如果您需要沒有使用者的程式設計存取 適用於端點的 Microsoft Defender，請參閱具有應用程式內容的存取 適用於端點的 Microsoft Defender。

如果您不確定需要哪一個存取權，請閱讀 簡介頁面。

適用於端點的 Microsoft Defender 透過一組程序設計 API 公開其大部分的數據和動作。 這些 API 可讓您自動執行工作流程，並根據 適用於端點的 Microsoft Defender 功能進行創新。 API 存取需要 OAuth2.0 驗證。 如需詳細資訊，請參閱 OAuth 2.0 授權碼流程。

一般而言，您必須採取下列步驟來使用 API：

• Create Microsoft Entra 應用程式
• 使用此應用程式取得存取令牌
• 使用令牌存取適用於端點的Defender API

此頁面說明如何建立 Microsoft Entra 應用程式、取得存取令牌以 適用於端點的 Microsoft Defender 並驗證令牌。

注意事項

代表使用者存取 適用於端點的 Microsoft Defender API 時，您需要正確的應用程式許可權和用戶權力。 如果您不熟悉 適用於端點的 Microsoft Defender 的用戶權力，請參閱使用角色型訪問控制管理入口網站存取。

提示

如果您具有在入口網站中執行動作的許可權，您就有許可權可在 API 中執行動作。

Create 應用程式

1. 使用具有全域管理員角色的用戶帳戶登入 Azure。

2. 流覽至 [Microsoft Entra ID>應用程式註冊>[新增註冊]。

   

3. 當 [ 註冊應用程式] 頁面出現時，輸入應用程式的註冊資訊：

   • 名稱 - 輸入將顯示給應用程式使用者的有意義的應用程式名稱。

   • 支援的帳戶類型 - 選取您希望應用程式支援的帳戶。

     
     

     支援的帳戶類型	描述
     僅限此組織目錄中的帳戶	如果您要建置企業營運 (LOB) 應用程式，請選取此選項。 如果您未在目錄中註冊應用程式，則無法使用此選項。 此選項會對應至僅 Microsoft Entra 單一租使用者。 除非您在目錄外部註冊應用程式，否則這是預設選項。 如果應用程式在目錄外部註冊，預設值是 Microsoft Entra 多租用戶和個人 Microsoft 帳戶。
     任何組織目錄中的帳戶	如果您想要以所有商務和教育客戶為目標，請選取此選項。 此選項會對應至僅限 Microsoft Entra 的多租使用者。 如果您將應用程式註冊為僅限 Microsoft Entra 單一租使用者，您可以將它更新為 Microsoft Entra 多租使用者，並透過 [驗證] 刀鋒視窗回到單一租使用者。
     任何組織目錄和個人 Microsoft 帳戶中的帳戶	選取此選項以將目標設為最廣泛的客戶集合。 此選項會對應至 Microsoft Entra 多租用戶和個人 Microsoft 帳戶。 如果您將應用程式註冊為 Microsoft Entra 多租用戶和個人 Microsoft 帳戶，則無法在 UI 中變更。 相反地，您必須使用應用程式指令清單編輯器來變更支援的帳戶類型。

   • 重新導向 URI (選擇性) - 選取您要建置的應用程式類型、 Web 或 公用用戶端 (行動 & 桌面) ，然後輸入應用程式的重新導向 URI (或回復 URL) 。

     • 針對 Web 應用程式，提供您應用程式的基底 URL。 例如， http://localhost:31544 可能是在本機電腦上執行之 Web 應用程式的 URL。 使用者會使用此 URL 來登入 Web 用戶端應用程式。

     • 針對公用用戶端應用程式，請提供 Microsoft Entra ID 用來傳回令牌回應的 URI。 輸入應用程式特定的值，例如 myapp://auth。

     若要查看 Web 應用程式或原生應用程式的特定範例，請參閱我們的 快速入門。

     完成時，選取 [ 註冊]。

4. 允許您的應用程式存取 適用於端點的 Microsoft Defender 並指派「讀取警示」許可權：

   • 在應用程式頁面上，選取 [API 許可權>][新增許可權>API 我的組織使用> 類型 WindowsDefenderATP ]，然後在 WindowsDefenderATP 上選取。

     注意事項

     WindowsDefenderATP 不會出現在原始清單中。 開始在文字框中寫入其名稱，以查看其出現。

     

   • 選擇 [委派的>許可權警示]。讀>取 [新增許可權]。

     

   重要事項

   選取相關的許可權。 讀取警示只是一個範例。

   例如：

   • 若 要執行進階查詢，請選取 [ 執行進階查詢權 限]。

   • 若 要隔離裝置，請選取 [隔離機器 許可權]。

   • 若要判斷您需要的許可權，請在您想要呼叫 的 API 中檢視 [許可權] 區段。

   • 選 取 [授與同意]。

     注意事項

     每次新增許可權時，您都必須選取 [ 授與同意 ]，新許可權才會生效。

     

5. 記下您的應用程式識別碼和租用戶標識碼。

   在您的應用程式頁面上，移至 [ 概觀 ] 並複製下列資訊：

   

取得存取權杖

如需 Microsoft Entra 令牌的詳細資訊，請參閱 Microsoft Entra 教學課程。

使用 C#

• 在應用程式中複製/貼上下列類別。

• 使用 AcquireUserTokenAsync 方法搭配您的應用程式識別碼、租使用者標識碼、使用者名稱和密碼來取得令牌。

  namespace WindowsDefenderATP
  {
      using System.Net.Http;
      using System.Text;
      using System.Threading.Tasks;
      using Newtonsoft.Json.Linq;
  
      public static class WindowsDefenderATPUtils
      {
          private const string Authority = "https://login.microsoftonline.com";
  
          private const string WdatpResourceId = "https://api.securitycenter.microsoft.com";
  
          public static async Task<string> AcquireUserTokenAsync(string username, string password, string appId, string tenantId)
          {
              using (var httpClient = new HttpClient())
              {
                  var urlEncodedBody = $"resource={WdatpResourceId}&client_id={appId}&grant_type=password&username={username}&password={password}";
  
                  var stringContent = new StringContent(urlEncodedBody, Encoding.UTF8, "application/x-www-form-urlencoded");
  
                  using (var response = await httpClient.PostAsync($"{Authority}/{tenantId}/oauth2/token", stringContent).ConfigureAwait(false))
                  {
                      response.EnsureSuccessStatusCode();
  
                      var json = await response.Content.ReadAsStringAsync().ConfigureAwait(false);
  
                      var jObject = JObject.Parse(json);
  
                      return jObject["access_token"].Value<string>();
                  }
              }
          }
      }
  }
  

驗證令牌

請確認您已取得正確的權杖：

• 將您在上一個步驟中取得的令牌複製/貼到 JWT 中，以便將它譯碼。

• 驗證您取得具有所需應用程式許可權的 『scp』 宣告。

• 在下列螢幕快照中，您可以在教學課程中看到從應用程式取得的已譯碼令牌：

  

使用令牌存取 適用於端點的 Microsoft Defender API

• 選擇您想要使用的 API - 支援的 適用於端點的 Microsoft Defender API。

• 在您傳送至 「Bearer {token}」 的 HTTP 要求中設定 Authorization 標頭 (Bearer 是授權配置) 。

• 令牌的到期時間為 1 小時， (您可以傳送多個具有相同令牌) 的要求。

• 使用 C# 傳送要求以取得警示清單的範例：

  var httpClient = new HttpClient();
  
  var request = new HttpRequestMessage(HttpMethod.Get, "https://api.securitycenter.microsoft.com/api/alerts");
  
  request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
  
  var response = httpClient.SendAsync(request).GetAwaiter().GetResult();
  
  // Do something useful with the response
  

另請參閱

• 適用於端點的 Microsoft Defender API
• 使用應用程式內容存取 適用於端點的 Microsoft Defender

提示

想要深入了解? Engage 技術社群中的 Microsoft 安全性社群：適用於端點的 Microsoft Defender 技術社群。