Publicar APIs do Microsoft Azure Data Manager for Energy em um gateway de API seguro
O Gerenciamento de API do Azure serve como um intermediário crucial entre aplicativos cliente e APIs de back-end. Ele facilita o acesso dos clientes aos serviços, ocultando os detalhes técnicos e dando às organizações controle sobre a segurança da API.
Ao publicar APIs do Azure Data Manager for Energy por meio do Gerenciamento de API do Azure, você pode usar o recurso Azure Data Manager for Energy Private Link para tráfego privado e remover completamente o acesso público direto à sua instância.
Este artigo descreve como configurar o Gerenciamento de API do Azure para proteger as APIs do Azure Data Manager for Energy.
Pré-requisitos
Você precisa dos seguintes componentes, ferramentas e informações disponíveis para concluir este passo a passo:
Uma rede virtual com duas sub-redes disponíveis, uma para o ponto de extremidade privado do Azure Data Manager for Energy e outra para a injeção de rede virtual do Azure API Management.
Azure Data Manager for Energy configurado com link privado implantado na sub-rede.
Gerenciamento de API do Azure provisionado e implantado na rede virtual usando injeção de rede virtual. Selecione Modo externo ou consulte a seção Outras opções para Modo interno .
Um editor de código, como o Visual Studio Code , para modificar as especificações OpenAPI do Azure Data Manager for Energy para cada uma das APIs que estão sendo publicadas.
Transfira as especificações OpenAPI do Azure Data Manager for Energy a partir do repositório GitHub adme-samples . Navegue até o diretório rest-apis e selecione a versão apropriada para seu aplicativo.
No registro do aplicativo para o aplicativo Azure Data Manager for Energy que foi usado no momento do provisionamento, observe a ID do Locatário e a ID do Cliente:
Preparar a instância de gerenciamento de API
Use as seguintes etapas para fazer alterações de configuração em sua instância de Gerenciamento de API do Azure:
No painel Todos os recursos, escolha a instância de Gerenciamento de API do Azure usada para este passo a passo.
Navegue até a página Configurações de produtos escolhendo-a no agrupamento de configurações da API:
Na página Produtos, selecione o botão Adicionar para criar um novo Produto. Os Produtos de Gerenciamento de API do Azure permitem que você crie um agrupamento de APIs com acoplamento flexível que pode ser governado e gerenciado em conjunto. Criamos um Produto para as nossas APIs do Azure Data Manager for Energy.
Na página Adicionar produto, insira os valores descritos na tabela a seguir para criar o produto.
Definição valor Nome a Apres. "Azure Data Manager for Energy Product" ID "Adme-produto" Description Insira uma descrição que indique aos desenvolvedores quais APIs estamos agrupando Publicado Marque esta caixa para publicar o Produto que criamos Exige subscrição Marque esta caixa para fornecer autorização básica para nossas APIs Requer aprovação Opcionalmente, selecione se deseja que um administrador analise e aceite ou rejeite tentativas de assinatura deste produto. Se não for selecionada, as tentativas de subscrição são aprovadas automaticamente. Limite da contagem de subscrições Opcionalmente, limite a contagem de várias assinaturas simultâneas. Termos legais Opcionalmente, defina os termos de uso do produto que os assinantes devem aceitar para usar o produto. APIs Podemos ignorar esse recurso. Associamos APIs mais adiante neste artigo Selecione Criar para criar o novo produto.
Quando a criação do produto estiver concluída, o portal retornará à página Produtos. Selecione nosso produto recém-criado Azure Data Manager for Energy Product para ir para a página de recursos do produto. Selecione o item de menu Configuração de políticas no menu de configurações.
No painel Processamento de entrada, selecione o <ícone /> , que permite modificar as políticas do produto. Você adiciona três conjuntos de políticas para melhorar a segurança da solução:
- Valide o Entra ID Token para garantir que solicitações não autenticadas sejam capturadas no gateway de API
- Quota e Limite de Taxa para controlar a taxa de pedidos e o total de pedidos/dados transferidos
- Definir Cabeçalho para remover cabeçalhos retornados por APIs de back-end, que podem revelar detalhes confidenciais a possíveis agentes mal-intencionados
Adicione a seguinte política validate-azure-ad-token à nossa configuração dentro das tags de entrada e abaixo da tag base . Certifique-se de atualizar o modelo com os detalhes do aplicativo Microsoft Entra ID anotados nos pré-requisitos.
<validate-azure-ad-token tenant-id="INSERT_TENANT_ID"> <client-application-ids> <application-id>INSERT_APP_ID</application-id> </client-application-ids> </validate-azure-ad-token>Abaixo da política validate-azure-ad-token , adicione as seguintes políticas de cota e limite de taxa. Atualize os valores de configuração da política conforme apropriado para seus consumidores.
<rate-limit calls="20" renewal-period="90" remaining-calls-variable-name="remainingCallsPerSubscription"/> <quota calls="10000" bandwidth="40000" renewal-period="3600" />Para a seção de saída do editor de políticas e sob a marca base , adicione as seguintes políticas de cabeçalho de conjunto.
<set-header name="x-envoy-upstream-service-time" exists-action="delete" /> <set-header name="x-internal-uri-pattern" exists-action="delete" />Selecione Salvar para confirmar as alterações.
Navegue de volta para o recurso de Gerenciamento de API no portal do Azure. Selecione o item de menu Backends e selecione o botão + Adicionar .
No modal Back-end, insira os valores descritos na tabela a seguir para criar o back-end.
Definição Valor Nome "Adme-Backend" Description Insira uma descrição que indique aos desenvolvedores que esse back-end está relacionado às APIs do Azure Data Manager for Energy Type URL personalizado URL de tempo de execução Insira seu _ex de URI do Azure Data Manager for Energy. https://INSERT_ADME_NAME.energy.azure.com/Validar cadeia de certificados Selecionado Validar nome do certificado Selecionado 
Selecione Criar para criar o back-end. Esse back-end recém-criado será usado na próxima seção quando publicarmos APIs.
Importar APIs do Azure Data Manager for Energy
Use as seguintes etapas para importar, configurar e publicar APIs do Azure Data Manager for Energy no gateway de Gerenciamento de API do Azure:
Navegue de volta para a instância de Gerenciamento de API do Azure usada na última seção.
Selecione o item de menu APIs no menu e, em seguida, selecione o botão + Adicionar API .
Selecione OpenAPI sob o título Criar a partir da definição .
Na janela modal de especificação Criar a partir da OpenAPI , selecione a alternância Completa .
Localize as especificações OpenAPI que você baixou como parte dos pré-requisitos e abra a especificação de esquema usando o editor de código de sua escolha. Procure a palavra "servidor" e anote a URL do servidor no arquivo ex. /api/schema-service/v1/.
Selecione Selecionar um arquivo e selecione a especificação da API de esquema . Quando o upload é concluído, a janela modal carrega alguns valores da especificação.
Para os outros campos, insira os valores descritos na tabela a seguir:
Definição Value Incluir parâmetros de consulta necessários em modelos de operação Selecionado Nome a apresentar Insira um nome para exibição que faça sentido para desenvolvedores de aplicativos, por exemplo, Azure Data Manager for Energy Schema Service Nome O Gerenciamento de API sugere um nome com caixa de kebab. Opcionalmente, o nome pode ser alterado, mas deve ser exclusivo para a instância Description A especificação OpenAPI pode definir uma descrição, se assim for, a descrição é preenchida automaticamente. Opcionalmente, atualize a descrição de acordo com seu caso de uso. Esquema do URL Selecione "Ambos" Sufixo do URL de API Insira um sufixo para todas as APIs do Azure Data Manager for Energy (ex. adme). Em seguida, insira o URL do servidor a partir da etapa 5. O valor final deve ser parecido com /adme/api/schema-service/v1/. Um sufixo nos permite estar em conformidade com clientes existentes e kits de desenvolvimento de software que normalmente se conectam diretamente às APIs do Azure Data Manager for Energy Etiquetas Opcionalmente, insira tags Produtos Selecione o produto "Azure Data Manager for Energy" criado na seção anterior Importante
Validar o sufixo URL da API, esta é uma causa comum de erros na publicação das APIs do Azure Data Manager for Energy
Selecione Criar para criar a fachada da API.
Selecione a fachada da API de esquema recém-criada na lista de APIs e selecione Todas as operações na lista de operações. No painel Processamento de entrada, selecione o <ícone /> para editar o documento de política.
Para configurar a API, adicione dois conjuntos de políticas:
- Definir o Serviço de Back-end para rotear solicitações para a instância do Azure Data Manager for Energy
- Reescreva o URI para remover o prefixo adme e compilar a solicitação para a API de back-end. Esta declaração de política usa expressões de política para adicionar dinamicamente o valor do modelo de URL da Operação atual à URL do servidor.
Anote a URL do servidor da etapa 5. Abaixo da tag base , na seção de entrada , insira as duas instruções de política a seguir.
<set-backend-service backend-id="adme-backend" /><!-- replace the '/api/schema-service/v1' with the server URL for this API specification you noted in step 5 --> <rewrite-uri template="@{return "/api/schema-service/v1"+context.Operation.UrlTemplate;}" />Selecione Salvar para confirmar as alterações.
Teste a API selecionando a operação GET Version info na lista de operações. Em seguida, selecione a guia Teste para navegar até o Console de Teste de Gerenciamento de API do Azure.
Insira os valores descritos na tabela a seguir. Gere um token de autenticação para o Azure Data Manager for Energy. Selecione Enviar para testar a API.
Definição Value ID da partição de dados A ID de partição de dados para sua instância do Azure Data Manager for Energy Produto Selecione o produto Azure Data Manager for Energy criado anteriormente Autorização "Portador" e o token de autenticação que gerou 
Se a API estiver configurada corretamente, você verá uma resposta HTTP 200 - OK semelhante à captura de tela. Caso contrário, verifique a seção Solução de problemas.
Repita as etapas acima para cada API do Azure Data Manager for Energy e a especificação associada.
Resolução de Problemas
Durante o teste de APIs por meio do Gerenciamento de API do Azure, se você encontrar erros, eles geralmente apontam para problemas de configuração. Com base no erro, revise as possíveis etapas de resolução.
| Código | Mensagem de Erro | Detalhes |
|---|---|---|
HTTP 401 Unauthorized |
Invalid Azure AD JWT |
Verifique se você tem um cabeçalho de autenticação válido para o Locatário e Aplicativo Cliente do Microsoft Entra ID para sua instância do Azure Data Manager for Energy. |
HTTP 401 Unauthorized |
Azure AD JWT not present |
Verifique se o cabeçalho de autenticação foi adicionado à sua solicitação de teste. |
HTTP 404 Not Found |
Esse erro normalmente significa que a solicitação para a API de back-end está sendo feita para a URL errada. Rastreie sua solicitação de API no Gerenciamento de API para entender qual URL é gerada para a solicitação de back-end e garantir que ela seja válida. Caso contrário, verifique novamente a política de regravação de url ou o back-end. | |
HTTP 500 Internal Server Error |
Internal server error |
Esse erro normalmente reflete um problema ao fazer solicitações para a API de back-end. Normalmente, nesse cenário, o problema está relacionado a serviços de nome de domínio (DNS). Verifique se há uma zona DNS privada configurada em sua rede virtual ou se sua resolução DNS personalizada tem os encaminhadores apropriados. Rastreie sua solicitação de API no Gerenciamento de API para entender qual solicitação de back-end foi feita e quais erros o Gerenciamento de API está relatando ao tentar fazer a solicitação. |
Outras considerações
Modo de rede virtual interna de Gerenciamento de API
O modo interno isola completamente o Gerenciamento de API do Azure em vez de expor os pontos de extremidade por meio do endereço IP público. Nessa configuração, as organizações podem garantir que todo o Azure Data Manager for Energy seja interno. Como o Azure Data Manager for Energy é uma solução de colaboração para trabalhar com parceiros e clientes, esse cenário pode não ser benéfico no estado em que se encontra.
App Gateway com firewall de aplicativos Web
Em vez de usar apenas o modo de rede virtual interna, muitas organizações optam por aplicar um mecanismo de proxy reverso seguro para expor a instância de Gerenciamento de API do Azure no modo interno a parceiros e clientes externos. A instância do modo interno permanece totalmente isolada com uma entrada rigidamente controlada que deve passar pelo proxy.
O Azure App Gateway é um serviço comum para usar como proxy reverso. O Gateway de Aplicativo do Azure também tem um recurso de firewall de aplicativo Web (WAF), que deteta ativamente possíveis ataques contra vulnerabilidades em seus aplicativos e APIs.
Configurando o Gerenciamento de API do Azure com um domínio personalizado
Outra característica comum dessa arquitetura é aplicar um domínio personalizado às APIs. Embora o Azure Data Manager for Energy não ofereça suporte a esse recurso, você pode configurar um domínio personalizado no Gerenciamento de API do Azure.
Um certificado para o domínio é um pré-requisito. No entanto, o Gerenciamento de API do Azure dá suporte à criação de certificados gerenciados gratuitos para seu domínio personalizado.