Zjišťování stínových rozhraní API pomocí Dev Proxy

Článek
07/16/2024

Pomocí Azure API Center můžete katalogovat rozhraní API používaná ve vaší organizaci. To vám umožní zjistit, která rozhraní API používáte, kde se rozhraní API nachází ve svém životním cyklu a kdo se má obrátit, pokud dojde k problémům. Stručně řečeno, aktuální katalog rozhraní API vám pomůže zlepšit stav zásad správného řízení, dodržování předpisů a zabezpečení.

Při sestavování aplikace, zejména pokud integrujete nové scénáře, možná používáte rozhraní API, která nejsou zaregistrovaná ve službě Azure API Center. Tato rozhraní API se nazývají stínová rozhraní API. Stínová rozhraní API jsou rozhraní API, která nejsou ve vaší organizaci zaregistrovaná. Můžou se jednat o rozhraní API, která ještě nejsou zaregistrovaná, nebo se mohou jednat o rozhraní API, která nejsou určená k použití ve vaší organizaci.

Jedním ze způsobů, jak zkontrolovat stínová rozhraní API, je použití dev proxy serveru. Dev Proxy je simulátor rozhraní API, který zachycuje a analyzuje požadavky rozhraní API z aplikací. Jednou z funkcí dev proxy je kontrola, jestli zachycené požadavky rozhraní API patří do rozhraní API zaregistrovaných v Centru rozhraní API.

Než začnete

Pokud chcete detekovat stínová rozhraní API, musíte mít instanci Azure API Center s informacemi o rozhraních API, která používáte ve vaší organizaci. Pokud jste ho ještě nevytvořili, přečtěte si článek Rychlý start: Vytvoření centra rozhraní API. Kromě toho je potřeba nainstalovat Dev Proxy.

Kopírování informací o centru rozhraní API

Na stránce Přehled instance služby Azure API Center zkopírujte název instance služby API Center, název skupiny prostředků a ID předplatného. Tyto informace potřebujete ke konfiguraci služby Dev Proxy ApiCenterOnboardingPlugin , aby se mohl připojit k vaší instanci služby Azure API Center.

Konfigurace dev proxy serveru

Pokud chcete zkontrolovat, jestli vaše aplikace používá stínová rozhraní API, musíte povolit ApiCenterOnboardingPlugin konfigurační soubor dev proxy serveru. Pokud chcete vytvořit sestavu rozhraní API, která vaše aplikace používá, přidejte reportér.

Povolení `ApiCenterOnboardingPlugin`

devproxyrc.json Do souboru přidejte následující konfiguraci:

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

V objektu subscriptionId, resourceGroupNamea serviceName vlastnosti zadejte informace o vaší instanci služby Azure API Center.

urlsToWatch Ve vlastnosti zadejte adresy URL, které vaše aplikace používá.

Tip

Pomocí rozšíření Dev Proxy Toolkit Visual Studio Code můžete snadno spravovat konfiguraci dev proxy serveru.

Přidání reportéru

Vytvoří ApiCenterOnboardingPlugin sestavu rozhraní API, která vaše aplikace používá. Pokud chcete tuto sestavu zobrazit, přidejte do konfiguračního souboru dev proxy reporter. Dev Proxy nabízí několik zpravodajů. V tomto příkladu použijete reportér prostého textu.

Aktualizujte devproxyrc.json soubor odkazem na reportér prostého textu:

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

Kontrola, jestli vaše aplikace používá stínová rozhraní API

Pokud chcete zkontrolovat, jestli vaše aplikace používá stínová rozhraní API, připojte se k předplatnému Azure, spusťte Dev Proxy a nechte ji zachycovat požadavky rozhraní API z vaší aplikace. Dev Proxy pak porovná informace o požadavcích rozhraní API s informacemi z Azure API Center a sestavami všech rozhraní API, která nejsou zaregistrovaná v Centru rozhraní API.

Připojení k předplatnému Azure

Dev Proxy používá informace z Azure API Center k určení, jestli vaše aplikace používá stínová rozhraní API. K získání těchto informací potřebuje připojení k vašemu předplatnému Azure. K předplatnému Azure se můžete připojit několika způsoby.

Spuštění dev proxy serveru

Po připojení k předplatnému Azure spusťte Dev Proxy. Pokud spustíte Dev Proxy ze stejné složky, ve které devproxyrc.json se soubor nachází, automaticky načte konfiguraci. V opačném případě zadejte cestu ke konfiguračnímu souboru pomocí --config-file této možnosti.

Když se spustí dev proxy server, zkontroluje, že se může připojit k vašemu předplatnému Azure. Po úspěšném připojení se zobrazí zpráva podobná této:

 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

Stisknutím klávesy R spusťte nahrávání požadavků rozhraní API z vaší aplikace.

Použití aplikace

