Publicar APIs do Gerenciador de Dados do Microsoft Azure para Energia 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. Isso 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 as APIs do Gerenciador de Dados do Azure para Energia por meio do Gerenciamento de API do Azure, você pode usar o recurso Link Privado do Gerenciador de Dados do Azure para Energia 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 Gerenciador de Dados do Azure para Energia.

Pré-requisitos

Você precisa dos seguintes componentes, ferramentas e informações disponíveis para concluir esse passo a passo:

• Uma rede virtual com duas sub-redes disponíveis, uma para o ponto de extremidade privado do Gerenciador de Dados do Azure para Energia e a outra para a injeção de rede virtual do Gerenciamento de API do Azure.

• Gerenciador de Dados do Azure para Energia configurado com link privado implantado na sub-rede.

• O Gerenciamento de API do Azure é provisionado e implantado na rede virtual usando a injeção de rede virtual. Selecione o modo Externo ou confira a seção Outras opções para o modo Interno.

• Um editor de código, como o Visual Studio Code, para modificar as especificações OpenAPI do Gerenciador de Dados do Azure para Energia para cada uma das APIs que estão sendo publicadas.

• Baixe as especificações do OpenAPI do Gerenciador de Dados do Azure para Energia 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 do Gerenciador de Dados do Azure para Energia que foi usado no momento do provisionamento, observe a ID do locatário e a ID do cliente:

  

Preparar a instância do Gerenciamento de API

Use as etapas a seguir para fazer alterações na configuração de sua instância do Gerenciamento de API do Azure:

1. No painel Todos os recursos, escolha a instância do Gerenciamento de API do Azure usada para esse passo a passo.

2. Navegue até a página Configurações de produtos selecionando-a no agrupamento de configurações de API:

   

3. 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 flexível de APIs que podem ser controladas e gerenciadas em conjunto. Criamos um produto para nossas APIs do Gerenciador de Dados do Azure para Energia.

4. Na página Adicionar produto, insira os valores descritos na tabela a seguir para criar o produto.

   

   Configuração	Valor
   Nome de Exibição	"Produto do Gerenciador de Dados do Azure para Energia"
   ID	"adme-product"
   Descrição	Insira uma descrição que indique aos desenvolvedores quais APIs estão sendo agrupadas
   Publicado	Marque essa caixa para publicar o produto que criamos
   Exige assinatura	Marque essa caixa para fornecer autorização básica para nossas APIs
   Requer aprovação	Opcionalmente, selecione se você quer que um administrador revise e aceite ou rejeite tentativas de assinatura desse produto. Se não for selecionado, as tentativas de assinatura serão automaticamente aprovadas.
   Limite de contagem de assinaturas	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. Associaremos APIs mais adiante neste artigo

5. Selecione Criar para criar o produto.

6. Quando a criação do produto estiver concluída, o portal levará você de volta à página Produtos. Selecione nosso produto recém-criado, o Produto do Gerenciador de Dados do Azure para Energia, para acessar a página Recursos do produto. Selecione o item de menu de configuração de Políticas no menu de configurações.

   

7. No painel Processamento de entrada, selecione o ícone </>, que permite modificar as políticas do produto. Adicione três conjuntos de políticas para aumentar a segurança da solução:

   • Validar o Token do Entra ID para garantir que solicitações não autenticadas sejam capturadas no gateway de API
   • Cota e Limite de Taxa para controlar a taxa de solicitações e o total de solicitações/dados transferidos
   • Definir Cabeçalho para remover cabeçalhos retornados por APIs de back-end que podem revelar detalhes confidenciais a possíveis atores mal-intencionados

8. Adicione a seguinte política validate-azure-ad-token à nossa configuração dentro das marcas de entrada e abaixo da marca de base. Atualize o modelo com os detalhes do aplicativo Microsoft Entra ID mencionados 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>
   

9. 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" />
   

10. Na seção de saída do editor de políticas e na marca de base, adicione as seguintes políticas de definir cabeçalho.

    <set-header name="x-envoy-upstream-service-time" exists-action="delete" />
    <set-header name="x-internal-uri-pattern" exists-action="delete" />
    

11. Selecione Salvar para confirmar suas alterações.

    

12. Navegue de volta para o recurso de Gerenciamento de API no portal do Azure. Selecione o item de menu Back-ends e selecione o botão + Adicionar.

    

13. No modal Back-end, insira os valores descritos na tabela a seguir para criar o back-end.

    Configuração	Valor
    Nome	"adme-backend"
    Descrição	Insira uma descrição que indique aos desenvolvedores que esse back-end está relacionado às APIs do Gerenciador de Dados do Azure para Energia
    Tipo	URL personalizada
    URL do Runtime	Digite seu URI _ex do Gerenciador de Dados do Azure para Energia. https://INSERT_ADME_NAME.energy.azure.com/
    Validar cadeia de certificados	Verificado
    Validar nome do certificado	Verificado

    

14. Selecione Criar para criar o back-end. Esse backend recém-criado será usado na próxima seção quando publicarmos APIs.

Importar APIs do Gerenciador de Dados do Azure para Energia

Use as etapas a seguir para importar, configurar e publicar APIs do Gerenciador de Dados do Azure para Energia no gateway do Gerenciamento de API do Azure:

1. Navegue de volta para a instância do Gerenciamento de API do Azure usada na última seção.

