Criar e gerenciar um espaço de trabalho no Gerenciamento de API do Azure

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

Configure um workspace para permitir que uma equipe de API gerencie e publique suas próprias APIs, fornecendo à equipe de plataforma de API as ferramentas para observar, governar e manter a plataforma de Gerenciamento de API. Depois de criar um espaço de trabalho e atribuir permissões, os colaboradores do workspace poderão criar e gerenciar suas próprias APIs, produtos, assinaturas e recursos relacionados.

Execute as etapas deste artigo para:

• Crie um espaço de trabalho do Gerenciamento de API associado ao gateway gerenciado padrão da instância ou a um gateway de espaço de trabalho novo ou existente.
• Opcionalmente, isole um gateway do espaço de trabalho em uma rede virtual do Azure.
• Atribua permissões ao espaço de trabalho.

Prerequisites

• Uma instância de Gerenciamento de API. Se você precisar de um, crie-o em uma camada com suporte.
• Função de proprietário ou colaborador no grupo de recursos em que a instância de Gerenciamento de API é implantada ou permissões equivalentes para criar recursos no grupo de recursos.
• (Opcional) Uma sub-rede em uma rede virtual nova ou existente do Azure para isolar o tráfego de entrada e de saída do gateway do espaço de trabalho. Para obter opções de configuração e requisitos, consulte Requisitos de recursos de rede para gateways de workspace.
• (Opcional, para associar o gateway gerenciado padrão ao espaço de trabalho) Um cliente REST para chamar a API REST do Gerenciamento de APIs.

Criar um espaço de trabalho e associá-lo ao gateway gerenciado padrão - API REST

Você pode criar um workspace que encaminha o tráfego da API pelo gateway gerenciado padrão do serviço, em vez de pelo gateway do workspace. Essa opção evita o custo extra e a complexidade de um recurso de gateway separado. O tráfego de API é roteado por meio do nome de host padrão do serviço (por exemplo, <service-name>.azure-api.net).

Use o Workspace – Criar ou atualizar a API REST para criar um workspace.

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/workspaces/{workspaceId}?api-version=2024-05-01
Authorization: Bearer {token}
Content-Type: application/json

{
  "properties": {
    "displayName": "my workspace",
    "description": "Workspace using default managed gateway",
    "serveOn": "workspaceAndDefault"
  }
}

Substituir:

• {subscriptionId} pela sua ID de assinatura do Azure
• {resourceGroupName} com o nome do grupo de recursos da instância de Gerenciamento de API
• {serviceName} com o nome da instância de Gerenciamento de API
• {workspaceId} com um identificador único de espaço de trabalho (alfanumérico, com hífens permitidos)

Uma resposta bem-sucedida retorna HTTP 201 Created com o recurso de workspace. Por padrão, o workspace roteia o tráfego de API por meio do nome de host padrão do serviço.

Depois que o workspace for criado, prossiga para Atribuir usuários ao workspace – portal para configurar permissões de acesso.

Criar um espaço de trabalho e associar um gateway do espaço de trabalho - portal

1. Entre no portal do Azure e vá até a sua instância do Gerenciamento de API.

2. No menu à esquerda, em APIs, selecione Workspaces>+ Adicionar.

3. Na guia Noções básicas, insira um Nome de exibição descritivo, Nome do recurso e Descrição opcional para o workspace. Selecione Próximo.

4. Na aba Gateway, configure as configurações do gateway do workspace.

   

   • Selecione Criar novo para criar um novo gateway de workspace ou selecione Usar existente para associar o workspace a um gateway existente que tenha outros workspaces implantados nele.

   • Se você optar por criar um novo gateway:

     • Em Detalhes do gateway, insira um nome de gateway e selecione o número de Unidades de escala. Os custos do gateway são baseados no número de unidades. Para obter mais informações, consulte preço de Gerenciamento de API.

     • Em Rede, selecione uma Configuração de rede para seu gateway de workspace.

       Important

       Planeje cuidadosamente a configuração de rede do workspace. Você não pode alterar a configuração de rede depois de criar o workspace.

     • Se você selecionar acesso público de entrada, acesso privado de saída (integração de rede virtual) ou acesso privado de entrada, acesso privado de saída (injeção de rede virtual), selecione uma rede virtual e uma sub-rede para isolar o gateway de workspace ou crie um novo. Para obter os requisitos de rede, confira os Requisitos de recursos de rede para gateways de workspace.

5. Selecione Próximo. Depois de concluir a validação, selecione Criar.

   Note

   A criação de uma nova porta de entrada do espaço de trabalho, caso selecionada, pode levar várias horas para ser concluída. Para acompanhar o progresso da implantação no portal do Azure, acesse o grupo de recursos do gateway. No menu esquerdo em Configurações, selecione Implantações.

Após a conclusão da implantação, o novo workspace aparece na lista na página Workspaces. Selecione o workspace para gerenciar suas configurações e recursos.

Atribuir usuários ao workspace - portal

Depois de criar um workspace, atribua permissões aos usuários para gerenciar os recursos do workspace. Cada usuário do workspace deve ter atribuídas tanto uma função RBAC do workspace com escopo de serviço quanto uma função RBAC com escopo do workspace, ou receber permissões equivalentes por meio de funções personalizadas.

Se o workspace usar um recurso de gateway de workspace, atribua também aos usuários do workspace uma função RBAC fornecida pelo Azure com escopo no gateway de workspace.

