Háttérrendszerek az API Managementben

Minden API-kezelési szintre vonatkozik

Az API Management háttérrendszere (vagy API háttérrendszere) egy HTTP-szolgáltatás, amely implementálja az ön kliensoldali API-ját és annak műveleteit.

Bizonyos API-k importálásakor az API Management automatikusan konfigurálja az API-háttérrendszert. Az API Management például a háttér webszolgáltatást konfigurálja importáláskor:

Más API-k, például az Azure-szolgáltatásokBÓL származó API-k esetében a háttérszolgáltatás explicit megadása nélkül importálhat Egy Azure-erőforrást. Ide sorolhatóak például a következők:

Az API Management más erőforrások API-háttérrendszerként való használatát is támogatja, például:

Ezekhez a háttérrendszerekhez létrehozhat egy háttérentitást az API Managementben, és hivatkozhat rá az API-kban.

A háttérrendszer előnyei

Az API Management támogatja a háttérbeli entitásokat, így kezelheti az API háttérszolgáltatásait. A háttérentitások információkat foglalnak össze a háttérszolgáltatásról, amely elősegíti az API-k újrafelhasználhatóságát, és javítja a szabályozást.

Használjon háttérrendszereket az alábbi feladatok közül egy vagy többhez:

  • Engedélyezze a háttérszolgáltatásnak küldött kérések hitelesítő adatait.
  • Használja ki az API Management funkcióit az Azure Key Vault titkos kulcsainak karbantartásához, ha a névvel ellátott értékek a fejléc- vagy lekérdezésparaméter-hitelesítéshez vannak konfigurálva.
  • A háttérrendszer túl sok kéréstől való védelméhez definiáljon megszakító szabályokat.
  • A kérelmek átirányítása vagy terheléselosztása több háttérrendszernek.

A háttérentitások konfigurálhatók és kezelhetők az Azure Portalon, vagy Azure API-k vagy eszközök használatával.

Háttérrendszer létrehozása

Létrehozhat háttérrendszert az Azure Portalon, vagy Azure API-k vagy eszközök használatával.

Megjegyzés:

Ha bizonyos API-kat, például API-kat a Microsoft Foundryből vagy más AI-szolgáltatásokból importál, az API Management automatikusan konfigurál egy háttérentitást.

Háttérrendszer létrehozása a portálon:

  1. Jelentkezzen be a portálra , és nyissa meg az API Management-példányt.
  2. A bal oldali menüben válassza az API-k>háttérrendszerei>+ Új háttér létrehozása lehetőséget.
  3. A Háttéroldalon hajtsa végre a következő lépéseket:
    1. Adja meg a háttérrendszer nevét és az opcionális leírást.
    2. Válasszon egy háttérbeli üzemeltetési típust, például Azure-erőforrást egy Azure-erőforráshoz , például egy függvényalkalmazáshoz vagy logikai alkalmazáshoz, egyéni szolgáltatás egyéni URL-címét vagy Service Fabric-fürtöt .
    3. A Futtatókörnyezet URL-címében adja meg annak a háttérszolgáltatásnak az URL-címét, amelybe az API-kérések továbbításra kerülnek.
    4. A Speciális területen tiltsa le a háttérrendszer tanúsítványláncának vagy tanúsítványnevének érvényesítését.
    5. Az Add this backend service to a backend pool (Háttérszolgáltatás hozzáadása háttérkészlethez) területen válasszon vagy hozzon létre egy terheléselosztásos készletet a háttérrendszerhez.
    6. Az Áramkör-megszakító szabály alatt opcionálisan konfiguráljon egy áramkör-megszakítót a háttérrendszerhez.
    7. Az Engedélyezési hitelesítő adatok területen igény szerint konfigurálja a hitelesítő adatokat a háttérrendszerhez való hozzáférés engedélyezéséhez. A lehetőségek közé tartozik a kérelem fejléce, a lekérdezési paraméter, az ügyféltanúsítvány vagy az API Management-példányban konfigurált rendszer által hozzárendelt vagy felhasználó által hozzárendelt felügyelt identitás .
    8. Válassza a Create gombot.

A háttérrendszer létrehozása után bármikor frissítheti a háttérbeállításokat. Hozzáadhat például egy megszakító szabályt, módosíthatja a futtatókörnyezet URL-címét, vagy hitelesítő adatokat adhat hozzá.

Felügyelt identitás konfigurálása az engedélyezési hitelesítő adatokhoz

