Niestandardowe polecenia HTTP w programie Aspire

W Aspire można dodawać niestandardowe polecenia HTTP do zasobów przy użyciu API WithHttpCommand. Ten interfejs API rozszerza istniejącą funkcjonalność, gdzie udostępniasz polecenia niestandardowe dotyczące zasobów. Ta funkcja umożliwia wykonanie polecenia na zasobie, który wysyła żądanie HTTP do wskazanego punktu końcowego i ścieżki. Jest to przydatne w scenariuszach, takich jak wyzwalanie migracji bazy danych, czyszczenie pamięci podręcznych lub wykonywanie niestandardowych akcji dotyczących zasobów za pośrednictwem żądań HTTP.

Aby zaimplementować niestandardowe polecenia HTTP, należy zdefiniować polecenie w zasobie i odpowiadający mu punkt końcowy HTTP, który obsługuje żądanie. Ten artykuł zawiera omówienie sposobu tworzenia i konfigurowania niestandardowych poleceń HTTP w programie Aspire.

Interfejsy API poleceń HTTP

Dostępne interfejsy API zapewniają rozbudowane możliwości z wieloma parametrami, aby dostosować polecenie HTTP. Aby dodać polecenie HTTP do zasobu, użyj WithHttpCommand metody rozszerzenia w konstruktorze zasobów. Dostępne są dwa przeciążenia:

Interfejs WithHttpCommand API udostępnia dwa rodzaje przeciążeń do dodawania niestandardowych poleceń HTTP do zasobów w Aspire. Te interfejsy API zostały zaprojektowane w celu zapewnienia elastyczności i obsługi różnych przypadków użycia podczas definiowania poleceń HTTP.

1. Przeciążanie za pomocą polecenia endpointName:

   Ta wersja jest idealna, gdy masz wstępnie zdefiniowaną nazwę punktu końcowego, którą powinno być docelowe polecenie HTTP. Upraszcza konfigurację przez bezpośrednie skojarzenie polecenia z określonym punktem końcowym. Jest to przydatne w scenariuszach, w których punkt końcowy jest statyczny i dobrze znany podczas opracowywania.

2. Przeciążanie za pomocą polecenia endpointSelector:

   Ta wersja zapewnia bardziej dynamiczne zachowanie, umożliwiając określenie wywołania zwrotnego (endpointSelector) w celu określenia punktu końcowego w czasie wykonywania. Jest to przydatne, gdy punkt końcowy może się różnić w zależności od stanu zasobu lub innych czynników kontekstowych. Zapewnia większą elastyczność w przypadku zaawansowanych scenariuszy, w których punkt końcowy nie może być zakodowany na stałe.

Oba przeciążenia pozwalają na obszerne dostosowywanie polecenia HTTP, dostarczając podklasę typu HttpCommandOptionsCommandOptions, obejmującą: określenie metody HTTP, konfigurowanie żądania, obsługę odpowiedzi oraz definiowanie właściwości związanych z interfejsem użytkownika, takich jak nazwa wyświetlana, opis i ikony. Wybór między nimi zależy od tego, czy punkt końcowy jest statyczny, czy dynamiczny w twoim przypadku użycia.

Te interfejsy API zostały zaprojektowane tak, aby bezproblemowo integrować się z Aspire ekosystemem, umożliwiając deweloperom rozszerzanie funkcjonalności zasobów przy minimalnym nakładzie pracy przy zachowaniu kontroli nad zachowaniem i prezentacją poleceń.

Zagadnienia dotyczące rejestrowania poleceń HTTP

Ponieważ polecenia HTTP są udostępniane za pośrednictwem punktów końcowych HTTP, rozważ potencjalne zagrożenia bezpieczeństwa. Ogranicz te punkty końcowe do środowisk programistycznych lub przejściowych, jeśli jest to możliwe. Zawsze weryfikuj żądania przychodzące, aby upewnić się, że pochodzą z zaufanych źródeł. Aby uzyskać więcej informacji, zobacz ASP.NET Core Zabezpieczenia.

