Použití DevOps a CI/CD k publikování rozhraní API

  • Článek

PLATÍ PRO: Všechny úrovně služby API Management

Díky strategické hodnotě rozhraní API v podniku se přijetí technik kontinuální integrace (CI) a nasazení (CD) DevOps stala důležitým aspektem vývoje rozhraní API. Tento článek popisuje rozhodnutí, která budete muset provést při zavádění principů DevOps pro správu rozhraní API.

Rozhraní API DevOps se skládá ze tří částí:

Diagram znázorňující tok DevOps rozhraní API

Jednotlivé části kanálu API DevOps jsou popsány níže.

Definice rozhraní API

Vývojář rozhraní API zapíše definici rozhraní API tím, že poskytne specifikaci, nastavení (například protokolování, diagnostiku a nastavení back-endu) a zásady, které se použijí pro rozhraní API. Definice rozhraní API poskytuje informace potřebné ke zřízení rozhraní API ve službě Azure API Management. Specifikace může být založená na specifikaci rozhraní API založené na standardech (například WSDL, OpenAPI nebo GraphQL), nebo je možné ji definovat pomocí rozhraní API Azure Resource Manageru (ARM) (například šablony ARM popisující rozhraní API a operace). Definice rozhraní API se v průběhu času změní a měla by se považovat za "zdrojový kód". Před přijetím se ujistěte, že je definice rozhraní API uložená ve správě zdrojového kódu a zda má odpovídající kontrolu.

K dispozici je několik nástrojů, které vám pomůžou vytvořit definici rozhraní API:

  • Sada Azure APIOps Toolkit poskytuje pracovní postup založený na systému správy zdrojového kódu Gitu (jako je GitHub nebo Azure Repos). Pomocí extraktoru vytvoří definici rozhraní API, která se pak použije u cílové služby API Management vydavatelem. APIOps v tuto chvíli podporuje rozhraní REST a GraphQL API.
  • Nástroj dotnet-apim převede definici YAML ve správném formátu na šablonu ARM pro pozdější nasazení. Tento nástroj se zaměřuje na rozhraní REST API.
  • Terraform je alternativou k Azure Resource Manageru ke konfiguraci prostředků v Azure. Můžete vytvořit konfiguraci Terraformu (společně se zásadami), která implementuje rozhraní API stejným způsobem jako šablona ARM.

K vytvoření artefaktů nezbytných k definování rozhraní API můžete také použít nástroje založené na integrovaném vývojovém prostředí (IDE) pro editory, jako je Visual Studio Code . Například na Webu Visual Studio Code Marketplace existuje více než 30 modulů plug-in pro úpravy souborů specifikace OpenAPI. K vytvoření artefaktů můžete použít také generátory kódu. Jazyk CADL umožňuje snadno vytvářet stavební bloky vysoké úrovně a pak je zkompilovat do standardního formátu definice rozhraní API, jako je OpenAPI.

Schválení rozhraní API

Jakmile se definice rozhraní API vytvoří, vývojář odešle definici rozhraní API ke kontrole a schválení. Pokud používáte systém správy zdrojového kódu založený na Gitu (například GitHub nebo Azure Repos), můžete odeslání provést prostřednictvím žádosti o přijetí změn. Žádost o přijetí změn informuje ostatní o změnách navržených v definici rozhraní API. Po potvrzení schvalovacích bran sloučí schvalovatel žádost o přijetí změn do hlavního úložiště, což znamená, že definici rozhraní API je možné nasadit do produkčního prostředí. Proces žádosti o přijetí změn umožňuje vývojáři napravit případné problémy zjištěné během procesu schvalování.

GitHub i Azure Repos umožňují nakonfigurovat kanály schválení, které se spustí při odeslání žádosti o přijetí změn. Kanály schválení můžete nakonfigurovat tak, aby spouštěly nástroje, jako jsou:

  • Lintery specifikace rozhraní API, jako je Spectral , aby se zajistilo, že definice splňuje standardy rozhraní API vyžadované organizací.
  • Detekce zásadních změn pomocí nástrojů, jako je openapi-diff.
  • Nástroje pro audit a posouzení zabezpečení. OWASP udržuje seznam nástrojů pro kontrolu zabezpečení.
  • Automatizované testovací architektury rozhraní API, jako je Newman, spouštěč testů pro kolekce Postman.