Az API Management-példányban konfigurált rendszer által hozzárendelt vagy felhasználó által hozzárendelt felügyelt identitással engedélyezheti a háttérszolgáltatáshoz való hozzáférést. Az alábbi lépésekkel konfigurálja a felügyelt identitást hozzáférési hitelesítő adatokhoz:

  1. A háttérkonfiguráció Engedélyezési hitelesítő adatai szakaszában válassza a Felügyelt identitás lapfület, és válassza az Engedélyezés lehetőséget.

  2. Az ügyfélidentitás részben válassza ki a kifejezetten a rendszer által hozzárendelt identitást vagy az Ön példányában konfigurált felhasználói identitást.

  3. Az erőforrás-azonosítóban adjon meg egy cél Azure-szolgáltatást, vagy a háttérrendszert képviselő saját Microsoft Entra-alkalmazás alkalmazásazonosítóját. Írja be például az Azure OpenAI szolgáltatás nevét https://cognitiveservices.azure.com .

    További példákért tekintse meg a hitelesítés által kezelt identitás házirend referenciáját.

  4. Válassza a Create gombot.

Megjegyzés:

Emellett rendelje hozzá a felügyelt identitást a megfelelő engedélyekhez vagy egy RBAC-szerepkörhöz a háttérszolgáltatás eléréséhez. Ha például a háttérrendszer egy Azure OpenAI-szolgáltatás, rendelje hozzá a felügyelt identitást a Cognitive Services User szerepkörhöz.

Tanúsítványok konfigurálása hitelesítési adatokhoz

A háttérszolgáltatáshoz való átjáróhozzáférést biztonságossá teheti az ügyféltanúsítványokkal vagy egyéni hitelesítésszolgáltatói (CA-) tanúsítványokkal végzett kölcsönös TLS-hitelesítéssel.

Ügyféltanúsítvány konfigurálása

Ha a backend szolgáltatást egy jól ismert hitelesítésszolgáltató által kiadott tanúsítvánnyal védik, hozzáadhat egy ügyféltanúsítványt a háttérentitáshoz.

  1. Adja hozzá a tanúsítványt az API Management-példányhoz. Hivatkozhat egy Azure Key Vaultban felügyelt tanúsítványra, vagy feltölthet egy PFX-fájlt.
  2. A háttérkonfiguráció Engedélyezési hitelesítő adatai szakaszában válassza az Ügyféltanúsítványok lapot.
  3. A legördülő menüben válassza ki a használni kívánt ügyféltanúsítványt.
  4. Válassza a Create gombot.

Ca-tanúsítvány konfigurálása

Ha a háttérszolgáltatás egyéni hitelesítésszolgáltatói tanúsítványt használ, hivatkozhat az egyéni hitelesítésszolgáltatói tanúsítványra a háttérentitóban. Előfordulhat, hogy egyéni hitelesítésszolgáltatói tanúsítványt kell hozzáadnia a háttérszerver tanúsítványának bizalmának megteremtéséhez – például önaláírt tanúsítványokkal, nem megbízható gyökértanúsítványokkal vagy részleges tanúsítványláncokkal.

Megjegyzés:

Jelenleg csak a v2-szinteken lévő háttérentitásokban konfigurálhatja a hitelesítésszolgáltatói tanúsítvány adatait.

A hitelesítésszolgáltatói tanúsítvány részleteinek hozzáadásához kövesse az alábbi lépéseket:

  1. A háttérkonfiguráció engedélyezési hitelesítő adatai szakaszában válassza a hitelesítésszolgáltatói tanúsítványokat.
  2. Válassza a + CA tanúsítvány adatainak hozzáadása lehetőséget.
  3. A hitelesítésszolgáltatói tanúsítvány hozzáadása panelen válassza az alábbi lehetőségek egyikét:
    • Tanúsítvány ujjlenyomata – Adja meg egy egyéni hitelesítésszolgáltatói tanúsítvány kiállítói ujjlenyomatát (SHA-1, SHA-256 vagy SHA-512 kivonat).
    • Alany neve és a kiállító ujjlenyomata – A kiállító ujjlenyomata mellett adja meg az alany nevét (CN vagy a leveletanúsítvány köznapi neve), amely azonosítja az általa védett számítógépnevet (például api.contoso.com vagy *.contoso.com).
  4. Válassza a Hozzáadás lehetőséget.
  5. Válassza a Create gombot.

