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

發行項
01/27/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.DownstreamApi安裝與Microsoft.Identity.Web套件：

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	Directory （tenant）子域。
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;

建立令牌擷取實例。 GetDefaultInstance使用封裝類別的 Microsoft.Identity.Web 方法來TokenAcquirerFactory建置令牌擷取實例。根據預設，如果實例存在於與應用程式相同的資料夾中，則會讀取 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。在本教學課程中，您只會實作呼叫 Post a todo，另一個呼叫以取得所有待辦事項。請參閱其他實作，例如 Delete 和 Put in the sample code。

將此程式代碼行新增至 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: 00001111-aaaa-2222-bbbb-3333cccc4444

Message: Bake bread

疑難排解

如果您遇到錯誤，

確認您新增至appsettings.json檔案的註冊詳細數據。
確認您透過正確的埠和 HTTPs 呼叫 Web API。
確認您的應用程式許可權已正確設定。

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

清除資源

如果您不打算使用您在本教學課程中註冊並建立的應用程式，請將其刪除，以避免產生任何成本。

另請參閱

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

共用方式為