Partilhar via

Descubra APIs de sombra usando o Dev Proxy

  • Artigo

Usando o Centro de API do Azure, você cataloga APIs usadas em sua organização. Isso permite que você diga quais APIs você usa, onde a API está em seu ciclo de vida e quem contatar se houver problemas. Em resumo, ter um catálogo atualizado de APIs ajuda a melhorar a postura de governança, conformidade e segurança.

Ao criar seu aplicativo, especialmente se você estiver integrando novos cenários, pode estar usando APIs que não estão registradas na Central de APIs do Azure. Essas APIs são chamadas de APIs sombra. As APIs de sombra são APIs que não estão registadas na sua organização. Podem ser APIs que ainda não estão registadas ou podem ser APIs que não se destinam a ser utilizadas na sua organização.

Uma maneira de verificar APIs de sombra é usando o Dev Proxy. O Dev Proxy é um simulador de API que interceta e analisa solicitações de API de aplicativos. Um recurso do Dev Proxy é verificar se as solicitações de API intercetadas pertencem a APIs registradas no Centro de APIs.

Captura de ecrã de uma linha de comandos a mostrar o Proxy de Desenvolvimento a verificar se os pedidos de API registados estão registados no Centro de API do Azure.

Antes de começar

Para detetar APIs de sombra, você precisa ter uma instância da Central de APIs do Azure com informações sobre as APIs que você usa em sua organização. Se você ainda não criou um, consulte Guia de início rápido: criar sua central de API. Além disso, você precisa instalar o Dev Proxy.

Copiar informações do Centro de API

Na página Visão geral da instância do Centro de API do Azure, copie o nome da instância da Central de APIs, o nome do grupo de recursos e a ID da assinatura. Você precisa dessas informações para configurar o Proxy de Desenvolvimento ApiCenterOnboardingPlugin para que ele possa se conectar à sua instância do Centro de API do Azure.

Captura de ecrã da página de descrição geral do Centro de API do Azure com várias propriedades realçadas.

Configurar proxy de desenvolvimento

Para verificar se seu aplicativo está usando APIs de sombra, você precisa habilitar o ApiCenterOnboardingPlugin no arquivo de configuração do Proxy de Desenvolvimento. Para criar um relatório de APIs que seu aplicativo usa, adicione um repórter.

Habilite o botão ApiCenterOnboardingPlugin

devproxyrc.json No arquivo, adicione a seguinte configuração:

{
  "$schema": "https://raw.githubusercontent.com/microsoft/dev-proxy/main/schemas/v0.19.0/rc.schema.json",
  "plugins": [
    {
      "name": "ApiCenterOnboardingPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll",
      "configSection": "apiCenterOnboardingPlugin"
    }
  ],
  "urlsToWatch": [
    "https://jsonplaceholder.typicode.com/*"
  ],
  "apiCenterOnboardingPlugin": {
    "subscriptionId": "00000000-0000-0000-0000-000000000000",
    "resourceGroupName": "demo",
    "serviceName": "contoso-api-center",
    "workspaceName": "default",
    "createApicEntryForNewApis": false
  }
}

No , resourceGroupNamee serviceName propriedades, forneça as informações sobre sua instância do subscriptionIdCentro de API do Azure.

urlsToWatch Na propriedade, especifique as URLs que seu aplicativo usa.

Gorjeta

Use a extensão Dev Proxy Toolkit Visual Studio Code para gerenciar facilmente a configuração do Dev Proxy.

Adicionar um repórter

O ApiCenterOnboardingPlugin produz um relatório de APIs que seu aplicativo está usando. Para exibir esse relatório, adicione um repórter ao arquivo de configuração do Proxy de Desenvolvimento. Dev Proxy oferece vários repórteres. Neste exemplo, você usa o repórter de texto simples.

Atualize seu devproxyrc.json arquivo com uma referência ao repórter de texto simples:

{
  "$schema": "https://raw.githubusercontent.com/microsoft/dev-proxy/main/schemas/v0.19.0/rc.schema.json",
  "plugins": [
    {
      "name": "ApiCenterOnboardingPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll",
      "configSection": "apiCenterOnboardingPlugin"
    },
    {
      "name": "PlainTextReporter",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll"
    }
  ],
  "urlsToWatch": [
    "https://jsonplaceholder.typicode.com/*"
  ],
  "apiCenterOnboardingPlugin": {
    "subscriptionId": "00000000-0000-0000-0000-000000000000",
    "resourceGroupName": "demo",
    "serviceName": "contoso-api-center",
    "workspaceName": "default",
    "createApicEntryForNewApis": false
  }
}

