教學課程：從 .NET 精靈應用程式呼叫受保護的 Web API

適用於：綠色圓圈，內有白色複選標記的 工作群租戶 外部租戶（深入瞭解）

本教學課程示範如何從 .NET 精靈應用程式呼叫受保護的Web API。 您可以讓用戶端精靈應用程式使用自己的身分識別來取得存取令牌，然後呼叫 Web API。 在我們的案例中，我們會呼叫受保護的 Microsoft Graph 端點。

在本教學課程中;

• 設定精靈應用程式以使用其應用程式註冊詳細數據。 請確定您已將 Microsoft Graph API User.Read.All 許可權授與應用程式。
• 建置精靈應用程式，代表其取得令牌，並呼叫受保護的Web API。

先決條件

• .NET。 在本教學課程中，我們使用 .NET 9.0。
• Visual Studio Code 或其他程式碼編輯器。
• 您的租使用者中 的應用程式註冊。 確保您在應用程式註冊資訊中具有下列內容：
  • 您註冊之用戶端應用程式的 應用程式（用戶端）識別碼。
  • 您註冊的 web 應用程式所在的 目錄（租用戶）識別碼。
  • 您所建立的 Web 應用程式的 用戶端密鑰 的值。

建立 .NET 精靈應用程式

1. 開啟終端機，並流覽至您要讓項目上線的資料夾。

2. 初始化 .NET 控制台應用程式，並流覽至其根資料夾。

   dotnet new console -n DotnetDaemon
   cd DotnetDaemon
   

安裝套件

安裝 Microsoft.Identity.Web 與 Microsoft.Identity.Web.DownstreamApi 套件：

dotnet add package Microsoft.Identity.Web
dotnet add package Microsoft.Identity.Web.DownstreamApi

Microsoft.Identity.Web 提供適用於 .NET 的 ASP.NET Core、驗證中間件和 Microsoft 驗證連結庫 （MSAL） 之間的黏附，讓您更輕鬆地將驗證和授權功能新增至您的應用程式。 Microsoft.Identity.Web.DownstreamApi 提供用來呼叫下游 API 的介面。

建立 appsettings.json 檔案 並 新增註冊組態

1. 在應用程式的根資料夾中建立 appsettings.json 檔案。

2. 將應用程式註冊詳細數據新增至 appsettings.json 檔案。

   {
       "AzureAd": {
           // "Authority": "", you can use this for customer tenants in place of Instance and TenantId values
           "Instance": "https://login.microsoftonline.com/",
           "TenantId": "Enter_the_Tenant_ID_Here",
           "ClientId": "Enter_the_Application_ID_Here",
           "ClientCredentials": [
               {
                   "SourceType": "ClientSecret",
                   "ClientSecret": "Enter_the_Client_Secret_Here"
               }
           ]
       },
       "DownstreamApi": {
           "BaseUrl": "https://graph.microsoft.com",
           "RelativePath": "/v1.0/users/",
           "RequestAppToken": true,
           "Scopes": [
               "https://graph.microsoft.com/.default"
           ]
       }
   }
   

   以您自己的值取代下列值：

   價值	描述
   在此輸入應用程式 ID	您註冊之用戶端精靈應用程式的應用程式（用戶端）標識碼。
   Enter_the_Client_Secret_Here	您建立的精靈應用程式秘密值。
   輸入租戶 ID 這裡	註冊應用程式所在目錄/租戶的租戶 ID。

   注意

   針對在外部租戶中註冊的應用程式，您可以使用 Authority，並移除 Instance 和 TenantId。

   "Authority": "https://<Enter_the_Tenant_Subdomain_Here>.ciamlogin.com/"。 其中 Enter_the_Tenant_Subdomain_Here 是租用戶的子域。

3. 將 appsettings.json 檔案新增至項目檔。 項目檔是專案中 .csproj 檔案。 這是因為檔案必須複製到輸出目錄。

   <ItemGroup>
       <None Update="appsettings.json">
           <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
       </None>
   </ItemGroup>
   

