Como encontrar APIs sombra
Usando a Central de APIs do Azure, você pode catalogar APIs usadas em sua organização. A qualquer momento, você pode saber quais APIs você usa em sua organização. Você também pode saber 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.
Para verificar se seu aplicativo está usando APIs de sombra, você pode usar o ApiCenterOnboardingPlugin plug-in. Este plug-in analisa as solicitações de API do seu aplicativo e relata todas as APIs que não estão registradas no Centro de APIs. Além disso, ele pode integrar diretamente novas APIs ao Centro de APIs 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.
Criar uma instância do Centro de API do Azure
Antes de começar, crie uma instância do Centro de API do Azure e registre as APIs que você usa em sua organização.
O ApiCenterOnboardingPlugin usa essas informações para verificar se as APIs que seu aplicativo está usando estão registradas em sua organização.
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 ApiCenterOnboardingPlugin para que ele possa se conectar à sua instância do Centro de API do Azure.
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": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"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": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"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": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"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.
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": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
"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
Resumo
Usando o ApiCenterOnboardingPlugin, você pode verificar se seu aplicativo está usando APIs de 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.