Képernyőkép a hitelesítésszolgáltatói tanúsítvány részleteinek konfigurálásáról egy háttérrendszerhez a portálon.

Megjegyzés:

Amikor egy egyéni hitelesítésszolgáltatói tanúsítvány részleteit konfigurálja a háttérentitóban, az API Management mindig ellenőrzi a tanúsítvány nevét és a tanúsítványláncot, függetlenül attól, hogy engedélyezi vagy letiltja-e az érvényesítési beállításokat a háttérrendszerben backendTlsProperties.

Jótanács

A CA-tanúsítvány részleteit programozott módon is konfigurálhatja az API Management REST API használatával. Állítsa be a backendTlsProperties a háttérentitásban.

Referencia háttérrendszer a set-backend-service szabályzat használatával

A háttérrendszer létrehozása után hivatkozzon a háttérazonosítóra (névre) az API-kban. set-backend-service A házirend használatával egy bejövő API-kérést irányíthat a háttérrendszerbe. Ha már konfigurált egy háttérbeli webszolgáltatást egy API-hoz, a set-backend-service szabályzattal átirányíthatja a kérést egy háttérentitásba. Például:

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

Megjegyzés:

Alternatív megoldásként használhatja a base-url-t. A formátum általában .https://backend.com/api Ne adjon hozzá perjelet a végére a helytelen konfigurációk elkerülése érdekében. A háttérrendszer és a base-url HTTP(S) végpontértékének általában egyeznie kell az előtér és a háttérrendszer közötti zökkenőmentes integráció érdekében. Az API Management példányok a háttérszolgáltatás nevét hozzáfűzik a base-url-hez.

A feltételes logikával a set-backend-service szabályzattal módosíthatja a tényleges backend rendszert a hely, a hívott átjáró vagy egyéb kifejezések alapján.

A következő szabályzat például egy másik háttérrendszerbe irányítja a forgalmat a hívott átjáró alapján:

<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/>

Jótanács

Az API Management automatikusan észleli és használja a háttérbeli entitásokat, amikor API-kéréseket fogad. Futtatókörnyezetben, ha van egy háttérentitás, amely megfelel egy háttérszolgáltatás URL-címének, amelybe az API Management kérést küld, a háttérentitást használja. Nem kell explicit módon használnia set-backend-service.

Áramkör-megszakító

Az API Management egy kapcsolatcsoport-megszakító tulajdonságot tesz elérhetővé a háttérerőforrásban, hogy megvédje a háttérszolgáltatást a túl sok kéréstől.

  • Az áramkör-megszakító tulajdonság olyan szabályokat határoz meg, amelyekkel a megszakítót át lehet rántani, például a hibaállapotok száma vagy százalékos aránya egy meghatározott időintervallumban, valamint a meghibásodásokat jelző állapotkódok tartománya.
  • Amikor az áramkör-megszakító kitér, az API Management egy meghatározott időre leállítja a kérések küldését a háttérszolgáltatásnak, és egy 503 Szolgáltatás nem érhető el választ ad vissza az ügyfélnek.
  • A beállított időtartam lejárta után az áramkör alaphelyzetbe áll, és a forgalom folytatódik a háttérrendszer irányába.

A háttér áramkör-megszakító az áramkör-megszakító minta implementálása, amely lehetővé teszi a háttérrendszer számára, hogy helyreálljon a túlterhelési helyzetekből. Az általános sebességkorlátozási és egyidejűség-korlátozási szabályokat úgy bővíti, hogy az API Management átjáró és a háttérszolgáltatások védelmét biztosítsa.

Megjegyzés:

  • A háttér-kapcsolatcsoport-megszakító jelenleg nem támogatott az API Management használati szintjén.
  • Az API Management-architektúra elosztott jellege miatt a megszakító lecsatolási szabályai hozzávetőlegesek. Az átjáró különböző példányai nem szinkronizálják és alkalmazzák az áramkör-megszakító szabályokat ugyanazon példány adatai alapján.
  • Jelenleg csak egy szabályt konfigurálhat egy háttér áramkör-megszakítóhoz.

Figyelmeztetés

Ha egy Azure OpenAI-szolgáltatást háttérrendszerként konfigurál, és a szolgáltatás túl sok kérést fogad, akkor válaszállapot-kódot 429 Too Many Requests és Retry-After fejlécet ad vissza, amely nagy lehet (például 1 nap). Az Azure OpenAI hátterével circuit breaker szabályokat implementálhat a 429 válaszok kezeléséhez és az Retry-After időintervallum elfogadásához.

