Samouczek: wywoływanie chronionego internetowego interfejsu API z poziomu aplikacji demona platformy .NET

2025-03-05

Dotyczy: Zielony okrąg z białym symbolem znacznika wyboru. Najemcy usługi Workforce Najemcy zewnętrzni (dowiedz się więcej)

W tym samouczku pokazano, jak wywołać chroniony internetowy interfejs API z poziomu aplikacji demona platformy .NET. Aplikacja demona klienta umożliwia uzyskanie tokenu dostępu przy użyciu własnej tożsamości, a następnie wywołanie internetowego interfejsu API. W naszym przypadku wywołujemy chroniony punkt końcowy usługi Microsoft Graph.

W tym samouczku;

Skonfiguruj aplikację działającą w tle, aby używała szczegółów rejestracji aplikacji. Upewnij się, że przyznasz aplikacji uprawnienie User.Read.All w interfejsie API programu Microsoft Graph.
Utwórz aplikację demona, która uzyskuje token we własnym imieniu i wywołuje chroniony internetowy interfejs API.

Warunki wstępne

.NET. W tym samouczku używamy platformy .NET 9.0.
Visual Studio Code lub innego edytora kodu.
Rejestracja aplikacji w Twoim dzierżawcy. Upewnij się, że masz następujące informacje na temat szczegółów rejestracji aplikacji:
- Identyfikator aplikacji (klienta) dla zarejestrowanej aplikacji internetowej klienta.
- Identyfikator katalogu (tenanta) , w którym zarejestrowano aplikację internetową.
- Wartość klucza tajnego klienta dla utworzonej aplikacji internetowej.

Utwórz aplikację demona .NET

Otwórz terminal i przejdź do folderu, w którym ma działać projekt.
Zainicjuj aplikację konsolową platformy .NET i przejdź do folderu głównego.
```
dotnet new console -n DotnetDaemon
cd DotnetDaemon
```

Instalowanie pakietów

Zainstaluj pakiety Microsoft.Identity.Web i Microsoft.Identity.Web.DownstreamApi:

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

Microsoft.Identity.Web zapewnia klej między platformą ASP.NET Core, oprogramowaniem pośredniczącym uwierzytelniania i biblioteką Microsoft Authentication Library (MSAL) dla platformy .NET, co ułatwia dodawanie funkcji uwierzytelniania i autoryzacji do aplikacji. Microsoft.Identity.Web.DownstreamApi udostępnia interfejs używany do wywoływania podrzędnego interfejsu API.

Utwórz plik appsettings.json i dodaj konfiguracje rejestracji

Utwórz plik appsettings.json w folderze głównym aplikacji.

Dodaj szczegóły rejestracji aplikacji do pliku 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"
        ]
    }
}

Zastąp następujące wartości własnymi wartościami:

Wartość	Opis
Wprowadź_ID_aplikacji_tutaj	Identyfikator aplikacji (klienta) zarejestrowanej aplikacji demona klienta.
Wprowadź_tutaj_Tajny_Klient	Utworzony tajny klucz aplikacji demona.
Wprowadź_ID_Najemcy_Tutaj	Identyfikator katalogu/dzierżawy, w którym zarejestrowano aplikację.

Notatka

W przypadku aplikacji zarejestrowanych w zewnętrznej dzierżawie można użyć Authority i usunąć zarówno Instance, jak i TenantId.

"Authority": "https://<Enter_the_Tenant_Subdomain_Here>.ciamlogin.com/". Gdzie Enter_the_Tenant_Subdomain_Here jest subdomeną lokatora.

Dodaj plik appsettings.json do pliku projektu. Plik projektu w twoim projekcie to plik .csproj. Jest to spowodowane tym, że plik musi zostać skopiowany do katalogu wyjściowego.
```
<ItemGroup>
    <None Update="appsettings.json">
        <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
</ItemGroup>
```

Uzyskiwanie tokenu dostępu

Otwórz plik program.cs w edytorze kodu i usuń jego zawartość.

Dodaj pakiety do pliku.

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

Utwórz wystąpienie pozyskiwania tokenu. Użyj metody GetDefaultInstance klasy TokenAcquirerFactory pakietu Microsoft.Identity.Web, aby skompilować wystąpienie pozyskiwania tokenu. Domyślnie wystąpienie odczytuje plik appsettings.json, jeśli istnieje w tym samym folderze co aplikacja. GetDefaultInstance umożliwia również dodawanie usług do kolekcji usług.

Dodaj ten wiersz kodu do pliku program.cs:
```
var tokenAcquirerFactory = TokenAcquirerFactory.GetDefaultInstance();
```
Skonfiguruj opcje aplikacji, aby były czytane z konfiguracji, i dodaj usługę DownstreamApi. Usługa DownstreamApi udostępnia interfejs używany do wywoływania podrzędnego interfejsu API. Wywołujemy tę usługę DownstreamAPI w obiekcie konfiguracji. Aplikacja demona odczytuje konfiguracje podrzędnego interfejsu API z sekcji DownstreamApiappsettings.json. Domyślnie uzyskuje się pamięć podręczną tokenów w pamięci operacyjnej.

Dodaj następujący fragment kodu do pliku program.cs:
```
const string ServiceName = "DownstreamApi";

tokenAcquirerFactory.Services.AddDownstreamApi(ServiceName,
    tokenAcquirerFactory.Configuration.GetSection("DownstreamApi"));
```
Wywoływany podrzędny interfejs API to Microsoft Graph. W tym samouczku użyjemy usługi DownstreamApi. Możesz również użyć zestawu Microsoft Graph SDK.
Skompiluj program pozyskiwania tokenów. To łączy wszystkie dodane usługi i zwraca dostawcę usług. Użyj tego dostawcy usług, aby uzyskać dostęp do zasobu API, który dodajesz. W takim przypadku należy dodać tylko jeden zasób interfejsu API jako usługę podrzędną, do której chcesz uzyskać dostęp.

Dodaj następujący fragment kodu do pliku program.cs:
```
var serviceProvider = tokenAcquirerFactory.Build();
```

Wywoływanie webowego interfejsu API

Dodaj kod, aby wywołać chroniony interfejs API sieci web przy użyciu interfejsu IDownstreamApi. W tym samouczku wywołujemy punkt końcowy interfejsu API programu Microsoft Graph.

Dodaj ten kod do pliku 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}"); }

Kod wywołuje punkt końcowy zdefiniowany w pliku appsettings.json. Metoda GetForAppAsync interfejsu IDownstreamApi służy do wywoływania punktu końcowego. Aplikacja samodzielnie wykonuje połączenie w swoim imieniu. Metoda zwraca obiekt HttpResponseMessage. Odpowiedź jest następnie odczytywana jako ciąg i wyświetlana w konsoli programu .

Uruchamianie aplikacji demona klienta

Przejdź do folderu głównego aplikacji demona i uruchom następujące polecenie:

dotnet run

Jeśli wszystko jest w porządku, w terminalu powinien zostać wyświetlony kod stanu odpowiedzi : OK. Jeśli istnieją użytkownicy, użytkownicy są wyświetlani w terminalu. W przeciwnym razie zostanie wyświetlony komunikat Brak użytkowników do wyświetlenia.

Jeśli wystąpią jakiekolwiek błędy, w terminalu zostanie wyświetlony komunikat o błędzie.

Rozwiązywanie problemów

W przypadku napotkania błędów,

Potwierdź szczegóły rejestracji dodane do pliku appsettings.json.
Upewnij się, że plik appsettings.json został dodany do pliku projektu.
Upewnij się, że uprawnienia aplikacji są poprawnie skonfigurowane.