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:

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

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 o usare API o strumenti di Azure.

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 eseguire le operazioni seguenti:
    1. Immettere un nome per il back-end e la descrizione facoltativa.
    2. Selezionare un tipo di hosting back-end, ad esempio risorsa di Azure per una risorsa di Azure , ad esempio un'app per le funzioni o un'app per la logica, 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, 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. Esempio: https://cognitiveservices.azure.com per il servizio OpenAI di Azure.

    Per ulteriori esempi, vedere il riferimento della policy authentication-managed-identity.

  4. Fare clic su Crea.

Nota

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, è possibile assegnare l'identità gestita al Cognitive Services User ruolo.

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

Nota

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 Gestione API istanze aggiungono il nome del base-urlservizio back-end a .

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

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.

Nota

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

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>Interruttore impostazioni>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 API supporta pool di back-end, quando si vogliono implementare più back-end per un'API e bilanciare il carico delle richieste tra tali back-end. Un pool è una raccolta di back-end considerati come una singola entità per il bilanciamento del carico.

Usare un pool di back-end per scenari come i 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).

Nota

  • È 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 vengono sincronizzate e il carico verrà bilanciato 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 I pesi vengono assegnati ai back-end nel pool e le richieste vengono distribuite in base al peso relativo di ogni back-end. Utile per scenari come le distribuzioni blu-verde.
Basato sulla priorità I back-end sono organizzati in gruppi di priorità. Le richieste vengono inviate prima a gruppi con priorità più alta; all'interno di un gruppo, le richieste vengono distribuite uniformemente o in base ai pesi assegnati.

Nota

I back-end nei gruppi con priorità più bassa verranno usati solo quando tutti i back-end in gruppi con priorità più alta non sono disponibili perché le regole dell'interruttore vengono bloccate.

Consapevolezza della sessione

Con una delle opzioni di bilanciamento del carico precedenti, abilitare facoltativamente la consapevolezza della sessione (affinità di sessione) per garantire 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.

Nota

La consapevolezza delle sessioni nei pool con carico bilanciato viene rilasciata prima al gruppo di aggiornamento Anticipato del Gateway dell'Intelligenza Artificiale.

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 Azure AI 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 eseguire le operazioni 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.

Limiti

Contenuto correlato