példa

Az Azure portál, az API Management REST API, vagy Bicep- vagy ARM-sablon használatával konfigurálhat egy körmegszakítót egy háttérrendszerben. Az alábbi példában az API Management példányon belül, a myAPIM-ben található myBackend áramkörmegszakító akkor aktiválódik, ha egy órán belül három vagy több 5xx állapotkód kiszolgálóhibát jelez.

A példában szereplő áramköri megszakító 1 óra elteltével alaphelyzetbe áll. Retry-After Ha egy fejléc szerepel a válaszban, a megszakító elfogadja az értéket, és megvárja a megadott időt, mielőtt a kéréseket újra elküldené a háttérrendszernek.

  1. Az Azure Portalon nyissa meg az API Management-példányt.
  2. A bal oldali menüben válassza az API-k>háttérrendszere közül a sajátját>.
  3. A háttérlapon válassza a Beállítások>kapcsolatcsoport megszakító beállításai> lehetőséget.
  4. Az Új áramkör-megszakító létrehozása lapon konfigurálja a szabályt:
    • Szabály neve: Adja meg a szabály nevét, például a myBackend nevet.
    • Hibaszám: Adja meg a 3 értéket.
    • Hibaintervallum: Hagyja meg az alapértelmezett 1 órás értéket.
    • Hibaállapot-kódtartomány: Válassza az 500 –599-et.
    • Utazás időtartama: Hagyja meg az alapértelmezett 1 órás értéket.
    • Ellenőrizze az "Újrapróbálkozás után" fejlécet a HTTP-válaszban: Válassza az Igaz (Elfogadás) lehetőséget.

Terheléskiegyensúlyozott készlet

Az API Management támogatja a háttérkészleteket , ha több háttérrendszert szeretne implementálni egy API-hoz, és terheléselosztási kéréseket szeretne megvalósítani ezeken a háttérrendszereken. A készlet olyan háttérrendszerek gyűjteménye, amelyeket a szolgáltatás egyetlen entitásként kezel a terheléselosztáshoz.

Használjon háttérkészletet az olyan forgatókönyvekhez, mint a következő forgatókönyvek:

  • Terjessze a terhelést több háttérrendszerre, amelyek különálló háttérrendszer megszakítóival rendelkezhetnek.
  • Helyezze át a terhelést az egyik háttérrendszerről egy másikra a frissítéshez (kék-zöld üzembe helyezés).

Megjegyzés:

  • Legfeljebb 30 háttérrendszert vehet fel egy csoportba.
  • Az API Management-architektúra elosztott jellege miatt a háttérbeli terheléselosztás hozzávetőleges. Az átjáró különböző példányai nem szinkronizálódnak és terheléselosztást hajtanak létre ugyanazon példány adatai alapján.

Terheléselosztási beállítások

Az API Management a következő terheléselosztási beállításokat támogatja a háttérkészletekhez:

Terheléselosztási lehetőség Leírás
Körkörös A kérések alapértelmezés szerint egyenletesen oszlanak el a háttérrendszerek között a poolban.
súlyozott Rendeljen súlyokat a kapacitáskészlet háttérrendszereihez, és irányítsa a kéréseket az egyes háttérrendszerek relatív súlya alapján. Olyan helyzetekben hasznos, mint a kék-zöld telepítések.
Prioritásalapú Rendszerezze a háttérrendszereket prioritási csoportokba. Először a magasabb prioritású csoportoknak küldjön kéréseket; a csoporton belül egyenletesen vagy a hozzárendelt súlyok szerint osztja el a kéréseket.

Megjegyzés:

Az API Management szolgáltatás csak akkor használ háttérrendszereket alacsonyabb prioritású csoportokban, ha a magasabb prioritású csoportok összes háttérrendszere nem érhető el, mert az áramkör-megszakító szabályok meg vannak kapcsolva.

Munkamenet érzékelése

Az előző terheléselosztási beállítások bármelyikének használatával engedélyezheti a munkamenet-tudatosságot (munkamenet-affinitást), hogy egy adott felhasználótól érkező összes kérés a munkamenet során ugyanarra a háttérrendszerre kerüljön a készletben. Az API Management beállít egy munkamenet-azonosító cookie-t a munkamenet állapotának fenntartásához. Ez a lehetőség hasznos lehet például olyan háttérrendszerekkel rendelkező helyzetekben, mint például az AI-csevegősegédek vagy más beszélgetési ügynökök, hogy a kéréseket ugyanazon munkamenetből ugyanarra a végpontra irányítják.

