Delen via

Achterkanten in API Management

VAN TOEPASSING OP: Alle API Management-niveaus

Een back-end (of API-back-end) in API Management is een HTTP-service waarmee uw front-end-API en de bijbehorende bewerkingen worden geïmplementeerd.

Bij het importeren van bepaalde API's configureert API Management de API-back-end automatisch. Api Management configureert bijvoorbeeld de back-endwebservice bij het importeren:

API Management biedt ook ondersteuning voor het gebruik van andere Azure-resources als API-back-end, zoals:

Voordelen van back-ends

API Management ondersteunt back-endentiteiten, zodat u de back-endservices van uw API kunt beheren. Een back-endentiteit encapsuleert informatie over de back-endservice, wat de herbruikbaarheid over API's heen en betere governance bevordert.

Gebruik back-ends voor een of meer van de volgende opties:

  • Autoriseer de bevoegdheden van aanvragen voor de back-endservice
  • Profiteer van API Management-functionaliteit voor het onderhouden van geheimen in Azure Key Vault als benoemde waarden zijn geconfigureerd voor verificatie van header- of queryparameters.
  • Regels voor circuitonderbrekers definiëren om uw back-end te beschermen tegen te veel aanvragen
  • Aanvragen routeren of verdelen naar meerdere backends

Back-endentiteiten configureren en beheren in Azure Portal of met behulp van Azure-API's of hulpprogramma's.

Een back-end maken

U kunt een back-end maken in Azure Portal of met behulp van Azure-API's of hulpprogramma's.

Een back-end maken in de portal:

  1. Meld u aan bij de portal en ga naar uw API Management-exemplaar.
  2. Selecteer in het linkermenu API's>Backends>+ Nieuwe backend maken.
  3. Ga als volgt te werk op de pagina Back-end :
    1. Voer een naam in voor de back-end en optionele beschrijving.
    2. Selecteer een hosttype voor back-end, bijvoorbeeld Azure-resource voor een Azure-resource, zoals een functie-app of logische app, aangepaste URL voor een aangepaste service of een Service Fabric-cluster .
    3. Voer in runtime-URL de URL in van de back-endservice waarnaar API-aanvragen worden doorgestuurd.
    4. Schakel onder Geavanceerd desgewenst validatie van certificaatketen of certificaatnaam uit voor de back-end.
    5. Onder Deze backendservice toevoegen aan een backendpool, selecteer of maak eventueel een load-balanced pool voor de backend.
    6. Configureer eventueel een circuitonderbreker voor de back-end onder circuitonderbrekerregel.
    7. Configureer onder Autorisatiereferenties optioneel referenties om toegang tot de back-end te autoriseren. Opties zijn onder andere een aanvraagheader, queryparameter, clientcertificaat of door het systeem toegewezen of door de gebruiker toegewezen beheerde identiteit die is geconfigureerd in het API Management-exemplaar.
    8. Klik op Creëren.

Nadat u een back-end hebt gemaakt, kunt u de back-endinstellingen op elk gewenst moment bijwerken. Voeg bijvoorbeeld een circuitonderbrekerregel toe, wijzig de runtime-URL of voeg autorisatiereferenties toe.

Beheerde identiteit configureren voor autorisatiereferenties

U kunt een door het systeem toegewezen of door de gebruiker toegewezen beheerde identiteit gebruiken die is geconfigureerd in het API Management-exemplaar om toegang tot de back-endservice te autoriseren. Ga als volgt te werk om een beheerde identiteit voor autorisatiereferenties te configureren:

  1. Selecteer in de sectie Autorisatiereferenties van de back-endconfiguratie het tabblad Beheerde identiteit en selecteer Inschakelen.

  2. Selecteer in clientidentiteit de door het systeem toegewezen identiteit of een door de gebruiker toegewezen identiteit die in uw exemplaar is geconfigureerd.

  3. Voer in Resource-id een Azure-doelservice of de toepassings-id in van uw eigen Microsoft Entra-toepassing die de back-end vertegenwoordigt. Voorbeeld: https://cognitiveservices.azure.com voor de Azure OpenAI-service.

    Zie de naslaginformatie over beleid voor beheerde identiteiten voor verificatie voor meer voorbeelden.

  4. Klik op Creëren.

Notitie

Wijs ook de beheerde identiteit de juiste machtigingen of een RBAC-rol toe voor toegang tot de back-endservice. Als de back-end bijvoorbeeld een Azure OpenAI-service is, kunt u de beheerde identiteit aan de Cognitive Services User rol toewijzen.

Verwijzen naar back-end met behulp van beleid voor set-backend-service

Nadat u een back-end hebt gemaakt, kunt u verwijzen naar de back-end-id (naam) in uw API's. Gebruik het set-backend-service beleid om een binnenkomende API-aanvraag naar de back-end te sturen. Als u al een back-end webservice voor een API hebt geconfigureerd, kunt u het set-backend-service-beleid gebruiken om het verzoek om te leiden naar een back-end-entiteit. Bijvoorbeeld:

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

