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

文章
07/03/2024

本教學課程是系列的最後一部分，示範如何從 .NET 精靈應用程式呼叫受保護的 Web API。在此系列的第 1 部分中，您已準備好外部租用戶來授權 .NET 精靈應用程式。在本教學課程中，您會建置用戶端精靈應用程式，並呼叫受保護的 Web API。您可以讓用戶端精靈應用程式使用自己的身分識別來取得存取權杖，然後呼叫 Web API。

本教學課程內容；

設定精靈應用程式以使用其應用程式註冊詳細資料。
建置精靈應用程式，以自行取得權杖，並呼叫受保護的Web API。

必要條件

教學課程：準備外部租用戶以授權 .NET 精靈應用程式

建立 .NET 精靈應用程式

開啟您的終端機，然後導覽至您要讓專案位於其中的資料夾。
初始化 .NET 主控台應用程式，並導覽至其根資料夾。
```
dotnet new console -n ToDoListClient
cd ToDoListClient
```

安裝套件

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

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

Microsoft.Identity.Web 可在 ASP.NET Core、驗證中介軟體與適用於 .NET 的 Microsoft 驗證程式庫 (MSAL) 之間提供聯繫管道，讓您更輕鬆地將驗證和授權功能新增至應用程式。 Microsoft.Identity.Web.DownstreamApi 提供用來呼叫下游 API 的介面。

建立 appsettings.json 檔案並新增註冊設定

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

將應用程式註冊詳細資料新增至 appsettings.json 檔案。

{
    "AzureAd": {
        "Authority": "https://<Enter_the_Tenant_Subdomain_Here>.ciamlogin.com/",
        "ClientId": "<Enter_the_Application_Id_here>",
        "ClientCredentials": [
            {
                "SourceType": "ClientSecret",
                "ClientSecret": "<Enter_the_Client_Secret_Here>"
            }
        ]
    },
    "DownstreamApi": {
        "BaseUrl": "<Web_API_base_url>",
        "RelativePath": "api/todolist",
        "RequestAppToken": true,
        "Scopes": [
            "api://<Enter_the_Web_Api_Application_Id_Here>/.default"
        ]
    }
}

將下列值取代為您自己的值：

值	Description
Enter_the_Application_Id_Here	您已註冊的用戶端精靈應用程式的「應用程式 (用戶端) 識別碼」。
Enter_the_Tenant_Subdomain_Here	目錄 (租用戶) 子網域。
Enter_the_Client_Secret_Here	您已建立的精靈應用程式祕密值。
Enter_the_Web_Api_Application_Id_Here	您已註冊的 Web API 應用程式的「應用程式 (用戶端) 識別碼」。
Web_API_base_url	Web API 的基底 URL。例如，`https://localhost:44351/`，其中 44351 是您 API 執行所在連接埠的連接埠號碼。您的 API 應該已經在此階段執行並等候要求，以讓您取得此值。

加入模型

導覽至專案資料夾的根目錄，然後建立 models 資料夾。在 models 資料夾中，建立 ToDo.cs 檔案，然後新增下列程式碼：

using System;

namespace ToDoListClient.Models;

public class ToDo
{
    public int Id { get; set; }
    public Guid Owner { get; set; }
    public string Description { get; set; } = string.Empty;
}

取得存取權杖

您現在已為精靈應用程式設定所需的項目。在此步驟中，您會撰寫可讓精靈應用程式取得存取權杖的程式碼。

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

將您的套件新增至檔案。

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

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

將此程式碼行新增至 program.cs 檔案：
```
var tokenAcquirerFactory = TokenAcquirerFactory.GetDefaultInstance();
```
設定要從設定中讀取應用程式選項，然後新增 DownstreamApi 服務。 DownstreamApi 服務提供用來呼叫下游 API 的介面。我們會在 config 物件中呼叫此服務 DownstreamAPI。精靈應用程式會讀取 appsettings.json 的 DownstreamApi 區段中的下游 API 設定。根據預設，您會取得記憶體內權杖快取。

將下列程式碼片段新增至 program.cs 檔案：
```
const string ServiceName = "DownstreamApi";

tokenAcquirerFactory.Services.AddDownstreamApi(ServiceName,
    tokenAcquirerFactory.Configuration.GetSection("DownstreamApi"));
```
建置權杖取得者。這會組成您已新增至 [服務] 的所有服務，並傳回服務提供者。使用此服務提供者來存取您已新增的 API 資源。在此情況下，您只將一個 API 資源新增為您想要存取的下游服務。

將下列程式碼片段新增至 program.cs 檔案：
```
var serviceProvider = tokenAcquirerFactory.Build();
```

呼叫 Web API

新增程式碼以使用 IDownstreamApi 介面來呼叫受保護的 Web API。在本教學課程中，您只會實作一個張貼待辦事項的呼叫，以及另一個取得所有待辦事項的呼叫。請參閱其他實作，例如範例程式碼中的 Delete 和 Put。

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

var toDoApiClient = serviceProvider.GetRequiredService<IDownstreamApi>();

Console.WriteLine("Posting a to-do...");

var firstNewToDo = await toDoApiClient.PostForAppAsync<ToDo, ToDo>(
    ServiceName,
    new ToDo()
    {
        Owner = Guid.NewGuid(),
        Description = "Bake bread"
    });

await DisplayToDosFromServer();
    
async Task DisplayToDosFromServer()
{
    Console.WriteLine("Retrieving to-do's from server...");
    var toDos = await toDoApiClient!.GetForAppAsync<IEnumerable<ToDo>>(
        ServiceName,
        options => options.RelativePath = "/api/todolist"
    );
    
    if (!toDos!.Any())
    {
        Console.WriteLine("There are no to-do's in server");
        return;
    }
    
    Console.WriteLine("To-do data:");
    
    foreach (var toDo in toDos!) {
        DisplayToDo(toDo);
    }
}

void DisplayToDo(ToDo toDo) {
    Console.WriteLine($"ID: {toDo.Id}");
    Console.WriteLine($"User ID: {toDo.Owner}");
    Console.WriteLine($"Message: {toDo.Description}");
}

執行用戶端精靈應用程式

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

dotnet run

如果沒有問題，則您應該會在終端機中看到下列輸出。

Posting a to-do...
Retrieving to-do's from server...
To-do data:
ID: 1
User ID: 00aa00aa-bb11-cc22-dd33-44ee44ee44ee

Message: Bake bread

疑難排解

如果您遇到錯誤，

確認您已新增至 appsettings.json 檔案的註冊詳細資料。
確認您要透過正確的連接埠和 https 來呼叫 Web API。
確認已正確地設定您的應用程式權限。

GitHub 上有提供完整的範例程式碼。

清除資源

若不想要使用已在本教學課程中註冊和建立的應用程式，請將其刪除，以避免產生任何成本。

另請參閱

在範例 Node.js 精靈應用程式中呼叫 API

分享方式：