Teilen über

Backends im API Management

GILT FÜR: Alle API Management-Ebenen

Ein Back-End (oder API-Back-End) in API Management ist ein HTTP-Dienst, der Ihre Front-End-API und die zugehörigen Vorgänge implementiert.

Wenn Sie bestimmte APIs importieren, konfiguriert die API-Verwaltung automatisch das API-Back-End. Beispielsweise konfiguriert API Management den Back-End-Webdienst, wenn Folgendes importiert wird:

Bei anderen APIs, z. B. APIs aus Azure-Diensten, importieren Sie eine Azure-Ressource, ohne den Back-End-Dienst explizit anzugeben. Beispiele sind:

Die API-Verwaltung unterstützt auch die Verwendung anderer Ressourcen als API-Back-End, z. B.:

Für diese Back-Ends können Sie eine Back-End-Entität in der API-Verwaltung erstellen und in Ihren APIs darauf verweisen.

Vorteile von Backends

API Management unterstützt Back-End-Entitäten, damit Sie die Back-End-Dienste Ihrer API verwalten können. Eine Back-End-Entität fasst Informationen über den Back-End-Dienst zusammen, fördert die API-übergreifende Wiederverwendbarkeit und verbessert die Governance.

Verwenden Sie Back-Ends für einen oder mehrere der folgenden Zwecke:

  • Die Anmeldeinformationen der Anfragen an den Back-End-Dienst autorisieren.
  • Nutzen sie die API-Verwaltungsfunktionen, um geheime Schlüssel in Azure Key Vault zu verwalten, wenn benannte Werte für die Header- oder Abfrageparameterauthentifizierung konfiguriert sind
  • Definieren Sie Circuit-Breaker-Regeln, um Ihr Backend vor zu vielen Anforderungen zu schützen.
  • Weiterleitung oder Lastenausgleich für Anforderungen mit mehreren Back-Ends

Konfigurieren und Verwalten von Back-End-Entitäten im Azure-Portal oder mithilfe von Azure-APIs oder -Tools.

Backend erstellen

Sie können ein Back-End im Azure-Portal oder mithilfe von Azure-APIs oder -Tools erstellen.

Hinweis

Wenn Sie bestimmte APIs wie APIs aus Microsoft Foundry oder anderen AI-Diensten importieren, konfiguriert die API-Verwaltung automatisch eine Back-End-Entität.

So erstellen Sie ein Back-End im Portal:

  1. Melden Sie sich beim Portal an, und wechseln Sie zu Ihrer API-Verwaltungsinstanz.
  2. Wählen Sie im linken Menü APIs>Back-Ends>+ Neues Back-End erstellen aus.
  3. Führen Sie auf der Back-End-Seite die folgenden Schritte aus:
    1. Geben Sie einen Namen für das Back-End und optionale Beschreibung ein.
    2. Wählen Sie einen Back-End-Hostingtyp aus, z. B. Azure-Ressource für eine Azure-Ressource wie eine Funktions-App oder Logik-App, benutzerdefinierte URL für einen benutzerdefinierten Dienst oder einen Service Fabric-Cluster .
    3. Geben Sie in der Laufzeit-URL die URL des Back-End-Diensts ein, an den API-Anforderungen weitergeleitet werden.
    4. Deaktivieren Sie unter "Erweitert" optional die Zertifikatkette oder die Zertifikatnamenüberprüfung für das Back-End.
    5. Unter „Diesen Back-End-Dienst zu einem Back-End-Pool hinzufügen“ können Sie optional einen Lastenausgleichspool für das Back-End auswählen oder erstellen.
    6. Konfigurieren Sie optional unter "Schaltkreisbrecherregel" einen Schaltkreisschalter für das Back-End.
    7. Konfigurieren Sie unter Autorisierungsanmeldeinformationen optional Anmeldeinformationen, um den Zugriff auf das Back-End zu autorisieren. Zu den Optionen gehören ein Anforderungsheader, ein Abfrageparameter, ein Clientzertifikat oder eine vom System zugewiesene oder vom Benutzer zugewiesene verwaltete Identität , die in der API-Verwaltungsinstanz konfiguriert ist.
    8. Klicken Sie auf Erstellen.

Nach dem Erstellen eines Back-End können Sie die Back-End-Einstellungen jederzeit aktualisieren. Sie können z. B. eine Schaltkreistrennregel hinzufügen, die Laufzeit-URL ändern oder Autorisierungsanmeldeinformationen hinzufügen.