Notitie

U kunt ook base-url gebruiken. Meestal is de indeling https://backend.com/api. Vermijd het toevoegen van een slash aan het einde om onjuiste configuraties te voorkomen. Normaal gesproken moeten de eindpuntwaarde en HTTP base-url (S) in de back-end overeenkomen om naadloze integratie tussen front-end en back-end mogelijk te maken. Houd er rekening mee dat API Management-exemplaren de naam van de back-endservice toevoegen aan de base-url.

U kunt voorwaardelijke logica met het set-backend-service beleid gebruiken om de effectieve back-end te wijzigen op basis van locatie, gateway die werd aangeroepen of andere expressies.

Hier volgt bijvoorbeeld een beleid voor het routeren van verkeer naar een andere back-end op basis van de gateway die werd aangeroepen:

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

Stroomonderbreker

API Management maakt een circuitonderbrekereigenschap beschikbaar in de back-endresource om een back-endservice te beschermen tegen te veel aanvragen.

  • De eigenschap voor de circuitonderbreker definieert regels om de circuitonderbreker te laten uitschakelen, zoals het aantal of percentage foutcondities binnen een bepaald tijdsinterval en een reeks statuscodes die fouten aangeven.
  • Wanneer de circuitonderbreker wordt geactiveerd, stopt API Management het verzenden van aanvragen naar de backendservice gedurende een gedefinieerde tijd en retourneert een 503 Service Unavailable-respons aan de client.
  • Na de geconfigureerde tripduur wordt het circuit opnieuw ingesteld en wordt het verkeer naar de backend hervat.

De circuitonderbreker van de back-end is een implementatie van het circuitonderbrekerpatroon , zodat de back-end kan herstellen uit overbelastingssituaties. Het versterkt algemene beleidsregels voor frequentiebeperking en beleidsregels voor gelijktijdigheidsbeperking, die u kunt implementeren om de API Management-gateway en uw back-endservices te beveiligen.

Notitie

  • Op dit moment wordt de circuitbreaker voor de backend niet ondersteund in de verbruikslaag van API Management.
  • Vanwege de gedistribueerde aard van de API Management-architectuur zijn de trippingregels voor circuitonderbrekers bij benadering. Verschillende exemplaren van de gateway worden niet gesynchroniseerd en passen stroomonderbrekerregels toe op basis van de informatie van hun eigen exemplaar.
  • Op dit moment kan slechts één regel worden geconfigureerd voor een back-end circuitonderbreker.

Voorbeeld

Gebruik de Azure-portal, API Management REST API of een Bicep- of ARM-sjabloon om een circuitonderbreker in een back-end te configureren. In het volgende voorbeeld wordt de stroomonderbreker in myBackend in het API Management-exemplaar myAPIM geactiveerd wanneer er drie of meer 5xx statuscodes zijn die serverfouten binnen 1 uur aangeven.

De circuitonderbreker in dit voorbeeld wordt na 1 uur opnieuw ingesteld. Als er een Retry-After header aanwezig is in het antwoord, accepteert de circuitonderbreker de waarde en wacht op de opgegeven tijd voordat aanvragen opnieuw naar de back-end worden verzonden.

  1. Ga in Azure Portal naar uw API Management-exemplaar.
  2. Selecteer API's> in het linkermenuback-ends> van uw back-end.
  3. Selecteer op de back-endpagina Instellingen>circuitonderbrekerinstellingen>Nieuwe toevoegen.
  4. Configureer de regel op de pagina Nieuwe circuitonderbreker maken :
    • Regelnaam: Voer een naam in voor de regel, zoals myBackend.
    • Aantal fouten: Voer 3 in.
    • Foutinterval: laat de standaardwaarde van 1 uur staan.
    • Foutstatuscodebereik: Selecteer 500 - 599.
    • Duur van reis: laat de standaardwaarde van 1 uur staan.
    • Controleer de 'Retry-After'-header in het HTTP-antwoord: Selecteer Waar (Accepteren).

Pool met gelijke taakverdeling

API Management ondersteunt back-endpools wanneer u meerdere back-ends voor een API wilt implementeren en aanvragen voor taakverdeling wilt verdelen over deze back-ends. Een pool is een verzameling back-ends die worden behandeld als één entiteit voor taakverdeling.

Gebruik een back-endpool voor scenario's zoals de volgende:

  • Spreid de belasting over meerdere backends, die mogelijk afzonderlijke back-endstroomonderbrekers hebben.
  • Verschuif de belasting van de ene set back-ends naar een andere voor de upgrade (blauwgroene implementatie).

Notitie

  • U kunt maximaal 30 backends opnemen in een pool.
  • Vanwege de gedistribueerde aard van de API Management-architectuur is back-endtaakverdeling bij benadering. Verschillende exemplaren van de gateway worden niet gesynchroniseerd en zullen belasting verdelen op basis van de informatie op dezelfde instantie.

