Backends em Gestão de API

APLICA-SE A: Todas as camadas de gerenciamento de API

Um back-end (ou back-end de API) na Gestão de API é um serviço HTTP que implementa a sua API de front-end e as suas operações.

Quando importa certas APIs, a Gestão de APIs configura automaticamente o backend da API. Por exemplo, o Gerenciamento de API configura o serviço Web de back-end ao importar:

• Uma OpenAPI especificação.
• Uma API SOAP.

Para outras APIs, como APIs dos serviços do Azure, importa um recurso do Azure sem especificar explicitamente o serviço de backend. Os exemplos incluem:

• Uma aplicação de funções Azure ativada por HTTP
• Uma aplicação de lógica.

A Gestão de APIs também suporta a utilização de outros recursos como backend de API, tais como:

• Um cluster do Service Fabric.
• Serviços de IA
• Um serviço personalizado

Para estes backends, pode criar uma entidade backend na API Management e referencia-a nas suas APIs.

Benefícios dos backends

O Gerenciamento de API suporta entidades de back-end para que você possa gerenciar os serviços de back-end de sua API. Uma entidade de back-end encapsula informações sobre o serviço de back-end, promovendo a reutilização entre APIs e governança aprimorada.

Utilize backends para um ou mais dos seguintes:

• Autorizar as credenciais de solicitações para o serviço de back-end
• Aproveite a funcionalidade de Gestão de API para manter segredos no Azure Key Vault se os valores nomeados estiverem configurados para autenticação de cabeçalhos ou parâmetros de consulta
• Defina regras de disjuntor para proteger seu back-end de muitas solicitações
• Encaminhar ou balancear carga de solicitações para vários servidores backend

Configure e gere entidades backend no portal Azure, ou usando APIs ou ferramentas Azure.

Criar um back-end

Pode criar um backend no portal Azure, ou usando APIs ou ferramentas Azure.

Para criar um back-end no portal:

1. Inicia sessão no portal e vai à tua instância de Gestão de APIs.
2. No menu à esquerda, selecione APIs>Backends>.
3. Na página de Backend , complete os seguintes passos:
   1. Insira um Nome para o backend e uma Descrição opcional.
   2. Selecione um tipo de alojamento Backend, como recurso Azure para um recurso Azure como uma Function App ou Logic App, URL personalizada para um serviço personalizado ou um cluster Service Fabric .
   3. Em URL de tempo de execução, insira a URL do serviço de back-end para o qual as solicitações de API são encaminhadas.
   4. Em Avançado, desative, opcionalmente, a cadeia de certificados ou a validação do nome do certificado para o back-end.
   5. Em Adicionar este serviço de back-end a um pool de back-end, opcionalmente, selecione ou crie um pool com balanceamento de carga para o back-end .
   6. Em Regra do disjuntor, configure opcionalmente um disjuntor para o back-end.
   7. Em Credenciais de autorização, opcionalmente, configure as credenciais para autorizar o acesso ao back-end. As opções incluem um cabeçalho de solicitação, parâmetro de consulta, certificado de cliente ou identidade gerenciada atribuída pelo sistema ou pelo usuário configurada na instância de Gerenciamento de API.
   8. Selecione Criar.

Depois de criar um back-end, você pode atualizar as configurações de back-end a qualquer momento. Por exemplo, pode adicionar uma regra de disjuntor, alterar o URL de execução ou adicionar credenciais de autorização.

Configurar identidade gerenciada para credenciais de autorização

Você pode usar uma identidade gerenciada atribuída pelo sistema ou pelo usuário configurada na instância de Gerenciamento de API para autorizar o acesso ao serviço de back-end. Para configurar uma identidade gerida para credenciais de autorização, complete os seguintes passos:

1. Na seção Credenciais de autorização da configuração de back-end, selecione a guia Identidade gerenciada e selecione Habilitar.

2. Na identidade do cliente, selecione a identidade atribuída pelo sistema ou uma identidade atribuída pelo utilizador que tenha configurado na sua instância.