Użyj wywołania zwrotnego HttpCommandOptions.PrepareRequest , aby zwiększyć bezpieczeństwo, dodając nagłówki uwierzytelniania lub inne miary. Typowym podejściem jest użycie wspólnej tajemnicy, parametru zewnętrznego lub tokenu znanego tylko hostowi AppHost i zasobowi. Ta wartość udostępniona może służyć do weryfikowania żądań i zapobiegania nieautoryzowanemu dostępowi.

Dodawanie niestandardowego polecenia HTTP

W pliku AppHost.cs dodajesz niestandardowe polecenie HTTP przy użyciu interfejsu API WithHttpCommand na IResourceBuilder<T>, gdzie T jest IResourceWithEndpoints. Oto przykład tego, jak to zrobić:

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache");

var apiCacheInvalidationKey = builder.AddParameter("ApiCacheInvalidationKey", secret: true);

var api = builder.AddProject<Projects.AspireApp_Api>("api")
    .WithReference(cache)
    .WaitFor(cache)
    .WithEnvironment("ApiCacheInvalidationKey", apiCacheInvalidationKey)
    .WithHttpCommand(
        path: "/cache/invalidate",
        displayName: "Invalidate cache",
        commandOptions: new HttpCommandOptions()
        {
            Description = """            
                Invalidates the API cache. All cached values are cleared!            
                """,
            PrepareRequest = (context) =>
            {
                var key = apiCacheInvalidationKey.Resource.GetValueAsync(context.CancellationToken);

                context.Request.Headers.Add("X-CacheInvalidation-Key", $"Key: {key}");

                return Task.CompletedTask;
            },
            IconName = "DocumentLightning",
            IsHighlighted = true
        });

builder.Build().Run();

Poprzedni kod:

• Tworzy nowego konstruktora aplikacji rozproszonych.
• Dodaje pamięć podręcznąRedis o nazwie cache do aplikacji.
• Dodaje parametr o nazwie ApiCacheInvalidationKey do aplikacji. Ten parametr jest oznaczony jako wpis tajny, co oznacza, że jego wartość jest bezpiecznie traktowana.
• Dodaje projekt o nazwie AspireApp_Api do aplikacji.
• Dodaje odwołanie do pamięci podręcznej Redis i czeka na gotowość przed kontynuowaniem.
• Konfiguruje polecenie HTTP dla projektu przy użyciu następujących elementów:
  • path: określa ścieżkę adresu URL dla polecenia HTTP (/cache/invalidate).
  • displayName: ustawia nazwę polecenia, jak jest wyświetlana w interfejsie użytkownika (Invalidate cache).
  • commandOptions: opcjonalne wystąpienie HttpCommandOptions , które konfiguruje zachowanie i wygląd polecenia w interfejsie użytkownika:
    • Description: zawiera opis polecenia wyświetlanego w interfejsie użytkownika.
    • PrepareRequest: funkcja wywołania zwrotnego, która konfiguruje żądanie HTTP przed wysłaniem żądania. W tym przypadku dodaje niestandardowy nagłówek (X-CacheInvalidation-Key) z wartością parametru ApiCacheInvalidationKey .
    • IconName: określa ikonę, która ma być używana dla polecenia w interfejsie użytkownika (DocumentLightningFilled).
    • IsHighlighted: wskazuje, czy polecenie powinno być wyróżnione w interfejsie użytkownika.
• Na koniec aplikacja jest kompilowana i uruchamiana.

Punkt końcowy HTTP jest odpowiedzialny za unieważnienie pamięci podręcznej. Po wykonaniu polecenia wysyła żądanie HTTP do określonej ścieżki (/cache/invalidate) ze skonfigurowanymi parametrami. Ponieważ dodano dodatkowy środek zabezpieczeń, żądanie zawiera nagłówek X-CacheInvalidation-Key z wartością parametru ApiCacheInvalidationKey. Zapewnia to, że tylko autoryzowane żądania mogą wyzwolić proces inwalidacji pamięci podręcznej.