Konfigurieren der verwalteten Identität für Autorisierungsanmeldeinformationen

Sie können eine vom System zugewiesene oder vom Benutzer zugewiesene verwaltete Identität verwenden, die in der API-Verwaltungsinstanz konfiguriert ist, um den Zugriff auf den Back-End-Dienst zu autorisieren. Führen Sie die folgenden Schritte aus, um eine verwaltete Identität für Autorisierungsanmeldeinformationen zu konfigurieren:

  1. Wählen Sie im Abschnitt "Autorisierungsanmeldeinformationen " der Back-End-Konfiguration die Registerkarte "Verwaltete Identität " und dann "Aktivieren" aus.

  2. Wählen Sie in der Clientidentität entweder die vom System zugewiesene Identität oder eine vom Benutzer zugewiesene Identität aus, die Sie in Ihrer Instanz konfiguriert haben.

  3. Geben Sie in der Ressourcen-ID einen Azure-Zieldienst oder die Anwendungs-ID Ihrer eigenen Microsoft Entra-Anwendung ein, die das Back-End darstellt. Geben Sie zum Beispiel https://cognitiveservices.azure.com für den Azure OpenAI-Dienst ein.

    Weitere Beispiele finden Sie in der Richtlinienreferenz Authentifizierungsverwaltete Identität.

  4. Klicken Sie auf Erstellen.

Hinweis

Weisen Sie auch der verwalteten Identität die entsprechenden Berechtigungen oder eine RBAC-Rolle zu, um auf den Back-End-Dienst zuzugreifen. Wenn das Back-End beispielsweise ein Azure OpenAI-Dienst ist, weisen Sie die verwaltete Identität der Cognitive Services User Rolle zu.

Konfigurieren von Zertifikaten für Berechtigungsnachweise

Sie können den Gatewayzugriff auf den Back-End-Dienst sichern, indem Sie die gegenseitige TLS-Authentifizierung mit Clientzertifikaten oder zertifikaten einer benutzerdefinierten Zertifizierungsstelle verwenden.

Konfigurieren des Clientzertifikats

Wenn der Back-End-Dienst mit einem Zertifikat gesichert ist, das von einer bekannten Zertifizierungsstelle ausgestellt wurde, können Sie ein Clientzertifikat in der Back-End-Entität hinzufügen:

  1. Fügen Sie das Zertifikat zur API-Verwaltungsinstanz hinzu. Sie können auf ein Zertifikat verweisen, das in Azure Key Vault verwaltet wird, oder eine PFX-Datei hochladen.
  2. Wählen Sie im Abschnitt "Autorisierungsanmeldeinformationen " der Back-End-Konfiguration die Registerkarte "Clientzertifikate " aus.
  3. Wählen Sie in der Dropdownliste das Clientzertifikat aus, das Sie verwenden möchten.
  4. Klicken Sie auf Erstellen.

Konfiguration des Zertifizierungsstellenzertifikats

Wenn der Back-End-Dienst ein benutzerdefiniertes Zertifizierungsstellenzertifikat verwendet, können Sie auf das benutzerdefinierte Zertifizierungsstellenzertifikat in der Back-End-Entität verweisen. Möglicherweise müssen Sie diesen Schritt ausführen, um eine Vertrauensstellung für das Back-End-Serverzertifikat einzurichten , z. B. mit selbstsignierten Zertifikaten, nicht vertrauenswürdigen Stammzertifikaten oder teilweisen Zertifikatketten.

Hinweis

Derzeit können Sie nur Details zum Zertifizierungsstellenzertifikat in einer Back-End-Entität in den v2-Ebenen konfigurieren.

Führen Sie die folgenden Schritte aus, um Details zum CA-Zertifikat hinzuzufügen:

  1. Wählen Sie im Abschnitt Autorisierungsanmeldeinformationen der Backend-Konfiguration CA-Zertifikate aus.
  2. Wählen Sie +Ca-Zertifikatdetails hinzufügen.
  3. Wählen Sie im Bereich " Zertifizierungsstelle hinzufügen " eine der folgenden Optionen aus:
    • Zertifikatfingerabdruck – Geben Sie den Fingerabdruck (SHA-1, SHA-256 oder SHA-512 Hash) eines benutzerdefinierten CA-Zertifikats ein.
    • Antragstellername und Ausstellerfingerabdruck – Geben Sie den Antragstellernamen ein, der die Zertifizierungsstelle und den Fingerabdruck der Zertifizierungsstelle eindeutig identifiziert.
  4. Wählen Sie Hinzufügen aus.
  5. Klicken Sie auf Erstellen.