Poznámka:

Rozhraní API Azure musí odpovídat striktní sadě pokynů , které můžete použít jako výchozí bod pro vlastní pokyny rozhraní API. Pro vynucování těchto pokynů existuje konfigurace Spectral.

Po spuštění automatizovaných nástrojů se definice rozhraní API zkontroluje podle lidského oka. Nástroje nezachytí všechny problémy. Kontrolor člověka zajistí, aby definice rozhraní API splňovala organizační kritéria pro rozhraní API, včetně dodržování pokynů k zabezpečení, ochraně osobních údajů a konzistenci.

Publikace rozhraní API

Definice rozhraní API se publikuje do služby API Management prostřednictvím kanálu verze. Nástroje použité k publikování definice rozhraní API závisí na nástroji použitém k vytvoření definice rozhraní API:

  • Pokud používáte sadu Azure APIOps Toolkit, obsahuje sada nástrojů vydavatele, který do cílové služby zapíše definici rozhraní API.
  • Pokud používáte dotnet-apim, je definice rozhraní API reprezentována jako šablona ARM. Úlohy jsou k dispozici pro Azure Pipelines a GitHub Actions k nasazení šablony ARM.
  • Pokud používáte Terraform, nástroje rozhraní příkazového řádku nasadí definici rozhraní API ve vaší službě. Pro Azure Pipelines a GitHub Actions jsou k dispozici úlohy.

Můžu používat jiné systémy správy zdrojového kódu a CI/CD?

Ano. Popsaný proces funguje s jakýmkoli systémem správy zdrojového kódu (i když rozhraní APIOps vyžaduje, aby systém správy zdrojového kódu byl založený na Gitu ). Podobně můžete použít libovolnou platformu CI/CD, pokud ji může aktivovat vrácení se změnami a spuštění nástrojů příkazového řádku, které komunikují s Azure.

Osvědčené postupy

Pro nastavení kanálu DevOps pro rozhraní API pro publikování neexistuje žádný oborový standard a ve všech situacích nebude fungovat žádný z uvedených nástrojů. Vidíme však, že většina situací je pokryta kombinací následujících nástrojů a služeb:

Viděli jsme největší úspěch v nasazeních zákazníků a doporučujeme následující postupy:

  • Nastavte gitHub nebo Azure Repos pro váš systém správy zdrojového kódu. Tato volba také určí výběr spouštěče kanálů. GitHub může používat Azure Pipelines nebo GitHub Actions, zatímco Azure Repos musí používat Azure Pipelines.
  • Nastavte službu Azure API Management pro každého vývojáře rozhraní API, aby mohli vyvíjet definice rozhraní API společně se službou API. Při vytváření služby použijte skladovou položku consumption nebo developer.
  • Pomocí fragmentů zásad zmenšete nové zásady, které vývojáři potřebují psát pro každé rozhraní API.
  • Pomocí pojmenovaných hodnot a back-endů se ujistěte, že zásady jsou obecné a můžou platit pro libovolnou instanci služby API Management.
  • Pomocí sady Azure APIOps Toolkit extrahujte z vývojářské služby funkční definici rozhraní API.
  • Nastavte proces schvalování rozhraní API, který běží na jednotlivých žádostech o přijetí změn. Proces schvalování rozhraní API by měl zahrnovat detekci zásadních změn, lintování a automatizované testování rozhraní API.
  • Pomocí vydavatele sady Azure APIOps Toolkit publikujte rozhraní API do produkční služby API Management.

Projděte si automatizovaná nasazení rozhraní API s využitím APIOps v Centru architektury Azure, kde najdete další podrobnosti o konfiguraci a spuštění kanálu nasazení CI/CD s využitím APIOps.

Reference