Používejte aplikaci stejně, jako byste to normálně dělali. Dev Proxy zachytí požadavky rozhraní API a uloží informace o nich do paměti. Na příkazovém řádku, na kterém běží Dev Proxy, byste měli vidět informace o požadavcích rozhraní API, které vaše aplikace provádí.

 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

Kontrola stínových rozhraní API

Zastavte záznam stisknutím klávesy s. Dev Proxy se připojí k instanci služby API Center a porovná informace o požadavcích s informacemi z centra 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...

Po dokončení analýzy dev proxy vytvoří sestavu v souboru s názvem ApiCenterOnboardingPlugin_PlainTextReporter.txt s následujícím obsahem:

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

Automatické onboarding stínové rozhraní API

Dokáže ApiCenterOnboardingPlugin nejen rozpoznat stínová rozhraní API, ale také je automaticky připojit ke službě API Center. Pokud chcete automaticky připojit stínová rozhraní API, aktualizujte createApicEntryForNewApis v konfiguračním souboru dev proxy adresu na 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
  }
}

Když spustíte Dev Proxy s nastaveným createApicEntryForNewApis nastavením true, automaticky vytvoří nové položky rozhraní API ve službě Azure API Center pro stínová rozhraní API, která detekuje.

Automatické onboarding stínových rozhraní API se specifikací OpenAPI

Když se rozhodnete automaticky připojit stínová rozhraní API ke službě API Center, můžete pro rozhraní API vygenerovat specifikace OpenAPI. Onboarding rozhraní API se specifikacemi OpenAPI urychlí onboarding chybějících koncových bodů a poskytne vám potřebné informace o rozhraní API. Když zjistí ApiCenterOnboardingPlugin , že vývojový proxy server vytvořil novou specifikaci OpenAPI, přidruží ho k odpovídajícímu onboardovanýmu rozhraní API ve službě API Center.

Pokud chcete automaticky generovat specifikace OpenAPI pro zprovozněná rozhraní API, aktualizujte konfiguraci dev proxy serveru tak, aby zahrnovala 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
  }
}

Důležité

Dev Proxy spouští moduly plug-in v pořadí, v jakém jsou zaregistrované v konfiguraci. Musíte nejprve zaregistrovat OpenApiSpecGeneratorPlugin , aby mohl vytvořit specifikace OpenAPI před ApiCenterOnboardingPlugin onboardingem nových rozhraní API.

Když spustíte Dev Proxy s touto konfigurací, automaticky vytvoří nové položky rozhraní API ve službě Azure API Center pro stínová rozhraní API, která detekuje. Pro každé nové rozhraní API vygeneruje Dev Proxy specifikaci OpenAPI a přidruží ho k odpovídajícímu onboardovanému rozhraní API ve službě API Center.

 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

Shrnutí

Pomocí dev proxy serveru a jeho ApiCenterOnboardingPluginmůžete zkontrolovat, jestli vaše aplikace používá stínová rozhraní API. Modul plug-in analyzuje požadavky rozhraní API z vaší aplikace a hlásí všechny požadavky rozhraní API, které nejsou zaregistrované ve službě Azure API Center. Modul plug-in umožňuje snadno připojit chybějící rozhraní API do služby API Center. Zkombinováním modulu ApiCenterOnboardingPlugin plug-in s OpenApiSpecGeneratorPluginmodulem můžete automaticky generovat specifikace OpenAPI pro nově nasazená rozhraní API. Tuto kontrolu můžete spustit ručně nebo integrovat s kanálem CI/CD, abyste měli jistotu, že vaše aplikace používá zaregistrovaná rozhraní API, než ji uvolní do produkčního prostředí.

Sdílet prostřednictvím

Zjišťování stínových rozhraní API pomocí Dev Proxy

Než začnete

Kopírování informací o centru rozhraní API

Konfigurace dev proxy serveru

Povolení `ApiCenterOnboardingPlugin`

Přidání reportéru

Kontrola, jestli vaše aplikace používá stínová rozhraní API

Připojení k předplatnému Azure

Spuštění dev proxy serveru

Použití aplikace

Kontrola stínových rozhraní API

Automatické onboarding stínové rozhraní API

Automatické onboarding stínových rozhraní API se specifikací OpenAPI

Shrnutí

Více informací

Váš názor

Další materiály

Sdílet prostřednictvím

Zjišťování stínových rozhraní API pomocí Dev Proxy

Než začnete

Kopírování informací o centru rozhraní API

Konfigurace dev proxy serveru

Povolení ApiCenterOnboardingPlugin

Přidání reportéru

Kontrola, jestli vaše aplikace používá stínová rozhraní API

Připojení k předplatnému Azure

Spuštění dev proxy serveru

Použití aplikace

Kontrola stínových rozhraní API

Automatické onboarding stínové rozhraní API

Automatické onboarding stínových rozhraní API se specifikací OpenAPI

Shrnutí

Více informací

Váš názor

Další materiály

Povolení `ApiCenterOnboardingPlugin`