• Para obter uma lista de funções internas de workspace, veja Como usar o controle de acesso baseado em função no Gerenciamento de API.
• Para ver as etapas para atribuir uma função, veja Atribuir funções do Azure usando o portal.

Atribuir uma função com escopo de serviço

1. Entre no portal do Azure e vá até a sua instância do Gerenciamento de API.

2. No menu à esquerda, selecione Controle de acesso (IAM)>+ Adicionar.

3. Atribuir uma das seguintes funções com escopo de serviço a cada membro do espaço de trabalho:

   • Desenvolvedor de API do Espaço de Trabalho de Serviço de Gerenciamento de API
   • Gerente de Produtos da API do Workspace do Serviço de Gerenciamento de API

Atribuir uma função no escopo do espaço de trabalho

1. No menu da instância do Gerenciamento de API em APIs, selecione Workspaces> e o nome do workspace que você criou.

2. Na janela Workspace, selecione Controle de acesso (IAM)>+ Adicionar.

3. Atribua um dos seguintes papéis com escopo no espaço de trabalho aos membros do espaço de trabalho para que eles possam gerenciar as APIs do espaço de trabalho e outros recursos:

   • Leitor do Workspace do Gerenciamento de API
   • Contribuidor do Espaço de Trabalho de Gerenciamento de API
   • Desenvolvedor de API do Workspace de Gerenciamento de API
   • Gerente de Produtos da API do Workspace do Gerenciamento de API

Atribuir uma função com escopo de gateway

1. Entre no portal do Azure e vá até a sua instância do Gerenciamento de API.

2. No menu à esquerda, em APIs, selecione Workspaces> o nome do seu workspace.

3. No menu à esquerda do workspace, selecione Gateways e selecione o gateway do espaço de trabalho.

4. No menu à esquerda, selecione Controle de acesso (IAM)>+ Adicionar.

5. Atribua uma das seguintes funções a cada membro do workspace. No mínimo, atribua a função Leitor para exibir as configurações do gateway. Proprietários e Colaboradores podem gerenciar as configurações do gateway, incluindo o dimensionamento do gateway.

   • Owner
   • Contributor
   • Reader

Habilitar as configurações de diagnóstico para monitorar APIs do ambiente de trabalho.

Defina as configurações para coletar logs do Azure Monitor para o workspace e enviá-los para um workspace do Log Analytics. A equipe do workspace pode monitorar suas próprias APIs enquanto a equipe da plataforma de API pode acessar logs centralizados para a instância de Gerenciamento de API. Confira o seguinte diagrama:

Para coletar logs do Azure Monitor para o espaço de trabalho, você precisa de configurações de diagnóstico nos níveis do serviço e do espaço de trabalho:

1. Primeiro, habilite uma configuração de diagnóstico no nível de serviço para coleta de logs de gateway de Gerenciamento de API, se uma configuração ainda não estiver habilitada. Enviar logs para um workspace do Log Analytics. Para obter mais informações, consulte Definir configurações de diagnóstico para o Gerenciamento de API.

2. Em seguida, habilite uma configuração de diagnóstico no nível do workspace para enviar os logs do gateway do Gerenciamento de API para o mesmo workspace do Log Analytics. Essa configuração coleta logs de todos os gateways associados ao espaço de trabalho.

   Important

   Uma configuração de diagnóstico no nível do serviço configura o registro em log na instância de Gerenciamento de API, incluindo workspaces que têm uma configuração de diagnóstico no nível do workspace habilitada. Se você não ativar uma configuração de diagnóstico no nível do workspace, os logs do gateway do workspace não serão coletados nem agregados ao Log Analytics.

   Note

   Por padrão, os membros da equipe do espaço de trabalho atribuídos às funções RBAC internas do espaço de trabalho não têm permissões para editar as configurações de diagnóstico em um espaço de trabalho. A equipe da plataforma de API tem essas permissões.

Para definir uma configuração de diagnóstico de workspace para a coleção de logs de gateway no nível do workspace:

1. Entre no portal do Azure e vá até a sua instância do Gerenciamento de API.

2. No menu à esquerda, em APIs, selecione Workspaces> o nome do seu workspace.

3. No menu à esquerda dos workspaces, em Monitoramento, selecione Configurações de diagnóstico>+ Adicionar configuração de diagnóstico.

4. Na configuração de diagnóstico, insira ou selecione detalhes para a configuração:

   1. Nome da configuração de diagnóstico: insira um nome descritivo.
   2. Grupos de categorias: opcionalmente, faça uma seleção para seu cenário.
   3. Em Categorias, selecione Logs relacionados ao Gateway ApiManagement para coletar logs de gateway para APIs neste workspace.
   4. Em Detalhes do Destino, selecione para enviar logs para o mesmo workspace do Azure Log Analytics especificado na configuração de diagnóstico no nível do serviço e em outras configurações de diagnóstico no nível do workspace.
   5. Clique em Salvar.

Introdução ao seu workspace

Dependendo de sua função no workspace, os usuários podem ter permissões para criar APIs, produtos, assinaturas e outros recursos, ou podem ter acesso somente leitura a alguns ou a todos esses recursos.

Para começar a gerenciar, proteger e publicar APIs em um workspace, confira as diretrizes a seguir.

Conteúdo relacionado

• Saiba mais sobre workspaces no Gerenciamento de API do Azure.
• Usar uma rede virtual para proteger o tráfego de entrada ou de saída para o Gerenciamento de API do Azure