Vlastní příkazy HTTP v Aspire

Do Aspireprostředků WithHttpCommand pomocí rozhraní API můžete přidat vlastní příkazy HTTP. Toto rozhraní API rozšiřuje stávající funkce, kde poskytujete vlastní příkazy pro prostředky. Tato funkce umožňuje příkaz na prostředku, který odešle požadavek HTTP do zadaného koncového bodu a cesty. To je užitečné pro scénáře, jako je aktivace migrací databáze, vymazání mezipamětí nebo provádění vlastních akcí s prostředky prostřednictvím požadavků HTTP.

Pokud chcete implementovat vlastní příkazy HTTP, definujete příkaz pro prostředek a odpovídající koncový bod HTTP, který zpracovává požadavek. Tento článek obsahuje přehled, jak vytvořit a nakonfigurovat vlastní příkazy HTTP v Aspire.

HTTP příkazové API

Dostupná rozhraní API poskytují rozsáhlé možnosti s mnoha parametry pro přizpůsobení příkazu HTTP. Pokud chcete do prostředku přidat příkaz HTTP, použijte metodu WithHttpCommand rozšíření v Tvůrci prostředků. K dispozici jsou dvě možnosti přetížení:

Rozhraní WithHttpCommand API poskytuje dvě přetížení pro přidání vlastních příkazů HTTP do prostředků v Aspire. Tato rozhraní API jsou navržená tak, aby nabízela flexibilitu a vyhovovala různým případům použití při definování příkazů HTTP.

1. Přetížení s endpointName:

   Tato verze je ideální, pokud máte předdefinovaný název koncového bodu, na který by měl cílit příkaz HTTP. Zjednodušuje konfiguraci tím, že příkaz přímo přidružuje ke konkrétnímu koncovému bodu. To je užitečné ve scénářích, kdy je koncový bod během vývoje statický a dobře známý.

2. Přetížení s endpointSelector:

   Tato verze poskytuje dynamičtější chování tím, že umožňuje zadat zpětné volání (endpointSelector) k určení koncového bodu za běhu. To je užitečné, když se koncový bod může lišit v závislosti na stavu prostředku nebo jiných kontextových faktorech. Nabízí větší flexibilitu pro pokročilé scénáře, kdy koncový bod nejde pevně zakódovat.

Obě přetížení umožňují rozsáhlé přizpůsobení příkazu HTTP tím, že poskytují podtřídu typu HttpCommandOptions, včetně specifikace metody HTTP, konfigurace požadavku, zpracování odpovědi a definování vlastností souvisejících s uživatelským rozhraním, jako je zobrazovaný název, popis a ikony. Volba mezi těmito dvěma položkami závisí na tom, jestli je koncový bod v případě použití statický nebo dynamický.

Tato rozhraní API jsou navržená tak, aby se bezproblémově integrovali s Aspire ekosystémem, což vývojářům umožňuje rozšířit funkce prostředků s minimálním úsilím a současně udržovat kontrolu nad chováním a prezentací příkazů.

Důležité informace o registraci příkazů HTTP

Vzhledem k tomu, že příkazy HTTP jsou zpřístupněny prostřednictvím koncových bodů HTTP, zvažte potenciální rizika zabezpečení. Pokud je to možné, omezte tyto koncové body na vývojová nebo přípravná prostředí. Vždy ověřte příchozí požadavky, abyste měli jistotu, že pocházejí z důvěryhodných zdrojů. Další informace najdete v tématu ASP.NET Core zabezpečení.

Použijte HttpCommandOptions.PrepareRequest zpětné volání k vylepšení zabezpečení přidáním ověřovacích hlaviček nebo jiných opatření. Běžným přístupem je použití sdíleného tajného klíče, externího parametru nebo tokenu známého pouze pro AppHost a prostředek. Tuto sdílenou hodnotu lze použít k ověření požadavků a zabránění neoprávněnému přístupu.

Přidání vlastního příkazu HTTP

Do souboru AppHost.cs přidáte vlastní příkaz HTTP pomocí WithHttpCommand rozhraní API, kde IResourceBuilder<T> je TIResourceWithEndpoints. Tady je příklad postupu:

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();

Předchozí kód:

• Vytvoří nového tvůrce distribuovaných aplikací.
• Redis Přidá do aplikace mezipaměť s názvemcache.
• Přidá do aplikace parametr s názvem ApiCacheInvalidationKey . Tento parametr je označený jako tajný kód, což znamená, že se s jeho hodnotou bezpečně zachází.
• Přidá projekt pojmenovaný AspireApp_Api do aplikace.
• Přidá do mezipaměti odkaz Redis a před pokračováním počká, až bude připraven.
• Nakonfiguruje příkaz HTTP pro projekt následujícím kódem:
  • path: Určuje cestu URL pro příkaz HTTP (/cache/invalidate).
  • displayName: Nastaví název příkazu, který se zobrazí v uživatelském rozhraní (Invalidate cache).
  • commandOptions: Volitelná instance HttpCommandOptions , která konfiguruje chování a vzhled příkazu v uživatelském rozhraní:
    • Description: Poskytuje popis příkazu, který se zobrazuje v uživatelském rozhraní.
    • PrepareRequest: Funkce zpětného volání, která před odesláním nakonfiguruje požadavek HTTP. V tomto případě přidá vlastní hlavičku (X-CacheInvalidation-Key) s hodnotou parametru ApiCacheInvalidationKey .
    • IconName: Určuje ikonu, která se má použít pro příkaz v uživatelském rozhraní (DocumentLightningFilled).
    • IsHighlighted: Určuje, jestli má být příkaz zvýrazněný v uživatelském rozhraní.
• Nakonec se aplikace sestaví a spustí.

Koncový bod HTTP zodpovídá za zneplatnění mezipaměti. Při spuštění příkazu odešle požadavek HTTP na zadanou cestu (/cache/invalidate) s nakonfigurovanými parametry. Vzhledem k tomu, že existuje přidaná bezpečnostní míra, požadavek obsahuje hlavičku X-CacheInvalidation-Key s hodnotou parametru ApiCacheInvalidationKey . Tím se zajistí, že proces zneplatnění mezipaměti mohou spustit pouze autorizované požadavky.

Příklad koncového bodu HTTP

Předchozí fragment kódu AppHost definoval vlastní příkaz HTTP, který odešle požadavek do koncového /cache/invalidate bodu. Minimální ASP.NET Core projekt rozhraní API definuje koncový bod HTTP, který zpracovává požadavek na zneplatnění mezipaměti. Podívejte se na následující fragment kódu ze souboru 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();
});

Předchozí kód:

• Předpokládá, že app proměnná je instancí IApplicationBuilder a je nastavena pro zpracování požadavků HTTP.
• Mapuje koncový bod HTTP POST na cestě /cache/invalidate.
• Koncový bod očekává, že v požadavku bude hlavička s názvem X-CacheInvalidation-Key .
• Načte hodnotu parametru ApiCacheInvalidationKey z konfigurace.
• Pokud hodnota hlavičky neodpovídá očekávanému klíči, vrátí neautorizovanou odpověď.
• Pokud je záhlaví platné, volá metodu ClearAllAsyncICacheService pro vymazání všech položek uložených v mezipaměti.
• Nakonec vrátí odpověď HTTP OK.

Ukázkové zážitky z řídicího panelu

Ukázkový AppHost a odpovídající ASP.NET Core minimální projekty rozhraní API demonstrují obě strany implementace příkazu HTTP. Když spustíte AppHost, stránka Prostředky řídicího panelu zobrazí vlastní příkaz HTTP jako tlačítko. Když zadáte, že má být příkaz zvýrazněný (isHighlighted: true), zobrazí se tlačítko ve sloupci Akce na stránce Zdroje . To umožňuje uživatelům snadno aktivovat příkaz z řídicího panelu, jak je znázorněno na následujícím snímku obrazovky:

Pokud vynecháte parametr isHighlighted nebo ho nastavíte na false, zobrazí se příkaz jako součást nabídky ve formě tří vodorovných teček ve sloupci Akce na stránce Prostředky. To umožňuje uživatelům přístup k příkazu bez nepotřebných uživatelských rozhraní s příliš mnoha tlačítky. Následující snímek obrazovky ukazuje stejný příkaz, který se nachází v poznámkovém menu.

Když uživatel tlačítko vybere, spustí se příkaz a požadavek HTTP se odešle do zadaného koncového bodu. Řídicí panel poskytuje zpětnou vazbu ke stavu spuštění příkazu, což uživatelům umožňuje sledovat výsledky. Při spuštění se zobrazí informační zpráva:

Po dokončení příkazu řídicí panel aktualizuje stav a poskytne zpětnou vazbu o tom, jestli byl úspěšný nebo neúspěšný. Následující snímek obrazovky ukazuje úspěšné provedení příkazu:

Viz také

• Aspire Přehled orchestrace
• Vlastní příkazy zdrojů v Aspire
• Aspire GitHub úložiště: Ukázka hřiště