Back-ends no Gerenciamento de API

APLICA-SE A: todas as camadas do Gerenciamento de API

Um back-end (ou back-end de API) no Gerenciamento de API é um serviço HTTP que implementa a API de front-end e suas operações.

Quando você importa determinadas APIs, o Gerenciamento de API configura automaticamente o back-end da API. Por exemplo, o Gerenciamento de API configura o serviço Web de backend ao importar:

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

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

• Um aplicativo de funções do Azure disparado por HTTP
• Um aplicativo lógico.

O Gerenciamento de API também dá suporte ao uso de outros recursos como um back-end de API, como:

• Um cluster do Service Fabric.
• Serviços de inteligência artificial
• Um serviço personalizado

Para esses back-ends, você pode criar uma entidade de back-end no Gerenciamento de API e referenciá-la em suas APIs.

Benefícios dos back-ends

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

Use back-ends para um ou mais dos seguintes recursos:

• Autorizar as credenciais de solicitações para o serviço de back-end
• Aproveite a funcionalidade de Gerenciamento de API para manter segredos no Azure Key Vault se os valores nomeados estiverem configurados para autenticação de parâmetro de cabeçalho ou consulta
• Definir regras de disjuntor para proteger seu back-end contra o excesso de solicitações
• Rotear ou balancear a carga de solicitações para vários back-ends

Configure e gerencie entidades de back-end no portal do Azure ou usando APIs ou ferramentas do Azure.

Criar um back-end

Você pode criar um back-end no portal do Azure ou usando APIs ou ferramentas do Azure.

Para criar um back-end no portal:

1. Entre no portal e vá para a instância de Gerenciamento de API.
2. No menu à esquerda, selecione APIs>Back-ends>+ Criar novo back-end.
3. Na página Back-end , conclua as seguintes etapas:
   1. Insira um nome para o back-end e uma descrição opcional.
   2. Selecione um tipo de hospedagem de back-end, como um recurso do Azure para um recurso do Azure, como um aplicativo de funções ou aplicativo lógico, URL personalizada para um serviço personalizado ou um cluster do Service Fabric .
   3. Na URL do Runtime, insira a URL do serviço de back-end para o qual as solicitações de API são encaminhadas.
   4. Em Avançado, opcionalmente, desabilite a cadeia de certificados ou a validação de nome de certificado para o back-end.
   5. Em Adicionar esse 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. Na Regra do disjuntor, opcionalmente, configure 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 do cliente ou identidade gerenciada atribuída pelo sistema ou atribuída 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, você pode adicionar uma regra de disjuntor, alterar a URL do runtime 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 atribuída 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 gerenciada para credenciais de autorização, conclua as seguintes etapas:

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 usuário que você configurou em sua instância.

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

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

4. Selecione Criar.

Configurar certificados para credenciais de autorização

Você pode proteger o acesso de gateway ao serviço de back-end usando autenticação TLS mútua com certificados de cliente ou certificados de autoridade de certificação (AC).

Configurar o certificado do cliente

Se o serviço de back-end for protegido com um certificado emitido por uma AC conhecida, você poderá adicionar um certificado de cliente na entidade de back-end:

1. Adicione o certificado à instância de Gerenciamento de API. Você pode fazer referência a um certificado gerenciado no Azure Key Vault ou carregar um arquivo PFX.
2. Na seção Credenciais de autorização da configuração de back-end, selecione a guia Certificados do cliente .
3. Na lista suspensa, selecione o certificado do cliente que você deseja usar.
4. Selecione Criar.

Configurar o certificado de Autoridade Certificadora

Se o serviço de back-end usar um certificado de AC personalizado, você poderá referenciar o certificado de AC personalizado na entidade de back-end. Talvez seja necessário fazer essa etapa para estabelecer a confiança para o certificado do servidor de back-end, por exemplo, com certificados autoassinados, certificados raiz não confiáveis ou cadeias de certificados parciais.

Para adicionar detalhes do certificado de autoridade de certificação, siga estas etapas:

1. Na seção Credenciais de Autorização da configuração de back-end, selecione Certificados CA.
2. Selecione + Adicionar detalhes do certificado de Autoridade Certificadora.
3. No painel Adicionar certificado de AC , selecione uma das seguintes opções:
   • Impressão digital do certificado – insira a impressão digital (um hash SHA-1, SHA-256 ou SHA-512) de um certificado de AC personalizado.
   • Nome da entidade e impressão digital do emissor – insira o nome da entidade que identifica exclusivamente a AC e a impressão digital da AC.
