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:

• Una specifica OpenAPI.
• Un'API SOAP.
• Risorse di Azure, ad esempio un'app per le funzioni di Azure attivata da HTTP o un'app per la logica.

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

• Un cluster di Service Fabric.
• Un servizio personalizzato.

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.

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

Dopo aver creato un back-end, è possibile fare riferimento al back-end 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/>

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

Esempio

Usare 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 viene ripristinato dopo un'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.

resource symbolicname 'Microsoft.ApiManagement/service/backends@2023-09-01-preview' = {
  name: 'myAPIM/myBackend'
  properties: {
    url: 'https://mybackend.com'
    protocol: 'https'
    circuitBreaker: {
      rules: [
        {
          failureCondition: {
            count: 3
            errorReasons: [
              'Server errors'
            ]
            interval: 'PT1H' 
            statusCodeRanges: [
              {
                min: 500
                max: 599
              }
            ]
          }
          name: 'myBreakerRule'
          tripDuration: 'PT1H'  
          acceptRetryAfter: true
        }
      ]
    }
   }
 }

{
  "type": "Microsoft.ApiManagement/service/backends",
  "apiVersion": "2023-09-01-preview",
  "name": "myAPIM/myBackend",
  "properties": {
    "url": "https://mybackend.com",
    "protocol": "https",
    "circuitBreaker": {
      "rules": [
        {
          "failureCondition": {
            "count": "3",
            "errorReasons": [ "Server errors" ],
            "interval": "PT1H",
            "statusCodeRanges": [
              {
                "min": "500",
                "max": "599"
              }
            ]
          },
          "name": "myBreakerRule",
          "tripDuration": "PT1H",
          "acceptRetryAfter": true
        }
      ]
    }
  }
}

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.

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

Per creare un pool di back-end, impostare la proprietà type del back-end su pool e specificare un elenco di back-end che costituiscono il pool.

Opzioni di bilanciamento del carico

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

• Round robin: per impostazione predefinita, le richieste vengono distribuite uniformemente tra i back-end del pool.
• Ponderato: ai back-end del pool vengono assegnati pesi e le richieste vengono distribuite tra i back-end in base al peso relativo assegnato a ogni back-end. Usare questa opzione per scenari come l'esecuzione di una distribuzione blu-verde.
• Basato su priorità: i back-end vengono organizzati in gruppi di priorità e le richieste vengono inviate ai back-end in ordine di gruppi di priorità. All'interno di un gruppo di priorità, le richieste vengono distribuite uniformemente tra i back-end o, se previsto, in base al peso relativo assegnato a ogni back-end.

Esempio

Usare l'API REST di Gestione API o un modello Bicep o ARM per configurare un pool di back-end. 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, backend-1 ha un peso maggiore di backend-2.

resource symbolicname 'Microsoft.ApiManagement/service/backends@2023-09-01-preview' = {
  name: 'myAPIM/myBackendPool'
  properties: {
    description: 'Load balancer for multiple backends'
    type: 'Pool'
    pool: {
      services: [
        {
          id: '/subscriptions/<subscriptionID>/resourceGroups/<resourceGroupName>/providers/Microsoft.ApiManagement/service/<APIManagementName>/backends/backend-1'
          priority: 1
          weight: 3
        }
        {
          id: '/subscriptions/<subscriptionID>/resourceGroups/<resourceGroupName>/providers/Microsoft.ApiManagement/service/<APIManagementName>/backends/backend-2'
          priority: 1
          weight: 1
        }
      ]
    }
  }
}

{
  "type": "Microsoft.ApiManagement/service/backends",
  "apiVersion": "2023-09-01-preview",
  "name": "myAPIM/myBackendPool",
  "properties": {
    "description": "Load balancer for multiple backends",
    "type": "Pool",
    "pool": {
      "services": [
        {
          "id": "/subscriptions/<subscriptionID>/resourceGroups/<resourceGroupName>/providers/Microsoft.ApiManagement/service/<APIManagementName>/backends/backend-1",
          "priority": "1", 
          "weight": "3" 
        },
        {
          "id": "/subscriptions/<subscriptionID>/resourceGroups/<resourceGroupName>/providers/Microsoft.ApiManagement/service/<APIManagementName>/backends/backend-2",
          "priority": "1",
          "weight": "1"    
        }
      ]
    }
  }
}

Limitazione

Per i livelli Developer e Premium, un'istanza di Gestione API distribuita in una rete virtuale interna può generare errori HTTP 500 BackendConnectionFailure quando l'URL dell'endpoint del gateway e l'URL di back-end sono uguali. Se si verifica questa limitazione, seguire le istruzioni riportate nell'articolo Limitazione delle richieste di Gestione API concatenate automaticamente in modalità rete virtuale interna nel blog della community tecnica.

Contenuto correlato

• Blog: Uso di Azure Gestione API interruttore e bilanciamento del carico con il servizio Azure OpenAI
• Configurare un back-end di Service Fabric usando il portale di Azure.