Screenshot der Konfiguration von CA-Zertifikatsdetails für ein Backend im Portal.

Hinweis

Wenn Sie Details eines benutzerdefinierten Zertifizierungsstellenzertifikats in der Back-End-Entität konfigurieren, überprüft API-Verwaltung immer den Zertifikatnamen und die Zertifikatkette, unabhängig davon, ob Sie validierungseinstellungen im Back-End backendTlsPropertiesaktivieren oder deaktivieren.

Verweisen auf das Back-End mithilfe der set-backend-service-Richtlinie

Nachdem Sie ein Back-End erstellt haben, können Sie in Ihren APIs auf den Back-End-Bezeichner (Name) verweisen. Verwenden Sie die set-backend-service-Richtlinie, um eine eingehende API-Anforderung an das Back-End weiterzuleiten. Wenn Sie bereits einen Back-End-Webdienst für eine API konfiguriert haben, können Sie die set-backend-service-Richtlinie stattdessen verwenden, um die Anforderung an eine Back-End-Entität umzuleiten. Beispiel:

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

Hinweis

Alternativ können Sie base-url verwenden. Normalerweise ist das Format https://backend.com/api. Vermeiden Sie das Hinzufügen eines Schrägstrichs am Ende, um Fehlkonfigurationen zu verhindern. In der Regel sollten der base-url und der HTTP(S)-Endpunktwert im Back-End übereinstimmen, um eine nahtlose Integration zwischen Frontend und Back-End zu ermöglichen. Beachten Sie, dass API Management-Instanzen den Namen des Back-End-Diensts an die base-url anfügen.

Sie können eine bedingte Logik mit der set-backend-service-Richtlinie nutzen, um das tatsächlich verwendete Back-End basierend auf dem Standort, dem aufgerufenen Gateway oder anderen Ausdrücken zu ändern.

Hier ist beispielsweise eine Richtlinie zum Weiterleiten von Datenverkehr an ein anderes Back-End basierend auf dem aufgerufenen Gateway:

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

Tipp

Die API-Verwaltung erkennt und verwendet auch back-End-Entitäten, wenn sie API-Anforderungen empfängt. Wenn zur Laufzeit eine Back-End-Entität vorhanden ist, die der URL eines Back-End-Diensts entspricht, an den die API-Verwaltung eine Anforderung sendet, wird die Back-End-Entität verwendet. Sie müssen nicht explizit verwenden set-backend-service.

Trennschalter

API Management stellt die Eigenschaft circuit breaker (Schutzschalter) in der Back-End-Ressource zur Verfügung, um einen Back-End-Dienst vor der Überlastung durch zu viele Anforderungen zu schützen.

  • Die Eigenschaft „circuit breaker“ definiert Regeln, die angeben, bei welchen Ereignissen der Trennschalter ausgelöst werden soll. Hierbei kann es sich beispielsweise um die Anzahl oder den Prozentsatz an Fehlerbedingungen während eines definierten Zeitintervalls handeln oder eine Reihe von Statuscodes, die auf Fehler hinweisen.
  • Wenn der Trennschalter ausgelöst wird, sendet API Management über einen definierten Zeitraum keine Anforderungen mehr an den Back-End-Dienst und gibt die Antwort „503 – Dienst nicht verfügbar“ an die anfordernden Clients zurück.
  • Nach dem konfigurierten Zeitraum wird die Verbindung zurückgesetzt, und der Datenverkehr wird wieder an das Back-End geleitet.

Der Trennschalter im Back-End ist eine Implementierung des Trennschaltermusters, um dem Back-End die Möglichkeit zu geben, sich nach Überlastungssituationen zu erholen. Dieses Feature erweitert die allgemeinen Richtlinien für Ratenbegrenzung und Parallelitätsbegrenzung, die Sie implementieren können, um das API Management-Gateway und Ihre Back-End-Dienste zu schützen.

Hinweis

  • Derzeit wird die Back-End-Sicherung im Tarif Verbrauch für API Management nicht unterstützt.
  • Aufgrund der verteilten Architektur von API Management sind die Regeln für die Auslösung von Sicherungen ungenau. Verschiedene Instanzen des Gateways werden untereinander nicht synchronisiert und wenden Sicherungsregeln basierend auf den Informationen zur jeweiligen Instanz an.
  • Derzeit können Sie nur eine Regel für einen Back-End-Schaltkreisschalter konfigurieren.