4. Selecione Adicionar.
5. Selecione Criar.

Mencione o back-end que estiver usando a política set-backend-service

Depois de criar um back-end, você pode referenciar o identificador de back-end (nome) em suas APIs. Use a política set-backend-service para direcionar para o back-end uma solicitação de API sendo recebida. Se já tiver configurado um serviço web de back-end para uma API, você poderá usar a política set-backend-service para, em vez disso, 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 uma lógica condicional com a política set-backend-service para alterar o back-end efetivo com base na localização, no gateway que foi chamado ou em outras expressões.

Por exemplo, aqui temos uma política para rotear o tráfego para outro backend com base no gateway 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 porcentagem de condições de falha durante um intervalo de tempo definido e uma faixa de códigos de status que indicam falhas.
• Quando o disjuntor é acionado, 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 ao cliente.
• Após a duração configurada da viagem, o circuito é reiniciado e o tráfego é retomado para o back-end.

O disjuntor de back-end é uma implementação do padrão de disjuntor para permitir que o back-end se recupere de situações de sobrecarga. Ele aumenta as políticas gerais de limitação de taxa e de limitação de simultaneidade que você pode implementar para proteger o gateway do Gerenciamento de API e 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 do Gerenciamento de API myAPIM é acionado quando há três ou mais códigos de status 5xx indicando erros de servidor em 1 hora.

O disjuntor neste exemplo é reiniciado após 1 hora. Se um cabeçalho Retry-After estiver presente na resposta, o disjuntor aceitará o valor e aguardará 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

O Gerenciamento de API dá suporte aos pools de back-end quando você quer implementar vários back-ends em uma API e solicitações de balanceamento de carga nesses back-ends. Um pool é uma coleção de back-ends que são tratados como uma única entidade para balanceamento de carga.

Use um pool de back-end para cenários como os seguintes:

• Distribua a carga para vários back-ends, que podem ter disjuntores de back-end individuais.
• Migre a carga de um conjunto de back-ends para outro conjunto para atualização (implantação azul-verde).

Opções de balanceamento de carga

O Gerenciamento de API dá suporte às seguintes opções de balanceamento de carga para pools de back-end:

Reconhecimento de sessão

Com qualquer uma das opções de balanceamento de carga anteriores, você pode habilitar o reconhecimento de sessão (afinidade de sessão) para garantir que todas as solicitações de um usuário específico durante uma sessão acessem o mesmo back-end no pool. O Gerenciamento de API define um cookie de ID de sessão para manter o estado da sessão. Essa opção é útil, por exemplo, em cenários com sistemas de suporte, como assistentes de chat de IA ou outros agentes de conversa, para rotear solicitações da mesma sessão para o mesmo destino.

Gerenciar cookies para reconhecimento de sessão

Quando você usa o reconhecimento de sessão, o cliente deve manipular cookies adequadamente. O cliente precisa armazenar o valor do Set-Cookie 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, para o caso da API de Assistentes (um recurso do Azure OpenAI no Microsoft Foundry Models), o cliente precisa guardar o ID da sessão, extrair o ID do thread do corpo, guardar 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 do 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 do Gerenciamento de API myAPIM está configurado com um pool de back-end. Os exemplos de back-end no pool são denominados backend-1 e backend-2. Ambos os back-ends estão no grupo de prioridade mais alta; dentro do grupo, back-end-1 tem um peso maior do que back-end-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 de Desenvolvedor 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 forem iguais. Se você se deparar com essa limitação, siga as instruções no artigo Limitação de solicitação de Gerenciamento de API de encadeamento automático no modo de rede virtual interna no blog da Tech Community.
• Atualmente, você pode configurar apenas uma regra para um disjuntor de back-end.

Conteúdo relacionado

• Blog: Usar o disjuntor do 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.
• Início Rápido Criar um pool de back-end no Gerenciamento de API do Azure usando o Bicep para balancear carga de solicitações do OpenAI
• Veja Gerenciamento de API do Azure como uma fonte da Grade de Eventos para obter informações sobre eventos da Grade de Eventos que o gateway gera quando um disjuntor é acionado ou redefinido. Use esses eventos para tomar medidas antes que os problemas de back-end aumentem.