Verifique se seu aplicativo está usando APIs de sombra

Para verificar se seu aplicativo está usando APIs de sombra, conecte-se à sua assinatura do Azure, execute o Proxy de Desenvolvimento e permita que ele intercete solicitações de API do seu aplicativo. Em seguida, o Proxy de Desenvolvimento compara as informações sobre as solicitações de API com as informações da Central de API do Azure e relata quaisquer APIs que não estejam registradas na Central de APIs.

Ligar à sua subscrição do Azure

O Proxy de Desenvolvimento usa informações do Centro de API do Azure para determinar se seu aplicativo está usando APIs de sombra. Para obter essas informações, ele precisa de uma conexão com sua assinatura do Azure. Você pode se conectar à sua assinatura do Azure de várias maneiras.

Executar proxy de desenvolvimento

Depois de se conectar à sua assinatura do Azure, inicie o Dev Proxy. Se você iniciar o Dev Proxy da mesma pasta onde o devproxyrc.json arquivo está localizado, ele carregará automaticamente a configuração. Caso contrário, especifique o caminho para o arquivo de configuração usando a --config-file opção.

Quando o Proxy de Desenvolvimento é iniciado, ele verifica se pode se conectar à sua assinatura do Azure. Quando a conexão é bem-sucedida, você vê uma mensagem semelhante a:

 info    Plugin ApiCenterOnboardingPlugin connecting to Azure...
 info    Listening on 127.0.0.1:8000...

Hotkeys: issue (w)eb request, (r)ecord, (s)top recording, (c)lear screen
Press CTRL+C to stop Dev Proxy

Pressione r para começar a gravar solicitações de API do seu aplicativo.

Utilizar a aplicação

Use seu aplicativo como faria normalmente. O Dev Proxy interceta as solicitações de API e armazena informações sobre elas na memória. Na linha de comando em que o Proxy de Desenvolvimento é executado, você verá informações sobre as solicitações de API feitas pelo seu aplicativo.

 info    Plugin ApiCenterOnboardingPlugin connecting to Azure...
 info    Listening on 127.0.0.1:8000...

Hotkeys: issue (w)eb request, (r)ecord, (s)top recording, (c)lear screen
Press CTRL+C to stop Dev Proxy

◉ Recording... 

 req   ╭ GET https://jsonplaceholder.typicode.com/posts
 api   ╰ Passed through

 req   ╭ DELETE https://jsonplaceholder.typicode.com/posts/1
 api   ╰ Passed through

Verificar APIs de sombra

Pare a gravação pressionando s. O Proxy de Desenvolvimento se conecta à instância do Centro de API e compara as informações sobre solicitações com as informações do Centro de API.

 info    Plugin ApiCenterOnboardingPlugin connecting to Azure...
 info    Listening on 127.0.0.1:8000...

Hotkeys: issue (w)eb request, (r)ecord, (s)top recording, (c)lear screen
Press CTRL+C to stop Dev Proxy

◉ Recording... 

 req   ╭ GET https://jsonplaceholder.typicode.com/posts
 api   ╰ Passed through

 req   ╭ DELETE https://jsonplaceholder.typicode.com/posts/1
 api   ╰ Passed through
○ Stopped recording
 info    Checking if recorded API requests belong to APIs in API Center...
 info    Loading APIs from API Center...
 info    Loading API definitions from API Center...

Quando o Dev Proxy conclui sua análise, ele cria um relatório em um arquivo nomeado ApiCenterOnboardingPlugin_PlainTextReporter.txt com o seguinte conteúdo:

New APIs that aren't registered in Azure API Center:

https://jsonplaceholder.typicode.com:
  DELETE https://jsonplaceholder.typicode.com/posts/1

APIs that are already registered in Azure API Center:

GET https://jsonplaceholder.typicode.com/posts

APIs de sombra integradas automaticamente

O ApiCenterOnboardingPlugin pode não apenas detetar APIs de sombra, mas também integrá-las automaticamente ao Centro de APIs. Para integrar automaticamente APIs de sombra, no arquivo de configuração do Proxy de Desenvolvimento, atualize o createApicEntryForNewApis para true.

{
  "$schema": "https://raw.githubusercontent.com/microsoft/dev-proxy/main/schemas/v0.19.0/rc.schema.json",
  "plugins": [
    {
      "name": "ApiCenterOnboardingPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll",
      "configSection": "apiCenterOnboardingPlugin"
    },
    {
      "name": "PlainTextReporter",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll"
    }
  ],
  "urlsToWatch": [
    "https://jsonplaceholder.typicode.com/*"
  ],
  "apiCenterOnboardingPlugin": {
    "subscriptionId": "00000000-0000-0000-0000-000000000000",
    "resourceGroupName": "demo",
    "serviceName": "contoso-api-center",
    "workspaceName": "default",
    "createApicEntryForNewApis": true
  }
}