2. Selecione o item de menu APIs no menu e, em seguida, selecione o botão + Adicionar API.

3. Selecione OpenAPI sob o título Criar a partir da definição.

   

4. Na janela modal Criar a partir da especificação do OpenAPI, selecione a opção Completo.

5. Localize as especificações do OpenAPI que você baixou como parte dos pré-requisitos e abra a especificação Esquema usando o editor de código de sua preferência. Procure a palavra "servidor" e anote a URL do servidor no arquivo ex. /api/schema-service/v1/.

6. Selecione Selecionar um arquivo e selecione a especificação da API de Esquema. Quando o upload for concluído, a janela modal carregará alguns valores da especificação.

7. Para os outros campos, insira os valores descritos na tabela a seguir:

   Configuração	Valor
   Incluir os parâmetros de consulta necessários nos modelos de operação	Verificado
   Nome de exibição	Insira um nome de exibição que faça sentido para os desenvolvedores de aplicativos ex. Serviço de Esquema do Gerenciador de Dados do Azure para Energia
   Nome	O Gerenciamento de API sugere um nome com base em kebab. Opcionalmente, o nome pode ser alterado, mas deve ser exclusivo para a instância
   Descrição	A especificação do OpenAPI pode definir uma descrição; nesse caso, a descrição é preenchida automaticamente. Opcionalmente, atualize a descrição de acordo com seu caso de uso.
   Esquema de URL	Selecione "Ambos"
   Sufixo da URL da API	Insira um sufixo para todas as APIs do Gerenciador de Dados do Azure para Energia (ex. adme). Em seguida, insira a URL do servidor da etapa 5. O valor final deve ser semelhante a /adme/api/schema-service/v1/. Um sufixo nos permite estar em conformidade com os clientes e kits de desenvolvimento de software existentes que normalmente se conectam diretamente às APIs do Gerenciador de Dados do Azure para Energia
   Marcações	Opcionalmente, insira marcas
   Produtos	Selecione o produto "Gerenciador de Dados do Azure para Energia" criado na seção anterior

   Importante

   Valide o sufixo da URL da API, pois essa é uma causa comum de erros na publicação das APIs do Gerenciador de Dados do Azure para Energia

8. Selecione Criar para criar a fachada da API.

   

9. 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 da política.

   

10. Para configurar a API, adicione dois conjuntos de políticas:

    • Defina o Serviço de Back-end para rotear as solicitações para a instância do Gerenciador de Dados do Azure para Energia
    • Reescreva o URI para remover o prefixo adme e crie a solicitação para a API de back-end. Essa instruçã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 nosso servidor.

11. Anote a URL do servidor da etapa 5. Abaixo da marca de 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;}" />
    

12. Selecione Salvar para confirmar suas alterações.

13. 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 do Gerenciamento de API do Azure.

14. Insira os valores descritos na tabela a seguir. Gere um token de autenticação para seu Gerenciador de Dados do Azure para Energia. Selecione Enviar para testar a API.

    Configuração	Valor
    data-partition-id	O ID da partição de dados para sua instância do Gerenciador de Dados do Azure para Energia
    Product	Selecione o produto do Gerenciador de Dados do Azure para Energia criado anteriormente
    Autorização	"Portador" e o token de autenticação que você gerou

    

15. 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.

16. Repita as etapas acima para cada API do Gerenciador de Dados do Azure para Energia e a especificação associada.

Soluçã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, examine 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 do Microsoft Entra ID e o aplicativo cliente para sua instância do Gerenciador de Dados do Azure para Energia.
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 reescrita de url ou o back-end.
HTTP 500 Internal Server Error	Internal server error	Normalmente, esse erro reflete um problema ao fazer solicitações à API de back-end. Normalmente, nesse cenário, o problema está relacionado aos serviços de nomes de domínio (DNS). Verifique se há uma zona DNS privada configurada em sua rede virtual ou se sua resolução de 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 do 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 Gerenciador de Dados do Azure para Energia seja interno. Como o Gerenciador de Dados do Azure para Energia é uma solução de colaboração para trabalhar com parceiros e clientes, esse cenário pode não ser benéfico no estado atual.

Gateway de Aplicativo com firewall do aplicativo Web

Em vez de usar apenas o modo de rede virtual interno, muitas organizações optam por aplicar um mecanismo de proxy reverso seguro para expor a instância do 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 rigorosamente controlada que deve passar pelo proxy.

O Gateway de Aplicativo do Azure é um serviço comum a ser usado como proxy reverso. O Gateway de Aplicativo do Azure também tem um recurso de firewall do aplicativo Web (WAF), que detecta ativamente possíveis ataques contra vulnerabilidades em seus aplicativos e APIs.

Configuração do Gerenciamento de API do Azure com um domínio personalizado

Outro recurso comum dessa arquitetura é aplicar um domínio personalizado às APIs. Embora o Gerenciador de Dados do Azure para Energia 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 oferece suporte à criação de certificados gerenciados gratuitos para seu domínio personalizado.

Conteúdo relacionado

• Linha de base de segurança do Azure para Gerenciamento de API

• Linha de base de segurança do Azure para o Gerenciador de Dados do Azure para Energia

• Tutorial: Criar um gateway de aplicativo com um Firewall do Aplicativo Web usando o portal do Azure