Usar o Azure API Management em uma solução multilocatário

OGerenciamento de API do Azure é um abrangente gateway de API e proxy reverso para APIs. Ele fornece muitos recursos que são úteis para aplicativos focados em API, incluindo cache, simulação de resposta e um portal do desenvolvedor. Este artigo resume alguns dos recursos principais do API Management que são úteis para soluções multilocatário.

Modelos de isolamento

O API Management normalmente é implantado como um componente compartilhado com uma única instância que atende a solicitações para vários locatários. No entanto, com base no seu modelo de locação, existem muitas maneiras de implantar o Gerenciamento de API. Este artigo parte do pressuposto de que você implanta sua solução usando carimbos de implantação.

Normalmente, a maneira como o Gerenciamento de API é usado permanece consistente em diferentes modelos de isolamento. Esta seção se concentra nas diferenças de custo e complexidade entre os modelos de isolamento e como cada abordagem encaminha solicitações para seus aplicativos de API de back-end.

Modelos de isolamento de instância compartilhada

É comum compartilhar uma instância do API Management entre vários locatários, o que ajuda a reduzir o custo e a complexidade de implantação e gerenciamento. Os detalhes de como você pode compartilhar uma instância do API Management dependem de como você atribui locatários a aplicativos de API de back-end.

Aplicativo de back-end de locatário único

Se você implantar aplicativos de back-end diferentes para cada locatário, poderá implantar uma única instância do API Management e rotear o tráfego para o back-end de locatário correto para cada solicitação. Essa abordagem exige que você configure o API Management com os nomes de host de back-end para cada locatário ou tenha outra maneira de mapear uma solicitação de entrada para o back-end do locatário correto.

Por requer uma pesquisa extra, pode não ser possível ampliar essa abordagem para um grande número de locatários que compartilhem uma única instância do Gerenciamento de API. Também pode haver alguma sobrecarga de desempenho quando você acessa o back-end do locatário. No entanto, o tamanho dessa sobrecarga de desempenho depende de como você estrutura essa pesquisa.

Aplicativo de back-end multilocatário compartilhado

Nos cenários em que os locatários compartilham um aplicativo de back-end comum, o processo de roteamento do API Management é simplificado porque você pode encaminhar todas as solicitações para um único back-end. Se você usar domínios curinga (wildcard) ou domínios emitidos pelo provedor, poderá alcançar uma escala quase ilimitada usando essa abordagem. Além disso, como as solicitações não precisam ser mapeadas para o back-end de um locatário, as decisões de roteamento personalizadas não impactam o desempenho.

Uma instância para cada locatário

Em alguns cenários, você pode implantar uma instância do Gerenciamento de API para cada locatário. Recomendamos essa abordagem somente se você tiver poucos locatários ou se tiver requisitos de conformidade estritos que o restrinjam de compartilhar qualquer infraestrutura entre locatários. Por exemplo, se você implantar uma rede virtual dedicada para cada locatário, provavelmente também precisará implantar uma instância dedicada do API Management para cada locatário.

Ao implantar uma instância do API Management, você precisa considerar os limites de serviço, incluindo quaisquer limites que possam se aplicar ao número de instâncias do API Management em uma assinatura ou região do Azure.

As instâncias de locatário único normalmente têm configuração mínima de roteamento porque você pode rotear todas as solicitações para um único back-end. Esse cenário não requer decisões de roteamento personalizadas e, portanto, não há impacto adicional no desempenho. No entanto, isso normalmente gera um custo de recursos mais alto do que a implantação de uma instância compartilhada. Se você precisar implantar instâncias de locatário único, avalie se os gateways auto-hospedados permitem que você reutilize recursos de computação específicos para o locatário que você já implantou.

Recursos do API Management que dão suporte à multilocação

API Management usa políticas para permitir a flexibilidade. Você pode personalizar como as solicitações são validadas, encaminhadas e processadas ao usar políticas. E ao projetar uma solução multilocatário com o API Management, você usa políticas para implementar muitos recursos.

Identificar os locatários em solicitações recebidas

Considere como você pode identificar o locatário apropriado em cada solicitação de entrada. Em uma solução multilocatário, é importante ter uma compreensão clara de quem está fazendo cada solicitação para que você retorne os dados desse locatário específico e de mais ninguém.