Vorsicht

Wenn Sie eine Azure OpenAI Service-Instanz als Back-End konfigurieren und der Dienst zu viele Anforderungen empfängt, wird der Antwortstatuscode 429 Too Many Requests und ein Retry-After-Header mit einem Wert zurückgegeben, der groß sein kann (z. B. 1 Tag). Implementieren Sie mit Azure OpenAI-Back-Ends Schaltkreistrennregeln, um die 429 Antworten zu verarbeiten und die Retry-After Dauer zu akzeptieren.

Beispiel

Verwenden Sie das Azure-Portal, die API-Verwaltungs-REST-API oder eine Bicep- oder ARM-Vorlage, um einen Circuit Breaker in einem Backend zu konfigurieren. Im folgenden Beispiel wird der Schutzschalter in myBackend in der API Management-Instanz myAPIM ausgelöst, wenn mindestens drei 5xx-Statuscodes an einem Tag auftreten. Diese Codes zeigen Serverfehler in 1 Stunde an.

Der Schaltkreisschalter in diesem Beispiel wird nach 1 Stunde zurückgesetzt. Wenn die Antwort einen Retry-After-Header enthält, akzeptiert der Schutzschalter den Wert und wartet die angegebene Zeit ab, bevor Anforderungen erneut an das Back-End gesendet werden.

  1. Wechseln Sie im Azure-Portal zu Ihrer API-Verwaltungsinstanz.
  2. Wählen Sie im linken Menü APIs>Back-Ends> Ihr Backend aus.
  3. Wählen Sie auf der Back-End-Seite "Einstellungen"> die Einstellungen für den>"Neu hinzufügen" aus.
  4. Konfigurieren Sie auf der Seite Neuen Trennschalter erstellen die Regel:
    • Regelname: Geben Sie einen Namen für die Regel ein, z. B. myBackend.
    • Fehleranzahl: Geben Sie 3 ein.
    • Fehlerintervall: Lassen Sie den Standardwert von 1 Stunde.
    • Fehlerstatuscodebereich: Wählen Sie 500 - 599 aus.
    • Reisedauer: Lassen Sie den Standardwert von 1 Stunde.
    • Überprüfen Sie den Header "Retry-After" in der HTTP-Antwort: Select True (Accept).

Pool mit Lastenausgleich

API Management unterstützt Back-End-Pools, wenn Sie mehrere Back-Ends für eine API implementieren und einen Lastenausgleich für Anforderungen für diese Back-Ends durchführen möchten. Ein Pool ist eine Sammlung von Backends, die als eine Einheit für die Lastverteilung behandelt werden.

Verwenden Sie einen Back-End-Pool für Szenarien wie die folgenden Szenarien:

  • Verteilen der Last auf mehrere Back-Ends, die möglicherweise über einzelne Back-End-Sicherungen verfügen
  • Verschieben der Last von einer Gruppe von Back-Ends auf eine andere für ein Upgrade (Blau-Grün-Bereitstellung)

Hinweis

  • Sie können bis zu 30 Backends in einen Pool integrieren.
  • Aufgrund der verteilten Architektur von API Management sind Lastenausgleiche für Back-Ends ungenau. Verschiedene Instanzen des Gateways werden untereinander nicht synchronisiert und führen einen Lastenausgleich basierend auf den Informationen zur jeweiligen Instanz durch.

Optionen für den Lastenausgleich

API Management unterstützt die folgenden Lastenausgleichsoptionen für Back-End-Pools:

Option "Lastenausgleich" BESCHREIBUNG
Roundrobin Standardmäßig werden Anforderungen gleichmäßig auf die Back-Ends im Pool verteilt.
Gewichtet Weisen Sie den Backends im Pool Gewichtungen zu und verteilen Sie Anfragen basierend auf der relativen Gewichtung der einzelnen Backends. Nützlich für Szenarien wie blaugrüne Bereitstellungen.
Prioritätsbasiert Organisieren Sie Backends in Prioritätsgruppen. Senden Sie Anforderungen zuerst an Gruppen mit höherer Priorität. Innerhalb einer Gruppe verteilen Sie die Anforderungen gleichmäßig oder gemäß den zugewiesenen Gewichtungen.

Hinweis

Der API-Verwaltungsdienst verwendet Back-Ends in Gruppen mit niedrigerer Priorität nur, wenn alle Back-Ends in Gruppen mit höherer Priorität nicht verfügbar sind, da Schaltkreistrennregeln übersprungen werden.

