Sdílet prostřednictvím

Back-endy ve službě API Management

PLATÍ PRO: Všechny úrovně služby API Management

Back-end (nebo back-end rozhraní API) ve službě API Management je služba HTTP, která implementuje rozhraní API front-endu a jeho operace.

Při importu určitých rozhraní API služba API Management automaticky nakonfiguruje back-end rozhraní API. Služba API Management například při importu nakonfiguruje back-endovou webovou službu:

U jiných rozhraní API, jako jsou rozhraní API ze služeb Azure, importujete prostředek Azure bez explicitního zadání back-endové služby. Mezi příklady patří:

API Management také podporuje použití jiných prostředků jako back-end rozhraní API, například:

  • Cluster Service Fabric.
  • Služby AI
  • Vlastní služba

Pro tyto back-endy můžete vytvořit back-endovou entitu ve službě API Management a odkazovat na ni ve svých rozhraních API.

Výhody „back-endů“

API Management podporuje back-endové entity, abyste mohli spravovat back-endové služby vašeho rozhraní API. Back-endová entita zapouzdřuje informace o back-endové službě a podporuje opakované použití napříč rozhraními API a vylepšené zásady správného řízení.

Použijte back-endy pro jednu nebo více z následujících možností:

  • Autorizace přihlašovacích údajů žádostí k back-endové službě
  • Využijte funkce služby API Management k udržování tajných kódů ve službě Azure Key Vault, pokud jsou pojmenované hodnoty nakonfigurované pro ověřování hlavičky nebo parametru dotazu.
  • Definování pravidel jističe pro ochranu back-endu před příliš mnoha požadavky
  • Směrování nebo vyrovnávání zatížení požadavků na více back-endů

Konfigurace a správa back-endových entit na webu Azure Portal nebo pomocí rozhraní AZURE API nebo nástrojů

Vytvoření back-endu

Back-end můžete vytvořit na webu Azure Portal nebo pomocí rozhraní API nebo nástrojů Azure.

Poznámka:

Při importu určitých rozhraní API, jako jsou rozhraní API z Microsoft Foundry nebo jiných služeb AI, služba API Management automaticky nakonfiguruje back-endovou entitu.

Vytvoření back-endu na portálu:

  1. Přihlaste se k portálu a přejděte do instance služby API Management.
  2. V nabídce vlevo vyberte rozhraní API>Backendy>+ Vytvořit nový backend.
  3. Na stránce Back-endu proveďte následující kroky:
    1. Zadejte název back-endu a volitelný popis.
    2. Vyberte typ hostování back-endu, například prostředek Azure pro prostředek Azure, jako je aplikace funkcí nebo aplikace logiky, vlastní adresa URL pro vlastní službu nebo cluster Service Fabric .
    3. V adrese URL modulu runtime zadejte adresu URL back-endové služby, na kterou se předávají požadavky rozhraní API.
    4. V části Upřesnit volitelně zakažte pro back-end ověřování řetězu certifikátů nebo názvu certifikátu.
    5. V části Přidat tuto back-endovou službu do back-endového fondu volitelně vyberte nebo vytvořte fond s vyrovnáváním zatížení pro back-end .
    6. V části Pravidlo jističe volitelně nakonfigurujte jistič pro back-end.
    7. V části Přihlašovací údaje pro autorizaci volitelně nakonfigurujte přihlašovací údaje pro autorizaci přístupu k back-endu. Mezi možnosti patří hlavička požadavku, parametr dotazu, klientský certifikát nebo spravovaná identita přiřazená systémem nebo spravovaná identita přiřazená uživatelem nakonfigurovaná v instanci služby API Management.
    8. Vyberte Vytvořit.

Po vytvoření back-endu můžete nastavení back-endu kdykoli aktualizovat. Můžete například přidat pravidlo jističe, změnit adresu URL modulu runtime nebo přidat autorizační přihlašovací údaje.

Nastavení spravované identity pro autorizační přihlašovací údaje

K autorizaci přístupu k back-endové službě můžete použít spravovanou identitu přiřazenou systémem nebo spravovanou identitu přiřazenou uživatelem nakonfigurovanou v instanci služby API Management. Pokud chcete nakonfigurovat spravovanou identitu pro přihlašovací údaje autorizace, proveďte následující kroky:

  1. V části Přihlašovací údaje pro autorizaci v konfiguraci back-endu vyberte kartu Spravovaná identita a vyberte Povolit.

  2. V části Identita klienta vyberte identitu přiřazenou systémem nebo identitu přiřazenou uživatelem, kterou jste nakonfigurovali ve své instanci.

  3. V ID prostředku zadejte cílovou službu Azure nebo ID aplikace vlastní aplikace Microsoft Entra představující back-end. Zadejte například https://cognitiveservices.azure.com pro službu Azure OpenAI.

    Další příklady najdete v referenci zásad ověřování spravovaného identitou.

  4. Vyberte Vytvořit.

