Compartilhar via

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.

Ao importar determinadas APIs, o Gerenciamento de API configura o back-end de API automaticamente. Por exemplo, o Gerenciamento de API configura o serviço Web de backend ao importar:

O Gerenciamento de API também dá suporte para o uso de outros recursos do Azure como back-end de API. Por exemplo:

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 do Gerenciamento de API para manter os segredos no Azure Key Vault se os valores nomeados estiverem configurados para autenticação de parâmetros de consulta ou cabeçalhos.
  • 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 essas entidades de back-end no portal do Azure ou no uso de 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 , faça o seguinte:
    1. Insira um nome para o back-end e uma descrição opcional.
    2. Selecione um tipo de hospedagem de back-end, por exemplo, 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, adicione uma regra de disjuntor, altere a URL do runtime ou adicione 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, faça o seguinte:

  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 configurada 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. Exemplo: 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.

Observação

Atribua também à identidade gerenciada as permissões apropriadas ou uma função RBAC para acessar o serviço de back-end. Por exemplo, se o back-end for um serviço do OpenAI do Azure, você poderá atribuir a identidade gerenciada à função Cognitive Services User.

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

Observação

Alternativamente, você pode utilizar base-url. Normalmente, o formato é https://backend.com/api. Evite adicionar uma barra no final para evitar configurações incorretas. Normalmente, o base-url e o valor do ponto de extremidade HTTP(S) no back-end devem corresponder para habilitarem a integração perfeita entre front-end e back-end. Observe que as instâncias de Gerenciamento de API acrescentam o nome do serviço de back-end ao base-url.

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.

Observação

  • Atualmente, não há suporte para os disjuntores de back-end no nível Consumo do Gerenciamento de API.
  • Devido à natureza distribuída da arquitetura do Gerenciamento de API, as regras de desarme de disjuntor são aproximadas. Instâncias diferentes do gateway não são sincronizadas e aplicarão regras de disjuntor com base nas informações da mesma instância.
  • Atualmente, apenas uma regra pode ser configurada para um disjuntor 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.

  1. No portal do Azure, acesse sua instância de Gerenciamento de API.
  2. No menu à esquerda, selecione APIs>Back-ends> no seu back-end.
  3. Na página de back-end, selecione Configurações>Configurações do disjuntor>Adicionar novo.
  4. Na página Criar novo disjuntor , configure a regra:
    • Nome da regra: insira um nome para a regra, como myBackend.
    • Contagem de falhas: Insira 3.
    • Intervalo de falha: deixe o valor padrão de 1 hora.
    • Intervalo de códigos de status de falha: selecione 500 a 599.
    • Duração da viagem: deixe o valor padrão de 1 hora.
    • Verifique o cabeçalho 'Retry-After' na resposta HTTP: Selecione True (Aceitar).

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 o seguinte:

  • 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 para atualização (implantação azul-verde).

Observação

  • Você pode incluir até 30 back-ends em um pool.
  • Devido à natureza distribuída da arquitetura do Gerenciamento de API, o balanceamento de carga do back-end é aproximado. Instâncias diferentes do gateway não são sincronizadas e farão o balanceamento de carga com base nas informações da mesma instância.

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:

Opção balanceamento de carga Descrição
Round robin As solicitações são distribuídas uniformemente entre os back-ends no pool por padrão.
ponderada Pesos são atribuídos aos back-ends no pool e as requisições são distribuídas com base no peso relativo de cada back-end. Útil para cenários como implantações blue-green.
Baseado em prioridade Os back-ends são organizados em grupos de prioridade. As solicitações são enviadas primeiro para grupos de prioridade mais alta; em um grupo, as solicitações são distribuídas uniformemente ou de acordo com os pesos atribuídos.

Observação

Os back-ends nos grupos de prioridade mais baixa só serão usados quando todos os back-ends nos grupos de prioridade mais alta não estiverem disponíveis porque as regras do disjuntor foram acionadas.

Reconhecimento de sessão

Com qualquer uma das opções de balanceamento de carga anteriores, opcionalmente, habilite 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 sejam direcionadas para 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.

Observação

O reconhecimento de sessão em pools com balanceamento de carga está sendo lançado primeiro para o grupo de atualizaçãoantecipada do Gateway de IA.

Gerenciar cookies para reconhecimento de sessão

Ao usar 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, no caso da API de Assistentes (um recurso da OpenAI do Azure nos modelos da Fábrica de IA do Azure), o cliente precisa manter a ID da sessão, extrair a ID do thread do corpo da mensagem, armazenar o par e enviar o cookie correto a 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.

  1. No portal do Azure, acesse sua instância de Gerenciamento de API.
  2. No menu à esquerda, selecione APIs>Back-ends> no seu back-end.
  3. Na página Back-ends , selecione a guia Balanceador de carga .
  4. Selecione + Criar um novo pool.
  5. Na página Criar novo pool com balanceamento de carga, faça o seguinte:
    • Nome: insira um nome para o pool, como myBackendPool.
    • Descrição: opcionalmente, insira uma descrição.
    • Adicionar backends ao pool: Selecione um ou mais backends para adicionar ao pool.
    • Peso e prioridade de back-end: selecione Personalizar peso e prioridade para configurar o peso e a prioridade de cada back-end no pool. Por exemplo, se você adicionou dois backends nomeados backend-1 e backend-2, defina o peso de backend-1 para 3 e o peso de backend-2 para 1, e defina a prioridade de ambos os backends para 1.
    • Selecione Criar.

Limitações

Conteúdo relacionado