O serviço de API Management fornece assinaturas que você pode usar para autenticar solicitações. Essas subscrições usam uma chave de subscrição exclusiva que ajuda a identificar o assinante que está fazendo a solicitação. Se você optar por usar assinaturas, considere como mapear as assinaturas do API Management para seus próprios identificadores de locatário ou cliente. As assinaturas são totalmente integradas ao portal do desenvolvedor. Para a maioria das soluções, é útil usar assinaturas para identificar locatários.

Como alternativa, você pode identificar o locatário usando outros métodos. As abordagens de exemplo a seguir são executadas em uma política personalizada que você define:

• Use um componente personalizado do URL, como um subdomínio, caminho ou string de consulta. Por exemplo, na URL https://api.contoso.com/tenant1/products, você pode extrair a primeira parte do caminho, tenant1, e tratá-la como um identificador do locatário. Da mesma forma, dado o URL de entrada https://tenant1.contoso.com/products, você pode extrair o subdomínio, tenant1. Para usar essa abordagem, considere interpretar o caminho ou a string de consulta a partir da propriedade Context.Request.Url.

• Use um cabeçalho de solicitação Por exemplo, seus aplicativos cliente podem adicionar um cabeçalho personalizado TenantID às solicitações. Para usar essa abordagem, pense em ler sobre a coleta de Context.Request.Headers.

• Extraia declarações de um JSON Web Token (JWT). Por exemplo, você pode ter uma declaração personalizada tenantId em um JWT que seu provedor de identidade emite. Para usar essa abordagem, utilize a política validate-jwt e defina a propriedade output-token-variable-name para que sua definição de política possa ler os valores do token.

• Pesquise identificadores de locatário dinamicamente. Você pode se comunicar com um banco de dados ou serviço externo enquanto a solicitação está sendo processada. Ao adotar essa abordagem, você pode criar uma lógica de mapeamento de locatário personalizado para mapear um identificador de locatário lógico para uma URL específica ou obter mais informações sobre um locatário. Para aplicar essa abordagem, use a política de solicitação de envio .

  É provável que essa abordagem aumente a latência das solicitações. Para atenuar esse efeito, é recomendado usar o cache para diminuir o número de chamadas para a API externa. Você pode usar as políticas de cache-store-value e cache-lookup-value para implementar uma abordagem de armazenamento em cache. Não deixe de invalidar seu cache com cada locatário adicionado, removido ou movido que afeta a pesquisa de back-end.

Valores nomeados

O Gerenciamento de API é compatível com valores nomeados, que são opções de configuração personalizadas que você pode usar em todas as suas políticas. Por exemplo, você pode usar um valor nomeado para armazenar o URL de back-end de um locatário e, em seguida, reutilizar esse mesmo valor em vários locais dentro de suas políticas. Se você precisar atualizar o URL, poderá atualizá-lo em um único lugar.

Autenticar solicitações de entrada

As solicitações de API feitas ao gateway do API Management geralmente precisam ser autenticadas. O Gerenciamento de API oferece diversos métodos de autenticação de solicitações recebidas pelo gateway, incluindo OAuth 2.0 e certificados de cliente. Considere os tipos de credenciais que você deve suportar e onde elas devem ser validadas. Por exemplo, considere se a validação deve ocorrer no API Management, em seus aplicativos de back-end ou nos dois locais.

Para obter mais informações, consulte Autenticação e autorização para APIs no Gerenciamento de API.

Encaminhar para back-ends específicos de um locatário

Ao usar o API Management como um componente compartilhado, talvez seja necessário encaminhar solicitações de API de entrada para diferentes back-ends específicos do locatário. Esses back-ends podem estar em stamps de implantação diferentes ou podem ser aplicativos diferentes dentro de um único stamp. Para personalizar o roteamento em uma definição de política, use a política set-backend-service. Você precisa especificar o novo URL base para o qual a solicitação deve ser redirecionada.

Armazenar em cache respostas ou outros dados

O API Management tem um recurso de cache poderoso que você pode usar para armazenar em cache respostas HTTP inteiras ou quaisquer outros dados. Por exemplo, você pode usar o cache para mapeamentos de locatários se usar uma lógica personalizada ou se pesquisar o mapeamento a partir de um serviço externo.