Poznámka:

Přiřaďte také spravovanou identitu příslušným oprávněním nebo roli RBAC pro přístup k back-endové službě. Pokud je zázemí například službou Azure OpenAI, přiřaďte spravované identitě roli Cognitive Services User.

Konfigurace certifikátů pro autorizační přihlašovací údaje

Přístup brány k back-endové službě můžete zabezpečit pomocí vzájemného ověřování TLS s klientskými certifikáty nebo vlastními certifikáty certifikační autority (CA).

Konfigurace klientského certifikátu

Pokud je back-endová služba zabezpečená pomocí certifikátu vydaného dobře známou certifikační autoritou, můžete do entity back-endu přidat klientský certifikát:

  1. Přidejte certifikát do instance služby API Management. Můžete odkazovat na certifikát spravovaný ve službě Azure Key Vault nebo nahrát soubor PFX.
  2. V části Přihlašovací údaje pro autorizaci v konfiguraci back-endu vyberte kartu Klientské certifikáty .
  3. V rozevíracím seznamu vyberte klientský certifikát, který chcete použít.
  4. Vyberte Vytvořit.

Konfigurace certifikátu certifikační autority

Pokud back-endová služba používá vlastní certifikát certifikační autority, můžete odkazovat na vlastní certifikát certifikační autority v entitě back-endu. Tento krok možná budete muset udělat, abyste vytvořili vztah důvěryhodnosti pro certifikát back-endového serveru – například s certifikáty podepsanými svým držitelem, nedůvěryhodnými kořenovými certifikáty nebo částečnými řetězy certifikátů.

Poznámka:

V současné době můžete v back-endové entitě ve vrstvách v2 nakonfigurovat pouze podrobnosti o certifikátu certifikační autority.

Pokud chcete přidat podrobnosti o certifikátu certifikační autority, postupujte takto:

  1. V části Přihlašovací údaje pro autorizaci v konfiguraci back-endu vyberte Certifikáty certifikační autority.
  2. Vyberte + Přidat podrobnosti certifikátu certifikační autority.
  3. V podokně Přidat certifikát certifikační autority vyberte jednu z následujících možností:
    • Kryptografický otisk certifikátu – Zadejte kryptografický otisk (SHA-1, SHA-256 nebo SHA-512) vlastního certifikátu certifikační autority.
    • Název subjektu a kryptografický otisk vystavitele – zadejte název subjektu, který jednoznačně identifikuje CA, a kryptografický otisk CA.
  4. Vyberte Přidat.
  5. Vyberte Vytvořit.

Snímek obrazovky s konfigurací podrobností certifikátu certifikační autority pro back-end na portálu

Poznámka:

Při konfiguraci podrobností vlastního certifikátu certifikační autority v back-endové entitě služba API Management vždy ověří název certifikátu a řetěz certifikátů bez ohledu na to, jestli povolíte nebo zakážete nastavení ověřování v back-endu backendTlsProperties.

Referenční backend pomocí politiky set-backend-service

Po vytvoření back-endu můžete v rozhraních API odkazovat na identifikátor back-endu (název). Použijte zásady set-backend-service k nasměrování příchozího požadavku rozhraní API na backend. Pokud jste už nakonfigurovali backendovou webovou službu pro rozhraní API, můžete tuto zásadu použít set-backend-service k přesměrování požadavku na entitu backend. Příklad:

<policies>
    <inbound>
        <base />
        <set-backend-service backend-id="myBackend" />
    </inbound>
    [...]
<policies/>

Poznámka:

Alternativně můžete použít base-url. Formát je https://backend.com/apiobvykle . Vyhněte se přidání lomítka na konci, aby nedošlo k nesprávné konfiguraci. Typická hodnota koncového bodu HTTP(S) v backendu by se měla shodovat, aby bylo možné bezproblémovou integraci mezi frontendem a backendem. Všimněte si, že instance služby API Management připojují název back-endové služby k objektu base-url.

Pomocí podmíněné logiky s set-backend-service politikou můžete změnit výsledný back-end na základě umístění, volané brány nebo jiných výrazů.

Tady je například pravidlo pro směrování provozu na jiný backend na základě volané brány.

<policies>
    <inbound>
        <base />
        <choose>
            <when condition="@(context.Deployment.Gateway.Id == "factory-gateway")">
                <set-backend-service backend-id="backend-on-prem" />
            </when>
            <when condition="@(context.Deployment.Gateway.IsManaged == false)">
                <set-backend-service backend-id="self-hosted-backend" />
            </when>
            <otherwise />
        </choose>
    </inbound>
    [...]
