Usar o Gerenciamento de API do Azure em uma solução multilocatária

O Gestão de API do Azure é um gateway de API abrangente 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 principais recursos do Gerenciamento de API que são úteis para soluções multilocatário.

Modelos de isolamento

O Gerenciamento de API normalmente é implantado como um componente compartilhado com uma única instância que atende solicitações para vários locatários. No entanto, com base em seu modelo de locação, há muitas maneiras de implantar o Gerenciamento de API. Este artigo pressupõe que implemente a 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 roteia solicitações para seus aplicativos de API back-end.

Modelos de isolamento de instância compartilhada

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

Aplicação back-end dedicada

Se você implantar aplicativos back-end distintos para cada locatário, poderá implantar uma única instância de Gerenciamento de API e rotear o tráfego para o back-end de locatário correto para cada solicitação. Essa abordagem requer que você configure o Gerenciamento de API com os nomes de host 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.

Como requer uma pesquisa extra, essa abordagem pode não ser dimensionada para um grande número de locatários que compartilham uma única instância de Gerenciamento de API. Também pode haver alguma sobrecarga de desempenho quando se consulta o back-end do utilizador. No entanto, o tamanho dessa sobrecarga de desempenho depende de como você projeta essa pesquisa.

Aplicativo back-end multilocatário compartilhado

Em cenários em que seus locatários compartilham um aplicativo back-end comum, o processo de roteamento do Gerenciamento de API é simplificado porque você pode rotear todas as solicitações para um único back-end. Se você usar domínios curinga 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, não há impacto no desempenho de decisões de roteamento personalizadas.

Instância para cada inquilino

Em alguns cenários, você pode implantar uma instância de Gerenciamento de API para cada locatário. Recomendamos esta abordagem apenas se tiver poucos inquilinos ou se tiver requisitos rigorosos de conformidade que o impeça de partilhar qualquer infraestrutura entre inquilinos. Por exemplo, se você implantar uma rede virtual dedicada para cada locatário, provavelmente também precisará implantar uma instância de Gerenciamento de API dedicada para cada locatário.

Ao implementar uma instância da Gestão de API, é necessário considerar as limitações do serviço, incluindo quaisquer limites que possam ser aplicados ao número de instâncias de Gestão de API em uma subscrição ou região do Azure.

As instâncias de locatário único geralmente têm uma configuração de roteamento mínima, pois você pode rotear todas as solicitações para um único back-end. Esse cenário não requer decisões de roteamento personalizadas, portanto, não há impacto adicional no desempenho. No entanto, você normalmente incorre em um custo de recursos mais alto do que se implantar uma instância compartilhada. Se precisarem implementar instâncias de inquilino único, considerem se os gateways alojados localmente permitem reutilizar recursos de computação específicos do inquilino que já implementou.

Recursos de gerenciamento de API que suportam multilocação

A Gestão de API usa políticas para permitir flexibilidade. Você pode personalizar como as solicitações são validadas, roteadas e processadas quando você usa políticas. E quando você projeta uma solução multilocatária com o Gerenciamento de API, usa políticas para implementar muitos de seus recursos.

Identificar locatários em solicitações de entrada

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 para esse locatário específico e mais ninguém.

A Gestão de API fornece assinaturas que pode utilizar para autenticar pedidos. Essas assinaturas usam uma chave de assinatura 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 Gerenciamento de API para seus próprios identificadores de locatário ou cliente. As subscrições estão totalmente integradas no portal do programador. Para a maioria das soluções, é uma boa prática 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 dentro de uma política personalizada que você define:

• Use um componente personalizado da URL, como um subdomínio, caminho ou cadeia de caracteres 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 de cliente. Da mesma forma, dada a URL https://tenant1.contoso.com/productsde entrada, você pode extrair o subdomínio, tenant1. Para usar essa abordagem, considere analisar o caminho ou a cadeia de caracteres de consulta da Context.Request.Url propriedade.

• Use um cabeçalho de solicitação. Por exemplo, seus aplicativos cliente podem adicionar um cabeçalho personalizado X-TenantID às solicitações. Para usar essa abordagem, considere a Context.Request.Headers leitura da coleção.

• 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 esta abordagem, use a validate-jwt política e defina a output-token-variable-name propriedade 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. Adotando essa abordagem, você pode criar uma lógica de mapeamento de locatário personalizada para mapear um identificador lógico de locatário para uma URL específica ou para 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 de suas solicitações. Para atenuar esse efeito, é recomendável usar o cache para reduzir o número de chamadas para a API externa. Você pode usar as políticas cache-store-value e cache-lookup-value para implementar uma abordagem de cache. Certifique-se de invalidar seu cache com cada locatário adicionado, removido ou movido que afete a pesquisa de back-end.

Valores com nome