取得存取令牌

1. 在程式代碼編輯器中開啟program.cs檔案，並刪除其內容。

2. 將您的套件新增至檔案。

   using Microsoft.Extensions.DependencyInjection;
   using Microsoft.Identity.Abstractions;
   using Microsoft.Identity.Web;
   

3. 建立 Token 取得實例。 使用 Microsoft.Identity.Web 軟體包的 TokenAcquirerFactory 類別的 GetDefaultInstance 方法來建置令牌取得實例。 根據預設，如果實例存在於與應用程式相同的資料夾中，則會讀取 appsettings.json 檔案。 GetDefaultInstance 也允許我們將服務新增至服務集合。

   將此程式代碼列新增至 program.cs 檔案：

   var tokenAcquirerFactory = TokenAcquirerFactory.GetDefaultInstance();
   

4. 設定要從組態讀取的應用程式選項，並新增 DownstreamApi 服務。 DownstreamApi 服務提供用來呼叫下游 API 的介面。 我們會在 config 物件中呼叫此服務 DownstreamAPI。 精靈應用程式會從 appsettings.json的 DownstreamApi 區段讀取下游 API 組態。 根據預設，您會取得記憶體內部令牌快取。

   將下列代碼段新增至 program.cs 檔案：

   const string ServiceName = "DownstreamApi";
   
   tokenAcquirerFactory.Services.AddDownstreamApi(ServiceName,
       tokenAcquirerFactory.Configuration.GetSection("DownstreamApi"));
   

   您呼叫的下游 API 是 Microsoft Graph。 在本教學課程中，我們使用 DownstreamApi 服務。 您也可以使用 Microsoft Graph SDK。

5. 建置令牌獲取器。 把新增的所有服務組合起來並傳回一個服務提供者。 使用此服務提供者來存取您新增的 API 資源。 在此情況下，您只會將一個 API 資源新增為您想要存取的下游服務。

   將下列代碼段新增至 program.cs 檔案：

   var serviceProvider = tokenAcquirerFactory.Build();
   

呼叫 Web API

1. 新增程序代碼，以使用 IDownstreamApi 介面呼叫受保護的 Web API。 在本教學課程中，我們會呼叫 Microsoft Graph API 端點。

2. 將此程式代碼新增至 program.cs 檔案：

   try
   {
       IDownstreamApi downstreamApi = serviceProvider.GetRequiredService<IDownstreamApi>();
   
       var response = await downstreamApi.GetForAppAsync<HttpResponseMessage>("DownstreamApi");
       var content = await response.Content.ReadAsStringAsync();
       var statusCode = response.StatusCode;
   
       Console.WriteLine($"Response status code: {statusCode}");
   
       if (!content.Any())
       {
           Console.WriteLine("There are no users to display.");
           return;
       }
   
       Console.WriteLine(content);
   }
   catch (Exception ex) { Console.WriteLine("We could not retrieve the user's list: " + $"{ex}"); }
   

   程式代碼會呼叫您在 appsettings.json 檔案中定義的端點。 IDownstreamApi 介面的 GetForAppAsync 方法可用來呼叫端點。 應用程式會代表自己進行呼叫。 方法會傳回 HttpResponseMessage 物件。 然後，回應會讀取為字串，並顯示在控制台中。

執行用戶端精靈應用程式

瀏覽至精靈應用程式的根資料夾，然後執行下列命令：

dotnet run

如果一切正常，您應該會在您的終端機中看到 回應狀態碼：OK。 如果有使用者，用戶會列在終端機中，否則您會看到訊息 沒有使用者可顯示。

如果發生任何錯誤，您會在終端機中看到錯誤訊息。

故障排除

如果您遇到錯誤，

• 確認您新增至 appsettings.json 檔案的註冊詳細數據。
• 確認您已將 appsettings.json 檔案新增至項目檔。
• 確認您的應用程式許可權已正確設定。