Sdílet prostřednictvím

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

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.

Snímek obrazovky příkazového řádku ukazuje kontrolu Dev Proxy, jestli jsou zaznamenané požadavky rozhraní API zaregistrované ve službě Azure API Center.

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.

Snímek obrazovky se stránkou přehledu azure API Center se zvýrazněnými několika vlastnostmi

Konfigurace dev proxy serveru

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

Povolte 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á.

Návod

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

Přidání reportéru

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

Aktualizujte svůj devproxyrc.json soubor přidáním odkazu na prostý textový reportér:

{
  "$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 podává zprávu o všech rozhraních 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í možnosti --config-file.

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žijte svou aplikaci

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é zavedení stínových rozhraní API

Dokáže ApiCenterOnboardingPlugin nejen rozpoznat stínová rozhraní API, ale také je automaticky připojit ke službě API Center. Pro automatické připojení stínových rozhraní API aktualizujte createApicEntryForNewApis v konfiguračním souboru Dev Proxy 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 createApicEntryForNewApis nastaveným na true, automaticky vytvoří nové záznamy API ve službě Azure API Center pro stínová rozhraní API, které detekuje.

Snímek obrazovky Centra rozhraní API zobrazující nově nasazené rozhraní API

Automatické zavádění skrytých rozhraní API s pomocí specifikace OpenAPI.

Když se rozhodnete automaticky připojit stínová rozhraní API ke službě API Center, můžete nechat Dev Proxy vygenerovat specifikaci OpenAPI pro rozhraní API. Nasazení rozhraní API se specifikacemi OpenAPI urychluje integraci chybějících koncových bodů a poskytuje 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. Nejprve musíte zaregistrovat OpenApiSpecGeneratorPlugin, aby mohlo vytvořit specifikace OpenAPI předtím, než ApiCenterOnboardingPlugin začne zavádět nové 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

Snímek obrazovky Azure API Center zobrazující nově nasazené rozhraní API se specifikací OpenAPI

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í.

Více informací

  • Last updated on