Use as políticas de cache-store-value e cache-lookup-value para implementar uma abordagem de armazenamento em cache.

APIs de grandes modelos de linguagem

Utilize os recursos do gateway de IA no Gerenciamento de APIs quando suas APIs chamarem grandes modelos de linguagem. Esses recursos ajudam você a controlar o custo, o desempenho e o isolamento em soluções multilocatários.

Cache semântico

Se suas APIs estiverem na frente de modelos do Azure OpenAI, considere usar o cache semântico no Gerenciamento de API para reduzir o custo e a latência para prompts repetidos ou quase duplicados.

Para obter mais informações, consulte os seguintes recursos:

• Habilitar o cache semântico
• Respostas de cache para solicitações da API openai do Azure
• Obter respostas armazenadas em cache de solicitações da API do Azure OpenAI

Você deve particionar o cache por locatário usando o elemento vary-by para que os prompts e respostas sejam isolados para o locatário a que se destinam. Coloque a lookup política no processamento de entrada e a store política no processamento de saída.

O exemplo a seguir mostra como as entradas de cache semântico são particionadas por ID ou chave de assinatura:

<!-- inbound -->
<azure-openai-semantic-cache-lookup
   score-threshold="0.05"
   embeddings-backend-id="embeddings-backend"
   embeddings-backend-auth="system-assigned">
   <vary-by>@(context.Subscription.Id)</vary-by>
   <!-- or: <vary-by>@(context.Subscription.Key)</vary-by> -->
</azure-openai-semantic-cache-lookup>

<!-- outbound -->
<azure-openai-semantic-cache-store duration="60" />

O exemplo a seguir particiona o cache semântico por declaração de locatário ou cabeçalho:

<!-- inbound; requires validate-jwt if using a claim -->
<azure-openai-semantic-cache-lookup
   score-threshold="0.05"
   embeddings-backend-id="embeddings-backend"
   embeddings-backend-auth="system-assigned">
   <vary-by>@(context.Principal?.Claims.GetValueOrDefault("tenantId", ""))</vary-by>
   <!-- Alternative using a custom header: -->
   <!-- <vary-by>@(context.Request.Headers.GetValueOrDefault("TenantID", ""))</vary-by> -->
</azure-openai-semantic-cache-lookup>

<!-- outbound -->
<azure-openai-semantic-cache-store duration="60" />

Limites baseados em token para modelos de linguagem grandes

Use limites baseados em token no gateway de IA para limitar o uso de cada locatário, não apenas para solicitações individuais. Ao usar back-ends do Azure OpenAI, use a política azure-openai-token-limit. Para back-ends compatíveis com OpenAI ou a API de Inferência do Modelo de IA do Azure, use a política llm-token-limit. Para obter mais informações, consulte a política de limite de token.

Selecione uma chave que seja exclusiva para o locatário, como uma ID de assinatura ou uma declaração de reivindicação de token de ID de locatário, para garantir que os limites isolem efetivamente cada locatário. O uso de token é acompanhado independentemente em cada gateway, região ou workspace e os contadores não são agregados em toda a instância.

O exemplo a seguir limita cada locatário a 60.000 tokens por minuto por assinatura:

<azure-openai-token-limit
   counter-key="@(context.Subscription.Id)"
   tokens-per-minute="60000"
   estimate-prompt-tokens="false" />

Os seguintes limites de exemplo por declaração de locatário ou cabeçalho:

<!-- Using a tenant claim; requires validate-jwt earlier in the pipeline -->
<azure-openai-token-limit
   counter-key="@(context.Principal?.Claims.GetValueOrDefault(&quot;tenantId&quot;, &quot;&quot;))"
   tokens-per-minute="60000"
   estimate-prompt-tokens="false" />

<!-- Or using a custom header populated by your edge/CDN/gateway -->
<azure-openai-token-limit
   counter-key="@(context.Request.Headers.GetValueOrDefault(&quot;TenantID&quot;, &quot;&quot;))"
   tokens-per-minute="60000"
   estimate-prompt-tokens="false" />

Domínios personalizados

