Gerenciamento de API federado com espaços de trabalho

APLICA-SE A: Básico v2 | Standard v2 | Premium | Premium v2

Este artigo fornece uma visão geral dos workspaces de Gerenciamento de API e como eles capacitam as equipes de desenvolvimento de API descentralizadas a gerenciar e transformar suas APIs em produtos em uma infraestrutura de serviço comum.

Por que as organizações devem federar o gerenciamento de API?

Hoje, as organizações enfrentam cada vez mais desafios no gerenciamento de uma proliferação de APIs. À medida que o número de APIs e equipes de desenvolvimento de API aumenta, a complexidade de gerenciá-las também aumenta. Essa complexidade pode levar ao aumento da sobrecarga operacional, aos riscos de segurança e à redução da agilidade. Por um lado, as organizações desejam estabelecer uma infraestrutura de API centralizada para garantir a governança, a segurança e a conformidade da API. Por outro lado, eles querem que suas equipes de API inovem e respondam rapidamente às necessidades dos negócios, sem a sobrecarga de gerenciar uma plataforma de API.

Um modelo federado de gerenciamento de API atende a essas necessidades. O gerenciamento de API federada permite o gerenciamento descentralizado de API por equipes de desenvolvimento com isolamento apropriado de planos de controle e dados, mantendo a governança centralizada, o monitoramento e a descoberta de API gerenciados por uma equipe de plataforma de API. Esse modelo supera as limitações de abordagens alternativas, como o gerenciamento de API totalmente centralizado pela equipe da plataforma ou o gerenciamento de API em silo por cada equipe de desenvolvimento.

O gerenciamento de API federada fornece:

• Governança e observabilidade de API centralizadas
• Um portal de desenvolvedor unificado para descoberta e integração de API eficazes
• Permissões administrativas segregadas entre equipes de API, aumentando a produtividade e a segurança
• Tempo de execução de API isolado entre as equipes de API, melhorando a confiabilidade, a resiliência e a segurança.

Como os workspaces habilitam o gerenciamento de API federada

No Gerenciamento de API do Azure, use workspaces para implementar o gerenciamento de API federada. Os workspaces funcionam como "pastas" em um serviço de Gerenciamento de API:

• Cada workspace contém APIs, produtos, assinaturas, valores nomeados e recursos relacionados. Confira a referência da API REST de Gerenciamento de API para obter uma lista completa de recursos e operações compatíveis com workspaces.
• O acesso das equipes aos recursos dentro de um workspace é gerenciado por meio do controle de acesso baseado em função (RBAC) do Azure, com funções internas ou personalizadas que podem ser atribuídas a contas do Microsoft Entra e delimitadas para um workspace.
• Cada workspace está associado a um ou mais gateways para encaminhar o tráfego da API para os serviços de back-end das APIs no workspace. Dependendo do nível de serviço e dos seus requisitos, um espaço de trabalho pode usar o gateway gerenciado padrão do serviço ou um ou mais gateways de espaço de trabalho.
• A equipe da plataforma pode aplicar políticas que abrangem APIs e produtos em workspaces para controlar o runtime de API na organização. Uma definição interna do Azure Policy (API Management policies should inherit parent scope policies using <base/>) permite que você audite ou imponha que essas políticas sejam aplicadas em todos os recursos do workspace.
• A equipe da plataforma pode implementar uma experiência centralizada de descoberta de API com um portal de desenvolvedores.
• Cada equipe de workspace pode reunir e analisar logs de recursos de gateway para monitorar as respectivas APIs de workspace, enquanto a equipe da plataforma tem acesso federado a logs em todos os workspaces no serviço do Gerenciamento de API, fornecendo supervisão, segurança e conformidade no ecossistema de API.

Embora os workspaces sejam gerenciados independentemente do serviço de Gerenciamento de API e de outros workspaces, intencionalmente, eles podem referenciar recursos específicos de nível de serviço. Consulte Workspaces e outros recursos de Gerenciamento de API, posteriormente neste artigo.

Visão geral do cenário de exemplo

