Compartilhar via

Descubra as APIs Sombra usando o Proxy de Desenvolvimento

  • Artigo

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

Ao criar seu aplicativo, principalmente se você estiver integrando novos cenários, talvez esteja usando APIs que não estão registradas no Centro de API do Azure. Essas APIs são chamadas de APIs de sombra. APIs de sombra são APIs que não estão registradas em sua organização. Elas podem ser APIs que ainda não foram registradas ou podem ser APIs que não devem ser usadas em sua organização.

Uma maneira de verificar se há APIs de sombra é usando o Dev Proxy. O Dev Proxy é um simulador de API que intercepta e analisa solicitações de API dos aplicativos. Um dos recursos do Dev Proxy é verificar se as solicitações de API interceptadas pertencem a APIs registradas no Centro de API.

Captura de tela de um prompt de comando mostrando o Dev Proxy verificando se as solicitações de API registradas estão registradas no Centro de API do Azure.

Antes de começar

Para detectar APIs de sombra, você precisa ter uma instância do Centro de API do Azure com informações sobre as APIs que você usa na sua organização. Se você ainda não criou um, consulte Início Rápido: criar seu centro 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 do Centro de API, o nome do grupo de recursos e a ID da assinatura. Você precisa dessas informações para configurar o ApiCenterOnboardingPlugin do Dev Proxy de forma que possa se conectar à sua instância do Centro de API do Azure.

Captura de tela da página de visão geral do Centro de API do Azure com várias propriedades destacadas.

Configurar o Dev Proxy

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

Habilitar o ApiCenterOnboardingPlugin

No arquivo devproxyrc.json, 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": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
    "resourceGroupName": "demo",
    "serviceName": "contoso-api-center",
    "workspaceName": "default",
    "createApicEntryForNewApis": false
  }
}

Nas propriedades subscriptionId, resourceGroupName e serviceName, forneça as informações sobre sua instância do Centro de API do Azure.

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

Dica

Use a extensão do Visual Studio Code do Kit de Ferramentas do Dev Proxy para gerenciar a configuração do Dev Proxy com facilidade.

Adicionar um gerador de relatórios

O ApiCenterOnboardingPlugin produz um relatório de APIs que o seu aplicativo está usando. Para ver esse relatório, adicione um gerador de relatórios ao arquivo de configuração do Dev Proxy. O Dev Proxy oferece vários geradores de relatórios. Nesse exemplo, você usa o gerador de relatórios em texto sem formatação.

Atualize seu arquivo devproxyrc.json com uma referência ao gerador de relatórios em texto sem formataçã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"
    },
    {
      "name": "PlainTextReporter",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll"
    }
  ],
  "urlsToWatch": [
    "https://jsonplaceholder.typicode.com/*"
  ],
  "apiCenterOnboardingPlugin": {
    "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
    "resourceGroupName": "demo",
    "serviceName": "contoso-api-center",
    "workspaceName": "default",
    "createApicEntryForNewApis": false
  }
}

Verificar se seu aplicativo está usando APIs de sombra

Para verificar se o seu aplicativo está usando APIs de sombra, conecte-se à sua assinatura do Azure, execute o Dev Proxy e permita que ele intercepte solicitações de API do seu aplicativo. Em seguida, o Dev Proxy compara as informações sobre as solicitações de API com as informações do Centro de API do Azure e de relatórios sobre quaisquer APIs que não estão registradas no Centro de API.

Conecte-se à sua assinatura do Azure

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

Executar o Dev Proxy

Após se conectar à sua assinatura do Azure, inicie o Dev Proxy. Se você iniciar o Dev Proxy na mesma pasta em que seu arquivo devproxyrc.json está localizado, a configuração será carregada automaticamente. Caso contrário, especifique o caminho para o arquivo de configuração usando a opção --config-file.

Quando é iniciado, o Dev Proxy verifica se consegue se conectar à sua assinatura do Azure. Se a conexão for bem-sucedida, você verá 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 iniciar o registro das solicitações de API a partir do seu aplicativo.

Usar seu aplicativo

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

 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

Interromper o registro pressionando s. O Dev Proxy se conecta à instância do Centro de API e compara as informações sobre as 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 termina sua análise, o Dev Proxy cria um relatório em um arquivo chamado 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

Além de detectar APIs de sombra, o ApiCenterOnboardingPlugin também as integra automaticamente ao Centro de API. Para integrar automaticamente as APIs de sombra, no arquivo de configuração do Dev Proxy, 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": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
    "resourceGroupName": "demo",
    "serviceName": "contoso-api-center",
    "workspaceName": "default",
    "createApicEntryForNewApis": true
  }
}

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

Captura de tela do Centro de API mostrando uma API recém-integrada.

APIs de sombra integradas automaticamente com especificação OpenAPI

Ao optar por integrar automaticamente as APIs de sombra ao Centro de API, 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 ApiCenterOnboardingPlugin detecta que o Dev Proxy criou uma nova especificação OpenAPI, ele a associa à API integrada correspondente no Centro de API.

Para gerar automaticamente as 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": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
    "resourceGroupName": "demo",
    "serviceName": "contoso-api-center",
    "workspaceName": "default",
    "createApicEntryForNewApis": true
  }
}

Importante

O Dev Proxy executa plug-ins na ordem em que estão registrados na configuração. Você precisa registrar o OpenApiSpecGeneratorPlugin primeiro para que ele possa criar especificações OpenAPI antes que o ApiCenterOnboardingPlugin integre novas APIs.

Quando você executa o Dev Proxy com essa configuração, ele cria automaticamente novas entradas de API no Centro de API do Azure para as APIs de sombra que ele detecta. Para cada nova API, o Dev Proxy gera uma nova especificação OpenAPI e a associa à API integrada correspondente no 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    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 tela do Centro de API do Azure mostrando uma API recém-integrada com uma especificação OpenAPI.

Resumo

Usando o Dev Proxy e seu ApiCenterOnboardingPlugin, você poderá verificar se o seu aplicativo está usando APIs de sombra. O plug-in analisa solicitações de API do aplicativo e de relatórios sobre solicitações de API que não estão registradas no Centro de API do Azure. O plug-in permite que você integre facilmente APIs ausentes ao Centro de API. Combinando o plug-in ApiCenterOnboardingPlugin com o OpenApiSpecGeneratorPlugin, você pode gerar automaticamente as especificações OpenAPI para as APIs recém-integradas. Você pode executar essa verificação manualmente ou integrá-la ao pipeline de CI/CD para se certificar de que seu aplicativo esteja usando APIs registradas antes de liberá-lo para a produção.

Mais informações