Use o Gerenciamento de API para configurar seus próprios domínios personalizados para o gateway de API e o portal de desenvolvedores. Em algumas camadas, você pode configurar domínios curinga ou vários nomes de domínio totalmente qualificados (FQDNs).

Você também pode usar o API Management junto com um serviço como o Azure Front Door. Nesse tipo de configuração, o Azure Front Door frequentemente manipula domínios personalizados e certificados TLS (Transport Layer Security) e se comunica com o Gerenciamento de API usando um único nome de domínio. Se a URL original do cliente incluir informações de locatário que você precisa enviar para a instância do Gerenciamento de API para processamento posterior, pense em usar o cabeçalho de solicitação X-Forwarded-Hostregras do Azure Front Door para repassar as informações como um cabeçalho HTTP.

Limites de taxa

É comum aplicar cotas ou limites de taxa em uma solução multilocatário. Os limites de taxa podem ajudar você a mitigar o problema de vizinho barulhento. Você também pode usar limites de taxa para impor a qualidade do serviço e diferenciar tipos de preços.

Use o Gerenciamento de API para implementar limites de taxa específicos para cada locatário. Se você usar assinaturas específicas para cada locatário, pense em usar a política de cota para implementar uma cota para cada assinatura. Como alternativa, considere usar a política de cota por chave para impor cotas usando qualquer outra chave de limite de taxa, como um identificador de locatário obtido da URL de solicitação ou de um JWT.

Para obter mais informações, consulte os limites baseados em token para modelos de linguagem grandes.

Monetização

A documentação do Gerenciamento de API fornece orientações abrangentes sobre como monetizar APIs, incluindo uma implementação de exemplo. As abordagens de monetização combinam muitos recursos do API Management para que os desenvolvedores possam publicar uma API, gerenciar assinaturas e cobrar com base em diferentes modelos de uso.

Gerenciamento de capacidade

Uma instância de Gerenciamento de API dá suporte a uma quantidade específica de capacidade, que representa os recursos disponíveis para processar suas solicitações. Ao usar políticas complexas ou implantar mais APIs na instância, você consome mais capacidade. Você pode gerenciar a capacidade de uma instância de várias maneiras, como comprando mais unidades. Você também pode escalar dinamicamente a capacidade da sua instância.

Algumas instâncias multilocatário podem consumir mais capacidade do que instâncias de locatário único, como se você usasse muitas políticas para encaminhar solicitações para back-ends de locatários diferentes. Considere o planejamento de capacidade com cuidado e planeje escalonar a capacidade da instância se você perceber um aumento no uso. Você também deve testar o desempenho de sua solução para entender suas necessidades de capacidade com antecedência.

Para obter mais informações sobre como dimensionar o Gerenciamento de API, consulte Atualizar e dimensionar uma instância de Gerenciamento de API.

Implantações em várias regiões

O Gerenciamento de API dá suporte a implantações multirregião, o que significa que você pode implantar um único recurso lógico do Gerenciamento de API em várias regiões do Azure sem precisar replicar sua configuração em recursos separados. Esse recurso é especialmente útil quando você distribui ou replica sua solução globalmente. Você pode implantar efetivamente uma frota de instâncias do API Management em várias regiões, o que permite o processamento de solicitações de baixa latência e gerenciá-las como uma única instância lógica.

No entanto, se você precisar de instâncias do API Management totalmente isoladas, também poderá optar por implantar recursos independentes do API Management em regiões diferentes. Essa abordagem separa o plano de gerenciamento para cada instância do API Management.

Colaboradores

A Microsoft mantém este artigo. Os colaboradores a seguir escreveram este artigo.

Principais autores:

• John Downs | Principal Engenheiro de Software, Padrões do Azure & Práticas
• Daniel Scott-Raynsford | Arquiteto de Soluções de Parceiro Sênior, Soluções de Parceiros Empresariais

Outro colaborador:

• Arsen Vladimirskiy | Engenheiro Principal de Clientes

Para ver perfis não públicos no LinkedIn, entre no LinkedIn.

Recursos relacionados

• Abordagens arquitetônicas para integração de locatários e acesso a dados em soluções multilocatários
• Arquitetar soluções multilocatário no Azure
• Lista de verificação para arquitetar e criar soluções multilocatário no Azure
• Modelos de locação a serem levados em conta para uma solução multilocatário