Uma organização que gerencia APIs usando Gerenciamento de API do Azure pode ter várias equipes de desenvolvimento que desenvolvem, definem, mantêm e productam diferentes conjuntos de APIs. Usando workspaces, essas equipes podem usar o Gerenciamento de API para gerenciar, acessar e proteger suas APIs separadamente e independentemente do gerenciamento da infraestrutura de serviço.

O fluxo de trabalho a seguir mostra um processo de exemplo para criar e usar um workspace.

1. Uma equipe central da plataforma de API que gerencia a instância do API Management cria um workspace e atribui permissões aos colaboradores do workspace por meio de funções RBAC. Por exemplo, atribua permissões para criar ou ler recursos no workspace. A equipe cria ou associa um gateway de API ao workspace para rotear o tráfego da API.

2. Uma equipe central da plataforma de API usa ferramentas de DevOps para criar um pipeline de DevOps para APIs nesse workspace.

3. Os membros do workspace desenvolvem, publicam, produzem e mantêm APIs no workspace.

4. A equipe central da plataforma de API gerencia a infraestrutura do serviço, como monitoramento, resiliência e imposição de políticas de todas as APIs.

Gateway de workspace

Cada espaço de trabalho é configurado com um ou mais gateways para permitir a execução de APIs gerenciadas nesse espaço de trabalho. Dependendo do nível de serviço e dos seus requisitos, você pode usar o gateway gerenciado padrão do serviço e/ou um ou mais gateways de espaço de trabalho (recursos de gateway separados).

Gateway gerenciado padrão

Nos níveis v2, você pode configurar um workspace para rotear o tráfego de API por meio do gateway gerenciado padrão do serviço, além de um ou mais recursos de gateway do workspace separados. Quando um workspace usa o gateway gerenciado padrão:

• O tráfego de API é roteado por meio do nome de host padrão do serviço (por exemplo, <service-name>.azure-api.net).
• O espaço de trabalho compartilha a capacidade e a configuração do gateway com outros espaços de trabalho e APIs no nível do serviço.

Gateway de workspace

Um gateway de workspace é um recurso de Azure autônomo (workspace gateway premium) com a mesma funcionalidade principal do gateway gerenciado padrão.

Você gerencia os gateways do espaço de trabalho de forma independente do serviço de Gerenciamento de API e entre si. Elas permitem o isolamento do runtime entre workspaces ou casos de uso, o que aumenta a confiabilidade, a resiliência e a segurança da API. Eles também permitem associar problemas de tempo de execução aos espaços de trabalho.

• Para obter informações sobre o custo dos gateways de workspace, consulte os preços do Gerenciamento de API.
• Para obter uma comparação detalhada dos gateways de Gerenciamento de API, consulte a Visão geral dos gateways de Gerenciamento de API.

Associar workspaces a um gateway de workspace

Dependendo das necessidades da sua organização, você pode associar um workspace ou vários workspaces a um gateway de workspace.

• Um gateway de um espaço de trabalho tem determinadas configurações, como rede virtual, capacidade de escalonamento e nome do host, bem como recursos de computação alocados, incluindo CPU, memória e recursos de rede.
• Todos os workspaces implantados em um gateway compartilham os recursos de configuração e computação.
• Bugs em uma API ou tráfego anormal podem causar esgotamento desses recursos, o que afeta todos os workspaces nesse gateway. Em outras palavras, quanto mais workspaces você implantar em um gateway, maior o risco de que uma API de um workspace tenha problemas de confiabilidade causados por uma API de outro workspace.
• Monitore o desempenho do gateway do espaço de trabalho usando métricas internas para acompanhar o uso da CPU e da memória.

Considere confiabilidade, segurança e custo ao escolher um modelo de implantação para workspaces.