Cookie-k kezelése a munkamenet-tudatosság érdekében

A munkamenet-tudatosság használatakor az ügyfélnek megfelelően kell kezelnie a cookie-kat. Az ügyfélnek tárolnia kell a Set-Cookie fejlécértéket, és el kell küldenie azt a munkamenet állapotának fenntartására irányuló későbbi kérésekkel.

Az API Management-szabályzatok segítségével cookie-kat állíthat be a munkamenet-tudatosság érdekében. Például az Assistants API (a Microsoft Foundry-modellekben az Azure OpenAI egyik funkciója) esetében az ügyfélnek meg kell őriznie a munkamenet-azonosítót, ki kell nyernie a szálazonosítót a törzsből, és meg kell tartania a párt, és minden híváshoz el kell küldenie a megfelelő cookie-t. Ezenkívül az ügyfélnek tudnia kell, hogy mikor küldjön cookie-t, vagy mikor ne küldjön cookie-fejlécet. Ezeket a követelményeket a következő példaszabályzatok meghatározásával lehet megfelelően kezelni:

<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>(preserveContent: true);
      var threadId = payload["id"];
      var gwSetCookieHeaderValue = context.Request.Headers.GetValueOrDefault("Set-Cookie", string.Empty);
      if(!string.IsNullOrEmpty(gwSetCookieHeaderValue))
          {
            gwSetCookieHeaderValue = gwSetCookieHeaderValue + $";Path=/threads/{threadId};";
          }
      return gwSetCookieHeaderValue;
    }" />
    <set-header name="Set-Cookie" exists-action="override">
        <value>@((string)context.Variables["gwSetCookie"])</value>
    </set-header>
  </outbound>
  <on-error>
    <base />
  </on-error>
</policies>

példa

A háttérkészlet konfigurálásához használja a portált, az API Management REST API-t vagy egy Bicep- vagy ARM-sablont. Az alábbi példában a myAPIM API Management-példányban lévő myBackendPool háttérkészletet konfigurálták. A példában szereplő háttérrendszerek a medencében a backend-1 és a backend-2 nevet viselik. Mindkét háttérrendszer a legmagasabb prioritású csoportban található; a csoporton belül az 1. háttérrendszer nagyobb súlyú, mint a backend-2.

  1. Az Azure Portalon nyissa meg az API Management-példányt.
  2. A bal oldali menüben válassza az API-k>háttérrendszere közül a sajátját>.
  3. A Háttérlapon válassza a Terheléselosztó lapot.
  4. Válassza + Új pool létrehozása.
  5. Az új terheléselosztott készlet létrehozása lapon adja meg a következő adatokat:
    • Név: Adjon nevet a készletnek, például a myBackendPoolnak.
    • Leírás: Igény szerint adjon meg egy leírást.
    • Háttérrendszer hozzáadása a készlethez: Jelöljön ki egy vagy több háttérrendszert, amely hozzáadható a készlethez.
    • Háttérsúly és prioritás: Válassza a Súly és prioritás testreszabása lehetőséget a készletben lévő háttérrendszer súlyának és prioritásának konfigurálásához. Ha például két háttérrendszert adott hozzá, a backend-1 és a backend-2 nevet, állítsa a háttérrendszer-1 súlyát 3-ra , a háttérrendszer-2 súlyát pedig 1-re , és állítsa mindkét háttérrendszer prioritását 1-re.
    • Válassza a Create gombot.

Context.Backend változó

Ha egy háttérentitást konfigurál az API Managementben, a context.Backend használatával elérheti a háttértulajdonságokat a szabályzatokban.

Az alábbi táblázat a változó tulajdonságait sorolja fel context.Backend .

Ingatlan Leírás
Id A háttérentitás erőforrás-azonosítója.
Type A háttérrendszer típusa: Single vagy Pool.
AzureRegion A háttérrégió, ha meg van adva.

példa

Az alábbi példa bemutatja, hogyan állíthat be egyéni fejlécet a backend típus megadásával egy bejövő házirendben.

<inbound>
  <base />
  <set-backend-service backend-id="my-backend" />
  <set-header name="X-Backend-Type" exists-action="override">
    <value>@(context.Backend?.Type ?? "n/a")</value>
  </set-header>
</inbound>

Korlátozások

Kapcsolódó tartalom

  • Last updated on