Condividi tramite

Back-end in Gestione API

SI APPLICA A: tutti i livelli di Gestione API

Un back-end (o back-end dell'API) in Gestione API è un servizio HTTP che implementa l'API front-end e le relative operazioni.

Quando si importano determinate API, Gestione API configura automaticamente il back-end dell'API. Gestione API, ad esempio, configura il servizio Web back-end durante l'importazione:

Per altre API, ad esempio le API dei servizi di Azure, si importa una risorsa di Azure senza specificare in modo esplicito il servizio back-end. Gli esempi includono:

Gestione API supporta anche l'uso di altre risorse come back-end API, ad esempio:

Per questi back-end, è possibile creare un'entità back-end in Gestione API e farvi riferimento nelle API.

Vantaggi dei back-end

Gestione API supporta le entità back-end per consentire la gestione dei servizi back-end dell'API. Un'entità back-end incapsula informazioni sul servizio back-end, promuovendo la riutilizzabilità tra le API e migliorando la governance.

Usare i back-end per uno o più delle attività seguenti:

  • Autorizzare le credenziali delle richieste al servizio back-end
  • Sfruttare le funzionalità di Gestione API per gestire i segreti in Azure Key Vault se si configurano valori denominati per l'autenticazione dei parametri di intestazione o query
  • Definire le regole dell'interruttore per proteggere il back-end da un numero eccessivo di richieste
  • Instradare o bilanciare il carico delle richieste a più back-end

Configurare e gestire le entità back-end nel portale di Azure oppure usando API o strumenti di Azure.

Creare un back-end

È possibile creare un back-end nel portale di Azure oppure usando API o strumenti di Azure.

Note

Quando si importano determinate API, ad esempio le API da Microsoft Foundry o da altri servizi di intelligenza artificiale, Gestione API configura automaticamente un'entità back-end.

Per creare un back-end nel portale:

  1. Accedere al portale e passare all'istanza di Gestione API.
  2. Nel menu a sinistra selezionare API>Back-end>+ Crea nuovo back-end.
  3. Nella pagina Back-end completare i passaggi seguenti:
    1. Immettere un nome per il back-end e la descrizione facoltativa.
    2. Selezionare un tipo di hosting back-end, come una risorsa di Azure per una risorsa come una Function App o una Logic App, un URL personalizzato per un servizio personalizzato o un cluster di Service Fabric.
    3. In URL di runtime immettere l'URL del servizio back-end a cui vengono inoltrate le richieste API.
    4. In Avanzate disabilitare facoltativamente la convalida della catena di certificati o del nome del certificato per il back-end.
    5. Sotto Aggiungi questo servizio back-end a un pool back-end, facoltativamente selezionare o creare un pool con bilanciamento del carico per il back-end.
    6. Sotto la regola dell'interruttore, è possibile configurare facoltativamente un interruttore per il backend.
    7. In Credenziali di autorizzazione configurare facoltativamente le credenziali per autorizzare l'accesso al back-end. Le opzioni includono un'intestazione di richiesta, un parametro di query, un certificato client o un'identità gestita assegnata dal sistema o assegnata dall'utente configurata nell'istanza di Gestione API.
    8. Fare clic su Crea.

Dopo aver creato un back-end, è possibile aggiornare le impostazioni back-end in qualsiasi momento. Ad esempio, è possibile aggiungere una regola di interruttore, modificare l'URL di runtime o aggiungere le credenziali di autorizzazione.

Configurare l'identità gestita per le credenziali di autorizzazione

È possibile usare un'identità gestita assegnata dal sistema o assegnata dall'utente configurata nell'istanza di Gestione API per autorizzare l'accesso al servizio back-end. Per configurare un'identità gestita per le credenziali di autorizzazione, seguire questa procedura:

  1. Nella sezione Credenziali di autorizzazione della configurazione back-end selezionare la scheda Identità gestita e selezionare Abilita.

  2. In Identità client selezionare Identità assegnata dal sistema o identità assegnata dall'utente configurata nell'istanza.

  3. In ID risorsa immettere un servizio di Azure di destinazione o l'ID applicazione della propria applicazione Microsoft Entra che rappresenta il back-end. Ad esempio, immettere https://cognitiveservices.azure.com per il servizio Azure OpenAI.

    Per ulteriori esempi, vedere le informazioni di riferimento del criterio authentication-managed-identity.

  4. Fare clic su Crea.

Note

Assegna inoltre all'identità gestita le autorizzazioni appropriate o un ruolo adeguato per il controllo degli accessi per accedere al servizio backend. Ad esempio, se il back-end è un servizio OpenAI di Azure, assegnare al ruolo Cognitive Services User l'identità gestita.

Configurare i certificati per le credenziali di autorizzazione

È possibile proteggere l'accesso gateway al servizio back-end usando l'autenticazione TLS reciproca con certificati client o certificati dell'autorità di certificazione personalizzata.

Configurare il certificato client

Se il servizio back-end è protetto con un certificato rilasciato da una CA nota, è possibile aggiungere un certificato client nell'entità back-end:

  1. Aggiungere il certificato all'istanza di Gestione API. È possibile fare riferimento a un certificato gestito in Azure Key Vault o caricare un file PFX.
  2. Nella sezione Credenziali di autorizzazione della configurazione back-end selezionare la scheda Certificati client .
  3. Nell'elenco a discesa selezionare il certificato client da usare.
  4. Fare clic su Crea.

Configurare il certificato della CA

Se il servizio back-end usa un certificato ca personalizzato, è possibile fare riferimento al certificato della CA personalizzato nell'entità back-end. Potrebbe essere necessario eseguire questo passaggio per stabilire l'attendibilità per il certificato del server back-end, ad esempio con certificati autofirmati, certificati radice non attendibili o catene di certificati parziali.

Note

Attualmente, è possibile configurare solo i dettagli del certificato della CA in un'entità back-end nei livelli v2.

Per aggiungere i dettagli del certificato della CA, seguire questa procedura:

  1. Nella sezione Credenziali di autorizzazione della configurazione back-end selezionare Certificati CA.
  2. Selezionare + Aggiungi dettagli certificato CA.
  3. Nel riquadro Aggiungi certificato CA selezionare una delle opzioni seguenti:
    • Impronta digitale del certificato: immettere l'impronta digitale (hash SHA-1, SHA-256 o SHA-512) di un certificato CA personalizzato.
    • Nome soggetto e impronta digitale dell'emittente - immettere il nome del soggetto che identifica in modo univoco la CA e l'impronta digitale della CA.
  4. Seleziona Aggiungi.
  5. Fare clic su Crea.

Screenshot della configurazione dei dettagli del certificato CA per un back-end nel portale.

Note

Quando si configurano i dettagli di un certificato ca personalizzato nell'entità back-end, Gestione API convalida sempre il nome del certificato e la catena di certificati, indipendentemente dal fatto che le impostazioni di convalida siano abilitate o disabilitate nel back-end.backendTlsProperties

Fare riferimento al backend utilizzando il criterio set-backend-service

Dopo aver creato un back-end, è possibile fare riferimento all'identificatore back-end (nome) nelle API. Usare il criterio set-backend-service per indirizzare una richiesta API in ingresso al back-end. Se è già stato configurato un servizio Web back-end per un'API, è possibile usare il criterio set-backend-service per reindirizzare la richiesta a un'entità back-end. Ad esempio:

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

Note

In alternativa, è possibile usare base-url. In genere, il formato è https://backend.com/api. Evitare di aggiungere una barra alla fine per evitare errori di configurazione. In genere, il valore dell'endpoint base-url e HTTP(S) nel back-end deve corrispondere per consentire un'integrazione trasparente tra front-end e back-end. Si noti che le istanze di Gestione API aggiungono il nome del servizio back-end a base-url.

È possibile usare la logica condizionale con il criterio set-backend-service per modificare il back-end effettivo in base alla posizione, al gateway che è stato chiamato o ad altre espressioni.

Ad esempio, di seguito viene riportato un criterio per instradare il traffico a un altro back-end in base al gateway che è stato chiamato:

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

Suggerimento

Gestione API rileva e usa automaticamente le entità back-end quando riceve le richieste API. In fase di esecuzione, se è presente un'entità back-end che corrisponde all'URL di un servizio back-end a cui Gestione API invia una richiesta, usa l'entità back-end. Non è necessario usare set-backend-servicein modo esplicito .

Interruttore automatico

Gestione API espone una proprietà interruttore nella risorsa back-end per evitare che un servizio back-end venga sovraccaricato da un numero eccessivo di richieste.

  • La proprietà interruttore definisce le regole per l'attivazione dell'interruttore, come il numero o la percentuale di condizioni di guasto durante un intervallo di tempo definito e una gamma di codici di stato che indicano i guasti.
  • Quando l'interruttore viene attivato, Gestione API interrompe l'invio di richieste al servizio back-end per un periodo di tempo definito e restituisce al client una risposta 503 Servizio non disponibile.
  • Una volta trascorso il tempo di attivazione configurato, il circuito viene ripristinato e il traffico riprende verso il back-end.

L'interruttore back-end è un'implementazione del modello di interruttore per consentire al back-end di eseguire il ripristino da situazioni di overload. Aumenta i criteri generali di limitazione della frequenza e limitazione della concorrenza che è possibile implementare per proteggere il gateway di Gestione API e i servizi back-end.

Note

  • Attualmente, l'interruttore back-end non è supportato nel livello A consumo di Gestione API.
  • A causa della natura distribuita dell'architettura di Gestione API, le regole di interruzione del circuito sono approssimative. Le diverse istanze del gateway non sono sincronizzate e applicano regole di interruzione del circuito in base alle informazioni sulla stessa istanza.
  • Attualmente, è possibile configurare una sola regola per un interruttore back-end.

Attenzione

Se si configura un servizio OpenAI di Azure come back-end e il servizio riceve troppe richieste, restituisce un 429 Too Many Requests codice di stato della risposta e un'intestazione Retry-After con un valore di grandi dimensioni, ad esempio 1 giorno. Con i back-end di Azure OpenAI, implementare regole di interruttore per gestire le risposte 429 e accettare la durataRetry-After.

Esempio

Usare il portale di Azure, l'API REST di Gestione API o un modello Bicep o ARM per configurare un interruttore in un back-end. Nell'esempio seguente l'interruttore in myBackend nell'istanza myAPIM di Gestione API viene attivato quando nell'arco di un'ora vengono restituiti tre o più codici di stato 5xx che indicano errori del server.

L'interruttore in questo esempio viene reimpostato dopo 1 ora. Se nella risposta è presente un'intestazione Retry-After, l'interruttore accetta il valore e attende il tempo specificato prima di inviare nuovamente le richieste al back-end.

  1. Nel portale di Azure passare all'istanza di Gestione API.
  2. Nel menu a sinistra seleziona API>Backends> il tuo back-end.
  3. Nella pagina back-end selezionare Impostazioni>Impostazioni interruttore>Aggiungi nuovo.
  4. Nella pagina Crea nuovo interruttore configurare la regola:
    • Nome regola: immettere un nome per la regola, ad esempio myBackend.
    • Numero di errori: immettere 3.
    • Intervallo di errore: lasciare il valore predefinito di 1 ora.
    • Intervallo di codici di stato errore: selezionare 500 - 599.
    • Durata viaggio: lasciare il valore predefinito di 1 ora.
    • Controllare l'intestazione 'Retry-After' nella risposta HTTP: selezionare True (Accept).

Pool con bilanciamento del carico

Gestione delle API supporta i backend pool quando si desidera implementare più backend per un'API e bilanciare il carico delle richieste tra tali backend. Un pool è una raccolta di back-end considerati come una singola entità per il bilanciamento del carico.

Usare un pool back-end per scenari come gli scenari seguenti:

  • Distribuire il carico in più back-end, che possono avere singoli interruttori di back-end.
  • Spostare il carico da un set di back-end a un altro per l'aggiornamento (distribuzione blu-verde).

Note

  • È possibile includere fino a 30 back-end in un pool.
  • A causa della natura distribuita dell'architettura di Gestione API, il bilanciamento del carico di back-end è approssimativo. Le diverse istanze del gateway non sincronizzano e bilanciano il carico in base alle informazioni sulla stessa istanza.

Opzioni di bilanciamento del carico

Gestione API supporta le opzioni di bilanciamento del carico seguenti per i pool back-end:

Opzione di bilanciamento del carico Descrizione
Round robin Le richieste vengono distribuite uniformemente tra i back-end nel pool per impostazione predefinita.
Ponderato Assegnare pesi ai backend nel pool e distribuire le richieste in base al peso relativo di ciascun backend. Utile per scenari come le distribuzioni blu-verde.
Basato sulla priorità Organizzare i back-end in gruppi di priorità. Inviare prima le richieste ai gruppi con priorità più alta; all'interno di un gruppo, distribuire le richieste in modo uniforme o in base ai pesi assegnati.

Note

Il servizio di API Management usa i back-end nei gruppi con priorità più bassa solo quando tutti i back-end in gruppi con priorità più alta non sono disponibili perché le regole dell'interruttore vengono bloccate.

Riconoscimento della sessione

Con una delle opzioni di bilanciamento del carico precedenti, è possibile abilitare la consapevolezza della sessione (affinità di sessione) per assicurarsi che tutte le richieste di un utente specifico durante una sessione vengano indirizzate allo stesso back-end nel pool. Gestione API imposta un cookie id sessione per mantenere lo stato della sessione. Questa opzione è utile, ad esempio, negli scenari con back-end, ad esempio assistenti di chat di intelligenza artificiale o altri agenti di conversazione per instradare le richieste dalla stessa sessione allo stesso endpoint.

Note

Il riconoscimento della sessione nei pool con carico bilanciato viene pubblicato prima nel gruppo di aggiornamentianticipati del Gateway IA.

Gestire i cookie per la consapevolezza delle sessioni

Quando si usa la consapevolezza della sessione, il client deve gestire i cookie in modo appropriato. Il client deve archiviare il valore dell'intestazione Set-Cookie e inviarlo con richieste successive per mantenere lo stato della sessione.

È possibile usare i criteri di Gestione API per impostare i cookie per la consapevolezza delle sessioni. Ad esempio, per il caso dell'API Assistants (una funzionalità di Azure OpenAI in Microsoft Foundry Models), il client deve mantenere l'ID sessione, estrarre l'ID del thread dal corpo e mantenere la coppia e inviare il cookie corretto per ogni chiamata. Inoltre, il client deve sapere quando inviare un cookie o quando non inviare un'intestazione di cookie. Questi requisiti possono essere gestiti in modo appropriato definendo i criteri di esempio seguenti:

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

Esempio

Usare il portale, l'API REST di gestione delle API o un modello Bicep o ARM per configurare un pool di backend. Nell'esempio seguente il back-end myBackendPool nell'istanza di Gestione API myAPIM è configurato con un pool di back-end. I back-end di esempio nel pool sono denominati backend-1 e backend-2. Entrambi i back-end si trovano nel gruppo con priorità più alta; all'interno del gruppo, back-end-1 ha un peso maggiore di back-end-2.

  1. Nel portale di Azure passare all'istanza di Gestione API.
  2. Nel menu a sinistra seleziona API>Backends> il tuo back-end.
  3. Nella pagina Back-end selezionare la scheda Bilanciamento del carico .
  4. Selezionare + Crea nuovo pool.
  5. Nella pagina Crea nuovo pool con carico bilanciato immettere le informazioni seguenti:
    • Nome: immettere un nome per il pool, ad esempio myBackendPool.
    • Descrizione: immettere facoltativamente una descrizione.
    • Aggiungere back-end al pool: selezionare uno o più back-end da aggiungere al pool.
    • Peso e priorità back-end: selezionare Personalizza peso e priorità per configurare il peso e la priorità di ogni back-end nel pool. Ad esempio, se sono stati aggiunti due back-end denominati back-end-1 e backend-2, impostare il peso di back-end-1 su 3 e il peso del back-end-2 su 1 e impostare la priorità di entrambi i back-end su 1.
    • Fare clic su Crea.

Limitazioni

Contenuti correlati

  • Last updated on