A Gestão de API suporta valores definidos, que são configurações personalizadas que podem ser utilizadas em todas as suas políticas. Por exemplo, você pode usar um valor nomeado para armazenar a 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 precisar atualizar o URL, você pode atualizá-lo em um único lugar.

Autenticar solicitações de entrada

As solicitações de API feitas ao gateway de Gerenciamento de API geralmente precisam ser autenticadas. O Gerenciamento de API fornece vários métodos de autenticação de solicitações de entrada para o gateway, incluindo OAuth 2.0 e certificados de cliente. Considere os tipos de credenciais que você deve oferecer suporte e onde elas devem ser validadas. Por exemplo, considere se a validação deve acontecer no Gerenciamento de API, em seus aplicativos back-end ou em ambos os locais.

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

Rota para back-ends específicos do locatário

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

Respostas em cache ou outros dados

O Gerenciamento de API tem um poderoso recurso de cache que você pode usar para armazenar em cache respostas HTTP inteiras ou quaisquer outros dados. Por exemplo, pode usar a cache para mapeamentos de inquilino, se utilizar lógica personalizada ou consultar o mapeamento de um serviço externo.

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

APIs de modelo de linguagem grande

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

Cache semântico

Se suas APIs estiverem na frente dos modelos do Azure OpenAI, considere o uso de 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 cache semântico
• Respostas de cache para solicitações de API do Azure OpenAI
• Obter respostas em cache de solicitações de API do Azure OpenAI

Você deve particionar o cache por locatário usando o vary-by elemento para que os prompts e as respostas sejam isolados para o locatário ao qual 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 tokens para modelos de linguagem grandes

Use limites baseados em tokens no gateway de IA para limitar o uso de cada locatário, não apenas para solicitações individuais. Quando você usa 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 de Modelo de IA do Azure, use a política llm-token-limit. Para obter mais informações, consulte Política de limite de token.

Selecione uma chave exclusiva para o locatário, como uma declaração de ID de assinatura ou token de ID de locatário, para garantir que os limites isolem efetivamente cada locatário. O uso do token é rastreado independentemente em cada gateway, região ou espaço de trabalho, 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" />

O exemplo a seguir limita 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 a Gestão de API para configurar os seus próprios domínios personalizados para o gateway de API e o portal do programador. Em algumas camadas, pode-se configurar domínios curinga ou vários nomes de domínio totalmente qualificados (FQDNs).

Você também pode usar o Gerenciamento de API junto com um serviço como o Azure Front Door. Nesse tipo de configuração, o Azure Front Door frequentemente lida com 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 de Gerenciamento de API para processamento posterior, considere usar o X-Forwarded-Host cabeçalho da solicitação ou use as regras da Porta da Frente do Azure para passar 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 ajudá-lo a mitigar o problema do vizinho barulhento. Você também pode usar limites de taxa para impor a qualidade do serviço e diferenciar entre diferentes níveis de preço.

Use o Gerenciamento de API para impor limites de taxa específicos do locatário. Se você usar assinaturas específicas do locatário, considere usar a política de cotas para impor 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 Limites baseados em tokens para modelos de linguagem grandes.

Rentabilização

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

Gestão da capacidade

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

Algumas instâncias multilocatárias podem consumir mais capacidade do que instâncias de locatário único, como se você usar muitas políticas para rotear solicitações para back-ends de locatários diferentes. Considere cuidadosamente o planejamento de capacidade e planeje dimensionar a capacidade de sua instância se você ver seu uso aumentar. 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 multirregionais

A Gestão de API suporta desdobramentos em várias regiões, o que significa que pode desdobrar um único recurso lógico de Gestão de API em várias regiões do Azure sem ter de replicar a 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 de Gerenciamento de API 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 de Gerenciamento de API totalmente isoladas, também poderá optar por implantar recursos independentes de Gerenciamento de API em regiões diferentes. Essa abordagem separa o plano de gerenciamento para cada instância de Gerenciamento de API.

Contribuidores

A Microsoft mantém este artigo. Os seguintes colaboradores escreveram este artigo.

Principais autores:

• John Downs | Engenheiro de Software Principal, Azure Patterns & Practices
• Daniel Scott-Raynsford | Arquiteto de Soluções para Parceiros Sénior, Enterprise Partner Solutions

Outros contribuidores:

• Arsen Vladimirskiy - Brasil | Engenheiro de Clientes Principal

Para ver perfis não públicos do LinkedIn, faça login no LinkedIn.

Recursos relacionados

• Abordagens arquitetônicas para integração de locatários e acesso a dados em soluções multilocatárias
• Arquitete soluções multilocatárias no Azure
• Lista de verificação para arquitetar e desenvolver soluções multi-inquilino no Azure
• Modelos de arrendamento a considerar para uma solução multilocatária