Przykładowy punkt końcowy HTTP

Powyższy fragment kodu AppHost zdefiniował niestandardowe polecenie HTTP, które wysyła żądanie do punktu końcowego /cache/invalidate . Minimalny ASP.NET Core projekt interfejsu API definiuje punkt końcowy HTTP, który obsługuje żądanie unieważnienia pamięci podręcznej. Rozważ następujący fragment kodu z pliku Program.cs projektu:

app.MapPost("/cache/invalidate", static async (
    [FromHeader(Name = "X-CacheInvalidation-Key")] string? header,
    ICacheService registry,
    IConfiguration config) =>
{
    var hasValidHeader = config.GetValue<string>("ApiCacheInvalidationKey") is { } key
        && header == $"Key: {key}";

    if (hasValidHeader is false)
    {
        return Results.Unauthorized();
    }

    await registry.ClearAllAsync();

    return Results.Ok();
});

Poprzedni kod:

• Przyjęto założenie, że zmienna app jest wystąpieniem IApplicationBuilder klasy i jest skonfigurowana do obsługi żądań HTTP.
• Mapuje punkt końcowy HTTP POST na ścieżkę /cache/invalidate.
• Punkt końcowy oczekuje, że nagłówek o nazwie X-CacheInvalidation-Key będzie obecny w żądaniu.
• Pobiera wartość parametru ApiCacheInvalidationKey z konfiguracji.
• Jeśli wartość nagłówka nie jest zgodna z oczekiwanym kluczem, zwraca nieautoryzowaną odpowiedź.
• Jeśli nagłówek jest prawidłowy, wywołuje metodę ClearAllAsync na obiekcie ICacheService, aby wyczyścić wszystkie buforowane elementy.
• Na koniec zwraca odpowiedź HTTP OK.

Przykładowe zastosowania pulpitu nawigacyjnego

Przykładowa aplikacja AppHost i odpowiadające jej minimalne projekty API ilustrują obie strony implementacji poleceń HTTP. Po uruchomieniu AppHost strona Zasoby pulpitu nawigacyjnego wyświetla niestandardowe polecenie HTTP jako przycisk. Po określeniu, że polecenie powinno zostać wyróżnione (isHighlighted: true), przycisk zostanie wyświetlony w kolumnie Akcje na stronie Zasoby . Dzięki temu użytkownicy mogą łatwo wyzwalać polecenie z poziomu pulpitu nawigacyjnego, jak pokazano na poniższym zrzucie ekranu:

Jeśli chcesz pominąć isHighlighted parametr lub ustawić go na false, polecenie zostanie zagnieżdżone w menu trzech kropek w kolumnie Akcje strony Zasobów. Dzięki temu użytkownicy mogą uzyskiwać dostęp do polecenia bez zaśmiecania interfejsu użytkownika za pomocą zbyt wielu przycisków. Poniższy zrzut ekranu przedstawia to samo polecenie wyświetlane w menu wielokropka:

Gdy użytkownik wybierze przycisk, zostanie wykonane polecenie, a żądanie HTTP zostanie wysłane do określonego punktu końcowego. Pulpit nawigacyjny udostępnia opinię na temat stanu wykonywania polecenia, co umożliwia użytkownikom monitorowanie wyników. Po uruchomieniu zostanie wyświetlone wyskakujące powiadomienie:

Po zakończeniu polecenia pulpit nawigacyjny aktualizuje stan i przekazuje opinię na temat tego, czy zakończyła się powodzeniem, czy niepowodzeniem. Poniższy zrzut ekranu przedstawia pomyślne wykonanie polecenia:

Zobacz także

• Aspire omówienie aranżacji
• Polecenia zasobów niestandardowych w programie Aspire
• Aspire GitHub Repozytorium: przykładowy plac zabaw