Quando você executa o Proxy de Desenvolvimento com createApicEntryForNewApis definido como true, ele cria automaticamente novas entradas de API no Centro de APIs do Azure para as APIs de sombra que deteta.

Captura de tela da Central de APIs mostrando uma API recém-integrada.

APIs de sombra integradas automaticamente com especificações OpenAPI

Quando você opta por integrar automaticamente APIs de sombra ao Centro de APIs, você pode fazer com que o Dev Proxy gere a especificação OpenAPI para a API. A integração de APIs com especificações OpenAPI acelera a integração de pontos de extremidade ausentes e fornece as informações necessárias sobre a API. Quando o deteta que o ApiCenterOnboardingPlugin Dev Proxy criou uma nova especificação OpenAPI, ele a associa à API integrada correspondente no Centro de APIs.

Para gerar automaticamente especificações OpenAPI para APIs integradas, atualize a configuração do Dev Proxy para incluir o OpenApiSpecGeneratorPlugin.

{
  "$schema": "https://raw.githubusercontent.com/microsoft/dev-proxy/main/schemas/v0.19.0/rc.schema.json",
  "plugins": [
    {
      "name": "OpenApiSpecGeneratorPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll"
    },
    {
      "name": "ApiCenterOnboardingPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll",
      "configSection": "apiCenterOnboardingPlugin"
    },
    {
      "name": "PlainTextReporter",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll"
    }
  ],
  "urlsToWatch": [
    "https://jsonplaceholder.typicode.com/*"
  ],
  "apiCenterOnboardingPlugin": {
    "subscriptionId": "00000000-0000-0000-0000-000000000000",
    "resourceGroupName": "demo",
    "serviceName": "contoso-api-center",
    "workspaceName": "default",
    "createApicEntryForNewApis": true
  }
}

Importante

O Dev Proxy executa plugins na ordem em que são registrados na configuração. Você precisa registrar o OpenApiSpecGeneratorPlugin primeiro para que ele possa criar especificações OpenAPI antes das ApiCenterOnboardingPlugin novas APIs integradas.

Quando você executa o Proxy de Desenvolvimento com essa configuração, ele cria automaticamente novas entradas de API no Centro de APIs do Azure para as APIs de sombra que deteta. Para cada nova API, o Dev Proxy gera uma especificação OpenAPI e a associa à API integrada correspondente no Centro de APIs.

 info    Plugin ApiCenterOnboardingPlugin connecting to Azure...
 info    Listening on 127.0.0.1:8000...

Hotkeys: issue (w)eb request, (r)ecord, (s)top recording, (c)lear screen
Press CTRL+C to stop Dev Proxy

◉ Recording... 

 req   ╭ GET https://jsonplaceholder.typicode.com/posts
 api   ╰ Passed through

 req   ╭ DELETE https://jsonplaceholder.typicode.com/posts/1
 api   ╰ Passed through
○ Stopped recording
 info    Creating OpenAPI spec from recorded requests...
 info    Created OpenAPI spec file jsonplaceholder.typicode.com-20240614104931.json
 info    Checking if recorded API requests belong to APIs in API Center...
 info    Loading APIs from API Center...
 info    Loading API definitions from API Center...
 info    New APIs that aren't registered in Azure API Center:

https://jsonplaceholder.typicode.com:
  DELETE https://jsonplaceholder.typicode.com/posts/1
 info    Creating new API entries in API Center...
 info      Creating API new-jsonplaceholder-typicode-com-1718354977 for https://jsonplaceholder.typicode.com...
 info    DONE

Captura de ecrã do Centro de API do Azure a mostrar uma API recentemente integrada com uma especificação OpenAPI.

Resumo

Usando o Dev Proxy e seu ApiCenterOnboardingPlugin, você pode verificar se seu aplicativo está usando APIs sombra. O plug-in analisa as solicitações de API do seu aplicativo e relata todas as solicitações de API que não estão registradas na Central de APIs do Azure. O plug-in permite que você integre facilmente APIs ausentes ao Centro de APIs. Ao combinar o ApiCenterOnboardingPlugin plugin com o OpenApiSpecGeneratorPlugin, você pode gerar automaticamente especificações OpenAPI para as APIs recém-integradas. Você pode executar essa verificação manualmente ou integrar com seu pipeline de CI/CD para garantir que seu aplicativo esteja usando APIs registradas antes de liberá-lo para produção.

Mais informações