• Atribuir um workspace ao seu próprio gateway de workspace dedicado para cargas de trabalho críticas – para maximizar a confiabilidade e a segurança da API, atribua cada workspace crítico a seu próprio gateway, evitando o uso compartilhado com outros workspaces.
• Equilibre a confiabilidade, a segurança e o custo - Associe vários espaços de trabalho a um gateway de espaço de trabalho (ou, se aplicável, ao gateway gerenciado padrão) para equilibrar a confiabilidade, a segurança e o custo de cargas de trabalho não críticas. Distribua workspaces em pelo menos dois gateways para ajudar a evitar que problemas, como esgotamento de recursos ou erros de configuração, afetem todas as APIs dentro da organização.
• Use gateways distintos para diferentes casos de uso – agrupe workspaces em um gateway de workspace com base em um caso de uso ou requisitos de rede. Por exemplo, você pode distinguir entre APIs internas e externas atribuindo-as a gateways separados, cada um com sua própria configuração de rede.
• Prepare-se para colocar em quarentena espaços de trabalho problemáticos - Use um proxy, como o Gateway de Aplicativo do Azure ou o Azure Front Door, diante de gateways de espaços de trabalho compartilhados para facilitar a migração de um espaço de trabalho que esteja causando esgotamento de recursos para um gateway diferente. Essa abordagem impede o impacto em outros workspaces que compartilham o gateway.

Nome do host do gateway do espaço de trabalho

Cada gateway de espaço de trabalho fornece um nome de host exclusivo para APIs gerenciadas em um espaço de trabalho associado. Os nomes de host padrão seguem o padrão <gateway-name>-<hash>.gateway.<region>.azure-api.net. Use o nome do host do gateway para rotear solicitações de API para as APIs do seu workspace.

Atualmente, os gateways de workspace não dão suporte a nomes de host personalizados. Você pode configurar o Gateway de Aplicativo do Azure ou o Azure Front Door com um nome de host personalizado na frente de um gateway de workspace.

Isolamento de rede para gateways de espaço de trabalho

Opcionalmente, você pode configurar um recurso de gateway de workspace em uma rede virtual privada para isolar o tráfego de entrada e saída. Se você configurar esse isolamento, o gateway de workspace deverá usar uma sub-rede dedicada na rede virtual.

Para obter requisitos detalhados, confira os Requisitos de recursos de rede para gateways de espaço de trabalho.

Dimensionar a capacidade dos gateways do espaço de trabalho

Gerencie a capacidade de um gateway de workspace adicionando ou removendo unidades de escala, semelhantes às unidades que você pode adicionar à instância de Gerenciamento de API em determinadas camadas de serviço. Os custos de um gateway de workspace são baseados no número de unidades selecionadas.

Disponibilidade regional de gateways do espaço de trabalho

Para obter uma lista atual de regiões em que os gateways do workspace estão disponíveis, consulte Disponibilidade de camadas v2 e gateways de workspace.

Limitações do workspace e do gateway do workspace

Restrições de espaços de trabalho

• Um workspace não pode ser associado a um gateway auto-hospedado
• APIs em workspaces não são cobertas pelo Defender para APIs
• Workspaces não dão suporte ao gerenciador de credenciais
• Os workspaces dão suporte apenas ao cache interno; não há suporte para cache externo
• Workspaces não dão suporte a APIs sintéticas do GraphQL
• Os workspaces não dão suporte à criação de APIs diretamente de recursos Azure, como Serviço OpenAI do Azure, Serviço de Aplicativo, Aplicativos de Funções e assim por diante no portal Azure
• Workspaces não dão suporte a servidores MCP
• As métricas de solicitação não podem ser divididas por workspace no Azure Monitor; todas as métricas do workspace são agregadas no nível do serviço
• Workspaces não oferecem suporte a certificados de CA
• Workspaces não dão suporte a identidades gerenciadas, incluindo recursos relacionados, como armazenar segredos em Azure Key Vault e usar a política authentication-managed-identity

Restrições do gateway do espaço de trabalho

As seguintes restrições se aplicam ao recurso de gateway do espaço de trabalho gerenciado. Eles não se aplicam ao usar workspaces no gateway gerenciado padrão do serviço.

• Os gateways de workspace não dão suporte a pontos de extremidade privados de entrada
• Os gateways de workspace não dão suporte a nomes de host personalizados
• Os workspaces só podem ser associados a gateways de workspace localizados na mesma região e assinatura do recurso de Gerenciamento de API

Herança de políticas globais em gateways de espaço de trabalho

Os gateways de espaço de trabalho executam toda a cadeia de políticas, incluindo a política global de nível de serviço (global.policy.xml). Esse comportamento significa que todas as políticas definidas no escopo global são avaliadas e executadas para chamadas de API processadas por gateways de workspace, assim como são para o gateway padrão. Esse comportamento é intencional e está de acordo com o modelo de avaliação de políticas do Gerenciamento de API, em que você aplica políticas hierarquicamente nos seguintes escopos: global (serviço) > workspace > produto > API > operação.