Sitzungsbindung

Mit einer der vorherigen Optionen für den Lastenausgleich können Sie das Sitzungsbewusstsein (Sitzungsaffinität) aktivieren, um sicherzustellen, dass alle Anforderungen eines bestimmten Benutzers während einer Sitzung zum gleichen Back-End im Pool wechseln. Die API-Verwaltung legt ein Sitzungs-ID-Cookie fest, um den Sitzungszustand aufrechtzuerhalten. Diese Option ist beispielsweise in Szenarien mit Back-Ends wie KI-Chat-Assistenten oder anderen Unterhaltungs-Agents hilfreich, um Anforderungen von derselben Sitzung an denselben Endpunkt weiterzuleiten.

Hinweis

Sitzungsbindung in Pools mit Lastenausgleich wird zuerst für AI Gateway EarlyUpdategruppe veröffentlicht.

Verwalten von Cookies für die Sitzungsbindung

Wenn Sie das Sitzungsbewusstsein verwenden, muss der Kunde Cookies entsprechend verarbeiten. Der Client muss den Set-Cookie Headerwert speichern und mit nachfolgenden Anfragen senden, um den Sitzungszustand beizubehalten.

Sie können API-Verwaltungsrichtlinien verwenden, um Cookies für die Sitzungserkennung festzulegen. Zum Beispiel muss der Client im Fall der Assistants-API (ein Feature von Azure OpenAI in Microsoft Foundry Models) die Sitzungs-ID behalten, die Thread-ID aus dem Body extrahieren und das Paar behalten und bei jedem Aufruf das richtige Cookie senden. Darüber hinaus muss der Client wissen, wann ein Cookie gesendet werden soll oder wann kein Cookie-Header gesendet werden soll. Diese Anforderungen können entsprechend behandelt werden, indem sie die folgenden Beispielrichtlinien definieren:

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

Beispiel

Verwenden Sie das Portal, die API-Verwaltungs-REST-API oder eine Bicep- oder ARM-Vorlage, um einen Back-End-Pool zu konfigurieren. Im folgenden Beispiel wird das Back-End myBackendPool in der API Management-Instanz myAPIM mit einem Back-End-Pool konfiguriert. Die Namen der Beispiel-Back-Ends im Pool lauten backend-1 und backend-2. Beide Back-Ends befinden sich in der Gruppe mit der höchsten Priorität; innerhalb der Gruppe hat Back-End-1 eine größere Gewichtung als Back-End-2.

  1. Wechseln Sie im Azure-Portal zu Ihrer API-Verwaltungsinstanz.
  2. Wählen Sie im linken Menü APIs>Back-Ends> Ihr Backend aus.
  3. Wählen Sie auf der Seite "Back-Ends " die Registerkarte " Lastenausgleich " aus.
  4. Wählen Sie +Neuen Pool erstellen.
  5. Geben Sie auf der Seite " Neuen Lastenausgleichspool erstellen " die folgenden Informationen ein:
    • Name: Geben Sie einen Namen für den Pool ein, z. B. myBackendPool.
    • Beschreibung: Geben Sie optional eine Beschreibung ein.
    • Hinzufügen von Back-Ends zum Pool: Wählen Sie ein oder mehrere Back-Ends aus, die dem Pool hinzugefügt werden sollen.
    • Back-End-Gewichtung und Priorität: Wählen Sie "Gewichtung und Priorität anpassen" aus, um die Gewichtung und Priorität jedes Back-End im Pool zu konfigurieren. Wenn Sie z. B. zwei Backends namens Backend-1 und Backend-2 hinzugefügt haben, setzen Sie die Gewichtung für Backend-1 auf 3 und für Backend-2 auf 1, und setzen Sie die Priorität beider Backends auf 1.
    • Klicken Sie auf Erstellen.

Begrenzungen

  • Für die Ebenen Developer und Premium Ebenen kann eine API Management-Instanz, die in einem internen virtuellen Netz bereitgestellt wird, einen HTTP 500 BackendConnectionFailure-Fehler auslösen, wenn die Gateway-Endpunkt-URL und die Back-End-URL identisch sind. Wenn Sie auf diese Einschränkung stoßen, befolgen Sie die Anweisungen im Artikel Self-Chained API Management request limitation in internal virtual network mode im Tech Community Blog.
  • Derzeit können Sie nur eine Regel für einen Back-End-Schaltkreisschalter konfigurieren.

Zugehöriger Inhalt

  • Last updated on