Opties voor taakverdeling

API Management ondersteunt de volgende opties voor taakverdeling voor back-endpools:

Optie taakverdeling Beschrijving
Round robin Aanvragen worden standaard gelijkmatig verdeeld over de back-ends in de pool.
gewogen Gewichten worden toegewezen aan de back-ends in de pool en aanvragen worden gedistribueerd op basis van het relatieve gewicht van elke back-end. Handig voor scenario's zoals blauwgroene implementaties.
Op basis van prioriteit Back-ends zijn ingedeeld in prioriteitsgroepen. Aanvragen worden eerst verzonden naar groepen met een hogere prioriteit; binnen een groep worden aanvragen gelijkmatig verdeeld of volgens toegewezen gewichten.

Notitie

Backends in groepen met lagere prioriteit worden alleen gebruikt wanneer alle backends in groepen met hogere prioriteit niet beschikbaar zijn, omdat circuitonderbrekerregels geactiveerd zijn.

Sessiebewustzijn

Met een van de voorgaande opties voor taakverdeling kunt u eventueel sessiebewustzijn (sessieaffiniteit) inschakelen om ervoor te zorgen dat alle aanvragen van een specifieke gebruiker tijdens een sessie worden doorgestuurd naar dezelfde back-end in de pool. API Management stelt een sessie-id-cookie in om de sessiestatus te behouden. Deze optie is bijvoorbeeld handig in scenario's met back-ends zoals AI-chatassistenten of andere gespreksagenten om aanvragen van dezelfde sessie naar hetzelfde eindpunt te routeren.

Notitie

Sessiebewustzijn in groepen met gelijke taakverdeling wordt eerst vrijgegeven aan de groep Vroegeupdates van AI Gateway.

Cookies beheren voor sessiebewustzijn

Bij het gebruik van sessiebewustzijn moet de client cookies op de juiste wijze afhandelen. De client moet de Set-Cookie headerwaarde opslaan en verzenden met volgende aanvragen om de sessiestatus te behouden.

U kunt API Management-beleid gebruiken om cookies in te stellen voor sessiebewustzijn. Voor het geval van de Assistent-API (een functie van Azure OpenAI in Azure AI Foundry-modellen) moet de client bijvoorbeeld de sessie-id behouden, de thread-id uit de hoofdtekst extraheren en het paar behouden en de juiste cookie verzenden voor elke aanroep. Bovendien moet de client weten wanneer een cookie moet worden verzonden of wanneer er geen cookieheader moet worden verzonden. Deze vereisten kunnen op de juiste wijze worden afgehandeld door het volgende voorbeeldbeleid te definiëren:

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

Voorbeeld

Gebruik de portal, API Management REST API of een Bicep- of ARM-sjabloon om een back-endpool te configureren. In het volgende voorbeeld is de back-end myBackendPool in het API Management-exemplaar myAPIM geconfigureerd met een back-endpool. Voorbeelden van back-ends in de pool hebben de naam backend-1 en backend-2. Beide back-ends bevinden zich in de groep met de hoogste prioriteit; binnen de groep heeft back-end-1 een groter gewicht dan back-end-2.

  1. Ga in Azure Portal naar uw API Management-exemplaar.
  2. Selecteer API's> in het linkermenuback-ends> van uw back-end.
  3. Selecteer op de pagina Back-ends het tabblad Load balancer .
  4. Selecteer + Nieuwe pool maken.
  5. Ga als volgt te werk op de pagina Nieuwe pool met gelijke taakverdeling maken:
    • Naam: Voer een naam in voor de pool, zoals myBackendPool.
    • Beschrijving: Voer desgewenst een beschrijving in.
    • Back-ends toevoegen aan pool: selecteer een of meer back-ends die u aan de pool wilt toevoegen.
    • Back-endgewicht en -prioriteit: selecteer Gewicht en prioriteit aanpassen om het gewicht en de prioriteit van elke back-end in de pool te configureren. Als u bijvoorbeeld twee back-ends met de naam back-end-1 en back-end-2 hebt toegevoegd, stelt u het gewicht van back-end-1 in op 3 en het gewicht van back-end-2 op 1 en stelt u de prioriteit van beide back-ends in op 1.
    • Klik op Creëren.

Beperkingen

  • Voor ontwikkelaars - en Premium-lagen kan een API Management-exemplaar dat is geïmplementeerd in een intern virtueel netwerk HTTP 500-fouten BackendConnectionFailure veroorzaken wanneer de URL van het gatewayeindpunt en de back-end-URL hetzelfde zijn. Als u deze beperking ondervindt, volgt u de instructies in het artikel over de beperking van selfchained API Management-aanvragen in de interne virtuele netwerkmodus in de Tech Community-blog.
  • Op dit moment kan slechts één regel worden geconfigureerd voor een back-end circuitonderbreker.

Gerelateerde inhoud