Recomendações para políticas globais com gateways de espaço de trabalho

• Examine sua política global para garantir que ela contenha apenas políticas destinadas a serem aplicadas em todos os gateways, incluindo gateways de espaço de trabalho.

• Se você precisar de comportamento diferente por gateway, use a política de escolha com context.Deployment.Gateway.Id a qual executar condicionalmente as políticas com base no gateway que processa a solicitação.

• Se você definir uma identidade gerenciada por autenticação no escopo global, mas o token não estiver disponível para APIs com escopo de workspace, mova a política para um escopo mais estreito (por exemplo, produto ou nível de API) em vez da política global.

Funções RBAC para workspaces

O RBAC do Azure é usado para configurar as permissões dos colaboradores do espaço de trabalho para ler e editar entidades do mesmo. Para obter uma lista de funções, veja Como usar o controle de acesso baseado em função no Gerenciamento de API.

Para gerenciar APIs e outros recursos no workspace, atribua funções a membros do workspace (ou permissões equivalentes por meio de funções personalizadas) que têm como escopo o serviço de Gerenciamento de API e o workspace. A função de escopo de serviço habilita a referência de recursos do nível de serviço a partir dos recursos do nível de espaço de trabalho. Por exemplo, organize um usuário em um grupo no nível do espaço de trabalho para controlar a API e a visibilidade do produto.

Se o workspace usar um gateway dedicado do workspace, os membros que gerenciam o gateway também deverão receber uma função com escopo no recurso de gateway do workspace.

Workspaces e outros recursos de Gerenciamento de API

Os workspaces são independentes para maximizar a segregação do acesso administrativo e do runtime da API. Para garantir maior produtividade e habilitar a governança, a observabilidade, a reutilização e a descoberta de API em toda a plataforma, existem várias exceções.

• Referências de recurso – os recursos em um workspace podem referenciar outros recursos no workspace e recursos selecionados no nível do serviço, como usuários, servidores de autorização ou grupos de usuários internos. Eles não podem referenciar recursos de outro workspace.

  Por motivos de segurança, você não pode referenciar recursos no nível do serviço a partir de políticas no nível do workspace (por exemplo, valores nomeados) nem por nomes de recursos, como backend-id na política set-backend-service.

  Important

  Todos os recursos em um serviço de Gerenciamento de API (por exemplo, APIs, produtos, marcas ou assinaturas) precisam ter nomes exclusivos, mesmo que estejam localizados em workspaces diferentes. Você não pode ter recursos do mesmo tipo e com o mesmo nome de recurso Azure no mesmo workspace, em outros workspaces ou no nível do serviço.

• Portal do desenvolvedor – os workspaces são um conceito administrativo e não são exibidos como tal para os consumidores do portal do desenvolvedor, inclusive por meio da interface do usuário do portal do desenvolvedor e da API subjacente. Você pode publicar APIs e produtos em um workspace no portal do desenvolvedor, assim como APIs e produtos no nível do serviço.

  Note

  O Gerenciamento de API dá suporte à atribuição de servidores de autorização definidos no nível do serviço a APIs em workspaces.

Migrar de workspaces em versão prévia

Se você criou workspaces em versão prévia no Gerenciamento de API do Azure e deseja continuar usando-os, migre seus workspaces para a versão em disponibilidade geral associando um gateway de workspace a cada workspace.

Para obter detalhes e saber mais sobre outras alterações que podem afetar seus workspaces em versão prévia, consulte Alterações interruptivas em workspaces (março de 2025).

Como excluir um workspace

Ao excluir um workspace usando a interface do portal do Azure, você também exclui todos os seus recursos secundários (APIs, produtos e assim por diante) e um gateway dedicado do workspace, se houver um associado. Isso não exclui a instância de Gerenciamento de API ou outros workspaces.

Conteúdo relacionado

• Criar um espaço de trabalho
• As alterações interruptivas nos espaços de trabalho – junho de 2024
• Alterações significativas em espaços de trabalho – março de 2025
• Limites – workspaces de Gerenciamento de API