Come trovare le API shadow

Usando il Centro API di Azure è possibile catalogarne le API usate nell'organizzazione. In qualsiasi momento, è possibile indicare le API usate nell'organizzazione. È anche possibile indicare dove si trova l'API nel ciclo di vita e chi contattare in caso di problemi. In breve, avere un catalogo aggiornato di API consente di migliorare il comportamento di governance, conformità e sicurezza.

Quando si compila l'app, soprattutto se si integrano nuovi scenari, è possibile usare api non registrate nel Centro API di Azure. Queste API sono denominate API shadow. Le API Shadow sono API non registrate nell'organizzazione. Potrebbero essere API che non sono ancora registrate o che potrebbero essere API che non devono essere usate nell'organizzazione.

Per verificare se l'app usa le API shadow, è possibile usare il plug-in ApiCenterOnboardingPlugin . Questo plug-in analizza le richieste API dall'app e segnala le API non registrate nel Centro API. Inoltre, può eseguire direttamente l'onboarding di nuove API nel Centro API di Azure.

Screenshot di un prompt dei comandi che mostra il controllo del proxy di sviluppo se le richieste API registrate vengono registrate nel Centro API di Azure.

Prima di iniziare

Per rilevare le API shadow, è necessario avere un'istanza del Centro API di Azure con informazioni sulle API usate nell'organizzazione.

Creare un'istanza del Centro API di Azure

Prima di iniziare, creare un'istanza del Centro API di Azure e registrare le API usate nell'organizzazione.

Screenshot del Centro API di Azure con diverse API usate nell'organizzazione.

ApiCenterOnboardingPlugin Usa queste informazioni per verificare se le API, che l'app usa, vengono registrate nell'organizzazione.

Copiare le informazioni del Centro API

Nella pagina Panoramica dell'istanza del Centro API di Azure copiare il nome dell'istanza di Centro API, il nome del gruppo di risorse e l'ID sottoscrizione. Queste informazioni sono necessarie per configurare in modo che possa connettersi all'istanza ApiCenterOnboardingPlugin del Centro API di Azure.

Screenshot della pagina di panoramica del Centro API di Azure con diverse proprietà evidenziate.

Configurare il proxy di sviluppo

Per verificare se l'app usa le API shadow, è necessario abilitare ApiCenterOnboardingPlugin nel file di configurazione del proxy di sviluppo. Per creare un report delle API usate dall'app, aggiungere un reporter.

Abilitare ApiCenterOnboardingPlugin

devproxyrc.json Nel file aggiungere la configurazione seguente:

{
  "$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
  }
}

subscriptionIdNelle proprietà , resourceGroupNamee serviceName specificare le informazioni sull'istanza del Centro API di Azure.

urlsToWatch Nella proprietà specificare gli URL usati dall'app.

Suggerimento

Usare l'estensione Dev Proxy Toolkit di Visual Studio Code per gestire facilmente la configurazione del proxy di sviluppo.

Aggiungere un giornalista

Genera ApiCenterOnboardingPlugin un report delle API che l'app usa. Per visualizzare questo report, aggiungere un reporter al file di configurazione del proxy di sviluppo. Dev Proxy offre diversi reporter. In questo esempio si usa il reporter di testo normale.

Aggiornare il devproxyrc.json file con un riferimento al reporter in testo normale:

{
  "$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
  }
}

Controllare se l'app usa le API shadow

Per verificare se l'app usa API shadow, connettersi alla sottoscrizione di Azure, eseguire Dev Proxy e consentire l'intercettazione delle richieste API dall'app. Dev Proxy confronta quindi le informazioni sulle richieste API con le informazioni del Centro API di Azure e segnala le API non registrate nel Centro API.

Connettersi alla sottoscrizione di Azure

Dev Proxy usa le informazioni del Centro API di Azure per determinare se l'app usa le API shadow. Per ottenere queste informazioni, è necessaria una connessione alla sottoscrizione di Azure. È possibile connettersi alla sottoscrizione di Azure in diversi modi.

