Megosztás a következőn keresztül:

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:

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

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, elősegítve az API-k újrafelhasználhatóságát és a továbbfejlesztett szabályozást.

Használjon háttérrendszereket az alábbiak közül egyhez vagy többhez:

  • A háttérszolgáltatás felé irányuló kérések hitelesítő adatainak engedélyezése
  • 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.
  • Áramkör-megszakító szabályok definiálása a háttérrendszer túl sok kéréstől való védelmére
  • Kérelmek átirányítása vagy terheléselosztása több háttérrendszernek

Háttérbeli entitások konfigurálása és kezelése 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.

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 tegye a következőket:
    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 függvényalkalmazáshoz vagy logikai alkalmazáshoz, egyéni szolgáltatáshoz tartozó egyéni URL-címet 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 kapcsolatcsoport-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. A kezelt identitás engedélyezési hitelesítő adatokhoz való konfigurálásához tegye a következőket:

  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élazonosságnál válassza ki a rendszer által hozzárendelt identitást vagy a példányban konfigurált, felhasználó által hozzárendelt 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. Példa: https://cognitiveservices.azure.com Az Azure OpenAI szolgáltatáshoz.

    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, hozzárendelheti a felügyelt identitást a Cognitive Services User szerepkörhöz.

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

A háttérrendszer létrehozása után hivatkozhat 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áshoz. 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. Vegye figyelembe, hogy az API Management-példányok hozzáfűzik a háttérszolgáltatás nevét a base-url.

A feltételes logikát használhatja a set-backend-service szabályzattal a hatékony háttérrendszer módosítására a hely, a megadott átjáró vagy egyéb kifejezések alapján.

Itt látható például egy szabályzat, amely átirányítja a forgalmat egy másik háttérrendszerbe 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/>

Á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álódnak, és az ugyanazon példányra vonatkozó információk alapján alkalmazzák az áramkör-megszakító szabályokat.
  • Jelenleg csak egy szabály konfigurálható egy háttérkapcsolat-megszakító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 végrehajtani ezeken a háttérrendszereken. A készlet olyan háttérrendszerek gyűjteménye, amelyeket a rendszer egyetlen entitásként kezel a terheléselosztáshoz.

Használjon háttérkészletet a következő forgatókönyvekhez:

  • Terjessze a terhelést több háttérrendszerre, amelyek különálló védelmi megszakítókkal rendelkezhetnek.
  • Helyezze át a terhelést az egyik háttérrendszerről a 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 végeznek 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 A súlyok a készlet háttérrendszereihez vannak rendelve, a kérések pedig az egyes háttérrendszerek relatív súlya alapján vannak elosztva. Olyan helyzetekben hasznos, mint a kék-zöld telepítések.
Prioritásalapú A háttérrendszerek prioritási csoportokba vannak rendezve. A kéréseket a rendszer először magasabb prioritású csoportoknak küldi el; csoporton belül a kérelmek egyenletesen vagy a hozzárendelt súlyok szerint oszlanak meg.

Megjegyzés:

Az alacsonyabb prioritású csoportok háttérrendszerei csak akkor lesznek használhatók, ha a magasabb prioritású csoportok összes háttérrendszere nem érhető el, mert az áramkör-megszakító szabályai meg vannak kapcsolva.

Munkamenet érzékelése

Az előző terheléselosztási beállítások bármelyikével engedélyezheti a munkamenet-tudatosságot (munkamenet-affinitást), hogy a munkamenet során egy adott felhasználótól érkező összes kérés ugyanarra a háttérrendszerre legyen irányítva 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.

Megjegyzés:

A terheléselosztásos készletek munkamenet-tudatossága először az AI Gateway koraifrissítési csoportjában jelenik meg.

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 esetében (az Azure OpenAI az Azure AI Foundry-modellekben) az ügyfélnek meg kell őriznie a munkamenet-azonosítót, ki kell nyernie a szálazonosítót a törzsből, majd tartania kell a párosítást, é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>();
      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é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. A terhelés-kiegyenlített tárház létrehozása lapon kövesse a következő lépéseket:
    • 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.

Korlátozások

Kapcsolódó tartalom