<policies/>

Návod

Služba API Management také automaticky detekuje a používá back-endové entity, když přijímá požadavky rozhraní API. Pokud za běhu existuje back-endová entita, která odpovídá adrese URL back-endové služby, do které služba API Management odesílá požadavek, použije entitu back-endu. Nemusíte explicitně používat set-backend-service.

Jistič

Platforma API Management zpřístupňuje vlastnost circuit breaker v backendovém prostředku, aby ochránila backendovou službu před zahlcením nadměrným počtem žádostí.

  • Vlastnost jističe definuje pravidla pro jízdu jističe, například počet nebo procento podmínek selhání během definovaného časového intervalu a rozsah stavových kódů, které označují chyby.
  • Když dojde k výpadku jističe, API Management přestane odesílat požadavky do back-endové služby po definovanou dobu a vrátí klientovi odpověď 503 Service Unavailable.
  • Po nakonfigurované době trvání jízdy se okruh resetuje a provoz se obnoví do back-endu.

Jistič back-endu je implementace modelu jističe, který umožňuje back-endu zotavit se z přetížených situací. Rozšiřuje obecné zásady omezování rychlosti a souběžnosti , které můžete implementovat za účelem ochrany brány služby API Management a back-endových služeb.

Poznámka:

  • Backendový jistič není v současné době podporován ve vrstvě Consumption služby API Management.
  • Vzhledem k distribuované povaze architektury služby API Management jsou pravidla aktivace jističe přibližná. Různé instance brány se nesynchronizují a aplikují pravidla jističe na základě informací o stejné instanci.
  • V současné době můžete pro jistič back-endu nakonfigurovat pouze jedno pravidlo.

Upozornění

Pokud nakonfigurujete službu Azure OpenAI jako back-end a služba obdrží příliš mnoho požadavků, vrátí 429 Too Many Requests stavový kód odpovědi a hlavičku Retry-After s hodnotou, která může být velká (například 1 den). Pomocí back-endů Azure OpenAI implementujte pravidla "circuit breaker" pro zpracování 429 odpovědí a přijetí Retry-After doby trvání.

Příklad

Ke konfiguraci jističe v backendu použijte portál Azure, rozhraní REST API služby API Management nebo šablonu Bicep nebo ARM. V následujícím příkladu jistič v myBackend v instanci správy API myAPIM vypne, když jsou během 1 hodiny tři nebo více stavových kódů naznačujících chyby serveru.

Jistič v tomto příkladu se resetuje po 1 hodině. Retry-After Pokud v odpovědi existuje hlavička, jistič přijme hodnotu a před opětovným odesláním požadavků do back-endu počká na zadaný čas.

  1. Na webu Azure Portal přejděte do vaší instance služby API Management.
  2. V nabídce vlevo vyberte rozhraní API>backendy> váš backend.
  3. Na stránce back-endu vyberte Nastavení>Nastavení jističe>Přidat nové.
  4. Na stránce Vytvořit nový jistič nakonfigurujte pravidlo:
    • Název pravidla: Zadejte název pravidla, například myBackend.
    • Počet selhání: Zadejte 3.
    • Interval selhání: Ponechte výchozí hodnotu 1 hodinu.
    • Rozsah stavového kódu selhání: Vyberte 500 až 599.
    • Doba trvání cesty: Ponechte výchozí hodnotu 1 hodinu.
    • Zkontrolujte hlavičku 'Retry-After' v odpovědi HTTP: Vyberte True (Accept).

Pool s vyrovnáváním zátěže

Služba API Management podporuje back-endové fondy , když chcete implementovat více back-endů pro rozhraní API a požadavky na vyrovnávání zatížení napříč těmito back-endy. Bazen je soubor zázemí, která jsou považována za jedinou entitu pro vyrovnávání zátěže.

Pro případy, jako jsou tyto, použijte backendový fond:

  • Rozdělte zatížení na několik back-endů, které můžou mít jednotlivé back-endové jističe.
  • Přesun zatížení z jedné sady backendů na jinou sadu pro upgrade (Modré Zelené nasazení).

Poznámka:

  • Do fondu můžete zahrnout až 30 backendů.
  • Vzhledem k distribuované povaze architektury služby API Management je vyrovnávání zatížení back-endu přibližné. Různé instance brány se nesynchronizují a nevyrovnávají zatížení na základě informací o stejné instanci.

Možnosti vyrovnávání zatížení

API Management podporuje následující možnosti vyrovnávání zatížení pro back-endové fondy:

Možnost vyrovnávání zatížení Popis
Kruhové dotazování Požadavky se ve výchozím nastavení distribuují rovnoměrně mezi backendy ve fondu.
Vážená Přiřaďte backendům ve fondu váhy a distribuujte požadavky na základě relativní váhy každého backendu. Užitečné pro scénáře, jako je modro-zelené nasazení.
Na základě priority Uspořádejte backendy do skupin podle priorit. Nejprve odešlete žádosti skupinám s vyšší prioritou; v rámci skupiny distribuujte žádosti rovnoměrně nebo podle přiřazených hmotností.

Poznámka:

Služba API Management používá backendy ve skupinách s nižší prioritou pouze tehdy, když jsou všechny backendy ve skupinách s vyšší prioritou nedostupné, protože pravidla jističe jsou aktivována.

Povědomí o sezeních

Pomocí některé z předchozích možností vyrovnávání zatížení můžete povolit rozpoznávání relací (spřažení relací), abyste zajistili, že všechny požadavky od konkrétního uživatele během relace přejdou do stejného back-endu ve fondu. Služba API Management nastaví soubor cookie ID relace pro zachování stavu relace. Tato možnost je užitečná například ve scénářích se systémy na pozadí, jako jsou AI chatovací asistenti nebo jiní konverzační agenti, aby žádosti ze stejné relace byly směrovány do stejného koncového bodu.

Poznámka:

Povědomí o relacích ve fondech s vyrovnáváním zatížení se vydává jako první do skupinyraných aktualizací služby AI Gateway.

Správa souborů cookie pro uvědomění o relacích

Když používáte správu relací, klient musí správně zpracovávat soubory cookie. Klient musí uložit Set-Cookie hodnotu hlavičky a odeslat ji s dalšími požadavky na zachování stavu relace.

Pomocí zásad služby API Management můžete nastavit soubory cookie pro správu relací. Například v případě rozhraní API Assistantů (funkce Azure OpenAI v modelech Microsoft Foundry) musí klient uchovat ID session, extrahovat ID vlákna z těla a zachovat dvojici a odeslat správný soubor cookie pro každé volání. Kromě toho klient potřebuje vědět, kdy odeslat soubor cookie nebo kdy neodesílat hlavičku cookie. Tyto požadavky je možné správně zpracovat definováním následujících ukázkových zásad:

<policies>
  <inbound>
    <base />
    <set-backend-service backend-id="APIMBackend" />
  </inbound>
  <backend>
    <base />
  </backend>
  <outbound>
    <base />
    <set-variable name="gwSetCookie" value="@{
      var payload = context.Response.Body.As<JObject>();
      var threadId = payload["id"];
      var gwSetCookieHeaderValue = context.Request.Headers.GetValueOrDefault("SetCookie", string.Empty);
      if(!string.IsNullOrEmpty(gwSetCookieHeaderValue))
      {
        gwSetCookieHeaderValue = gwSetCookieHeaderValue + $";Path=/threads/{threadId};";
      }
      return gwSetCookieHeaderValue;
    }" />
    <set-header name="Set-Cookie" exists-action="override">
      <value>Cookie=gwSetCookieHeaderValue</value>
    </set-header>
  </outbound>
  <on-error>
    <base />
  </on-error>
</policies>

Příklad

Ke konfiguraci backendového poolu použijte portál, rozhraní REST API služby API Management nebo šablonu Bicep nebo ARM. V následujícím příkladu je back-end myBackendPool v instanci služby API Management myAPIM nakonfigurovaný s back-endovým fondem. Ukázkové backendy ve fondu jsou pojmenovány backend-1 a backend-2. Oba back-endy jsou ve skupině s nejvyšší prioritou; back-end-1 má ve skupině větší váhu než back-end-2.

  1. Na webu Azure Portal přejděte do vaší instance služby API Management.
  2. V nabídce vlevo vyberte rozhraní API>backendy> váš backend.
  3. Na stránce Backendy vyberte kartu Vyrovnávání zátěže.
  4. Vyberte + Vytvořit nový fond.
  5. Na stránce Vytvořit nový fond s vyrovnáváním zatížení zadejte následující informace:
    • Název: Zadejte název fondu, například myBackendPool.
    • Popis: Volitelně zadejte popis.
    • Přidání back-endů do fondu: Vyberte jeden nebo více back-endů, které chcete přidat do fondu.
    • Váha a priorita backendu: Vyberte Přizpůsobit váhu a prioritu pro konfiguraci váhy a priority každého backendu ve fondu. Pokud jste například přidali dva back-endy s názvem back-end-1 a back-end-2, nastavte váhu back-endu-1 na 3 a váhu back-endu-2 na 1 a nastavte prioritu obou back-endů na 1.
    • Vyberte Vytvořit.

Omezení

Související obsah

  • Last updated on