3. Em ID do Recurso, insira um serviço do Azure de destino ou a ID do aplicativo do seu próprio aplicativo Microsoft Entra que representa o back-end. Por exemplo, introduza https://cognitiveservices.azure.com para o serviço Azure OpenAI.

   Para obter mais exemplos, consulte a referência da política authentication-managed-identity .

4. Selecione Criar.

Configurar certificados para credenciais de autorização

Pode proteger o acesso ao gateway ao serviço de backend, utilizando autenticação TLS mútua com certificados de cliente ou certificados de autoridade certificadora personalizada (CA).

Configurar certificado do cliente

Se o serviço backend estiver protegido com um certificado emitido por uma CA conhecida, pode adicionar um certificado de cliente na entidade backend:

1. Adicione o certificado à instância de Gestão de APIs. Podes consultar um certificado gerido no Azure Key Vault ou carregar um ficheiro PFX.
2. Na secção de credenciais de autorização da configuração do backend, selecione o separador Certificados do Cliente .
3. No menu suspenso, selecione o certificado do cliente que pretende usar.
4. Selecione Criar.

Configurar certificado de CA

Se o serviço backend usar um certificado CA personalizado, pode referenciar o certificado CA personalizado na entidade de backend. Pode ser necessário fazer este passo para estabelecer confiança no certificado do servidor backend – por exemplo, com certificados auto-assinados, certificados raiz não confiáveis ou cadeias de certificados parciais.

Para adicionar detalhes do certificado de CA, siga estes passos:

1. Na secção de credenciais de autorização da configuração backend, selecione Certificados CA.
2. Selecionar + Adicionar detalhes do certificado de CA.
3. No painel Adicionar certificado CA, selecione uma das seguintes opções:
   • Impressão digital do certificado - Introduza a impressão digital (um hash SHA-1, SHA-256 ou SHA-512) de um certificado CA personalizado.
   • Nome do assunto e impressão digital do emissor - Introduza o nome do assunto que identifica de forma única a CA e a impressão digital do certificado da CA.
4. Selecione Adicionar.
5. Selecione Criar.

Referenciar back-end usando a política de set-backend-service

Depois de criar um back-end, você pode fazer referência ao identificador de back-end (nome) em suas APIs. Use a set-backend-service política para direcionar uma solicitação de API de entrada para o back-end. Se você já configurou um serviço Web de back-end para uma API, poderá usar a set-backend-service política para redirecionar a solicitação para uma entidade de back-end. Por exemplo:

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

Você pode usar a lógica condicional com a política set-backend-service para alterar o back-end efetivo com base na localização, no gateway chamado ou outras expressões.

Por exemplo, aqui está uma política para encaminhar o tráfego para outro servidor com base no gateway que foi chamado.

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

Disjuntor

O Gerenciamento de API expõe uma propriedade de disjuntor no recurso de back-end para proteger um serviço de back-end de ser sobrecarregado por muitas solicitações.

• A propriedade do disjuntor define regras para acionar o disjuntor, como o número ou a porcentagem de condições de falha durante um intervalo de tempo definido e um intervalo de códigos de status que indicam falhas.
• Quando o disjuntor dispara, o Gerenciamento de API para de enviar solicitações para o serviço de back-end por um tempo definido e retorna uma resposta 503 Serviço Indisponível para o cliente.
• Após o tempo de viagem configurado, o circuito é reiniciado e o tráfego é retomado para o backend.

O disjuntor backend é uma implementação do padrão do disjuntor para permitir que o backend se recupere de situações de sobrecarga. Ele complementa as políticas gerais de limitação de taxa e de simultaneidade que pode implementar para proteger o gateway de gestão de API e os seus serviços de back-end.

Exemplo

Use o portal do Azure, a API REST de Gerenciamento de API ou um modelo Bicep ou ARM para configurar um disjuntor em um back-end. No exemplo a seguir, o disjuntor em myBackend na instância de Gerenciamento de API myAPIM tropeça quando há três ou mais 5xx códigos de status indicando erros do servidor em 1 hora.

O disjuntor neste exemplo é reiniciado após 1 hora. Se um Retry-After cabeçalho estiver presente na resposta, o disjuntor aceita o valor e aguarda o tempo especificado antes de enviar solicitações para o back-end novamente.

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