Eseguire il proxy di sviluppo

Dopo la connessione alla sottoscrizione di Azure, avviare Dev Proxy. Se si avvia Dev Proxy dalla stessa cartella in cui si trova il devproxyrc.json file, carica automaticamente la configurazione. In caso contrario, specificare il percorso del file di configurazione usando l'opzione --config-file .

All'avvio di Dev Proxy verifica che possa connettersi alla sottoscrizione di Azure. Quando la connessione ha esito positivo, viene visualizzato un messaggio simile al seguente:

 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

Premere r per avviare la registrazione delle richieste API dall'app.

Usare l'app

Usa la tua app come normalmente fai. Dev Proxy intercetta le richieste API e li archivia in memoria. Nella riga di comando in cui viene eseguito Il proxy di sviluppo dovrebbero essere visualizzate informazioni sulle richieste API eseguite dall'app.

 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

Controllare le API shadow

Arrestare la registrazione premendo s. Dev Proxy si connette all'istanza di Centro API e confronta le informazioni sulle richieste con le informazioni del Centro 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...

Al termine dell'analisi, Dev Proxy crea un report in un file denominato ApiCenterOnboardingPlugin_PlainTextReporter.txt con il contenuto seguente:

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

Eseguire automaticamente l'onboarding delle API shadow

Può ApiCenterOnboardingPlugin non solo rilevare le API shadow, ma anche eseguirne automaticamente l'onboarding nel Centro API. Per eseguire automaticamente l'onboarding delle API shadow, nel file di configurazione del proxy di sviluppo aggiornare in createApicEntryForNewApis 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 si esegue Dev Proxy con createApicEntryForNewApis impostato su true, vengono create automaticamente nuove voci API nel Centro API di Azure per le API shadow rilevate.

Screenshot del Centro API che mostra una nuova API di cui è stato eseguito l'onboarding.

Eseguire automaticamente l'onboarding delle API shadow con specifiche OpenAPI

Quando si sceglie di eseguire automaticamente l'onboarding, le API shadow nel Centro API possono essere generate da Dev Proxy per generare la specifica OpenAPI per l'API. Le API di onboarding con specifiche OpenAPI accelerano l'onboarding di endpoint mancanti e forniscono le informazioni necessarie sull'API. ApiCenterOnboardingPlugin Quando rileva, tale proxy di sviluppo ha creato una nuova specifica OpenAPI, la associa all'API di onboarding corrispondente nel Centro API.

Per generare automaticamente le specifiche OpenAPI per le API di cui è stato eseguito l'onboarding, aggiornare la configurazione di Dev Proxy per includere .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

Dev Proxy esegue i plug-in nell'ordine in cui sono registrati nella configurazione. È necessario registrare il OpenApiSpecGeneratorPlugin primo in modo che possa creare specifiche OpenAPI prima dell'onboarding di ApiCenterOnboardingPlugin nuove API.

Quando si esegue Dev Proxy con questa configurazione, vengono create automaticamente nuove voci API nel Centro API di Azure per le API shadow rilevate. Per ogni nuova API, Dev Proxy genera una specifica OpenAPI e la associa all'API di onboarding corrispondente nel Centro 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

Screenshot del Centro API di Azure che mostra una nuova API di cui è stato eseguito l'onboarding con una specifica OpenAPI.

Riepilogo

ApiCenterOnboardingPluginUsando , è possibile verificare se l'app usa le API shadow. Il plug-in analizza le richieste API dall'app e segnala le richieste API non registrate nel Centro API di Azure. Il plug-in consente di eseguire facilmente l'onboarding delle API mancanti nel Centro API. Combinando il ApiCenterOnboardingPlugin plug-in con OpenApiSpecGeneratorPlugin, è possibile generare automaticamente le specifiche OpenAPI per le API appena caricate. È possibile eseguire questo controllo manualmente o integrarsi con la pipeline CI/CD per assicurarsi che l'app usi LE API registrate prima di rilasciarla nell'ambiente di produzione.

Ulteriori informazioni