Pool com balanceamento de carga

A Gestão de APIs suporta "pools" de backend quando se deseja implementar múltiplos backends para uma API e distribuir os pedidos entre esses backends de maneira equilibrada. Um pool é um conjunto de back-ends que são tratados como uma única entidade para o balanceamento de carga.

Use um pool de backend para cenários como os seguintes:

• Distribua a carga por vários backends, que podem ter disjuntores de backend individuais.
• Transferir a carga de um conjunto de backends para outro conjunto para atualização (implementação azul-verde).

Opções de balanceamento de carga

O Gerenciamento de API suporta as seguintes opções de balanceamento de carga para pools de back-end:

Sensibilização para a sessão

Com qualquer uma das opções de balanceamento de carga anteriores, pode ativar a consciência de sessão (afinidade de sessão) para garantir que todos os pedidos de um utilizador específico durante a sessão vão para o mesmo backend no pool. O Gerenciamento de API define um cookie de ID de sessão para manter o estado da sessão. Esta opção é útil, por exemplo, em cenários com backends como assistentes de bate-papo de IA ou outros agentes de conversação, para rotear solicitações da mesma sessão para o mesmo endpoint.

Gerir cookies para reconhecimento da sessão

Quando utiliza a consciência de sessão, o cliente deve tratar os cookies de forma adequada. O cliente precisa armazenar o Set-Cookie valor do cabeçalho e enviá-lo com solicitações subsequentes para manter o estado da sessão.

Você pode usar políticas de Gerenciamento de API para ajudar a definir cookies para reconhecimento de sessão. Por exemplo, no caso da API Assistants (uma funcionalidade do Azure OpenAI nos Microsoft Foundry Models), o cliente precisa de manter o ID da sessão, extrair o ID do thread do corpo, manter o par e enviar o cookie correto para cada chamada. Além disso, o cliente precisa saber quando enviar um cookie ou quando não enviar um cabeçalho de cookie. Esses requisitos podem ser tratados adequadamente definindo as seguintes políticas de exemplo:

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

Exemplo

Use o portal, a API REST de Gerenciamento de API ou um modelo Bicep ou ARM para configurar um pool de back-end. No exemplo a seguir, o back-end myBackendPool na instância de Gerenciamento de API myAPIM é configurado com um pool de back-end. Exemplos de back-ends no pool são denominados backend-1 e backend-2. Ambos os backends estão no grupo prioritário mais alto; Dentro do grupo, backend-1 tem um peso maior do que 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
        }
      ],
      "sessionAffinity": { 
        "sessionId": { 
          "source": "Cookie", 
          "name": "SessionId" 
        } 
      } 
    }
  }
}

{
  "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"    
        }
      ],
        "sessionAffinity": { 
        "sessionId": { 
          "source": "Cookie", 
          "name": "SessionId" 
        } 
      } 
    }
  }
}

Limitações

• Para as camadas Developer e Premium, uma instância de Gerenciamento de API implantada em uma rede virtual interna pode gerar erros HTTP 500 BackendConnectionFailure quando a URL do ponto de extremidade do gateway e a URL do back-end são as mesmas. Se encontrar essa limitação, siga as instruções no artigo sobre a limitação de pedidos do Gerenciamento de API Auto-Encadeado no modo de rede virtual interna no blog da Comunidade Técnica.
• Atualmente, só pode configurar uma regra para um disjuntor de backend.

Conteúdos relacionados

• Blog: Usando o disjuntor de Gerenciamento de API do Azure e o balanceamento de carga com o Serviço OpenAI do Azure
• Configure um back-end do Service Fabric usando o portal do Azure.
• Guia de início rápido: criar um pool de back-end no Gerenciamento de API do Azure usando o Bicep para solicitações OpenAI de balanceamento de carga
• Consulte o Azure API Management como fonte de Event Grid para informações sobre eventos de Event Grid que o gateway gera quando um disjuntor dispara ou reinicia. Use esses eventos para agir antes que os problemas de back-end aumentem.