Sdílet prostřednictvím

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

PLATÍ PRO: Všechny úrovně správy rozhraní API

Díky strategické hodnotě rozhraní API v podniku se přechodem technik kontinuální integrace DevOps (CI) a průběžného nasazování (CD) stal 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 postavený na nadstavbě systému správy verzí zdrojového kódu, například GitHubu nebo Azure Repos. Pomocí extraktoru vytvoří definici rozhraní API, která se pak použije na cílovou službu 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 pro úpravy souborů specifikace OpenAPI na Webu Visual Studio Code Marketplace existuje více než 90 modulů plug-in . K vytvoření artefaktů můžete použít také generátory kódu. Jazyk TypeSpec umožňuje definovat rozhraní API a obrazce cloudových služeb a je vysoce rozšiřitelná s primitivními prvky, které můžou popisovat obrazce rozhraní API, které jsou společné mezi rozhraními REST, OpenAPI, gRPC a dalšími protokoly.

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ůže vývojář odeslat pull request. Žádost o stažení informuje ostatní o změnách navržených v definici API. Po potvrzení schválovacích bodů sloučí schvalovatel pull request do hlavní větve úložiště a signalizuje, ž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 schvalovací kanály, které se spouštějí 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:

  • Specifikace lintrů pro rozhraní API, jako je Spectral, aby se zajistilo, že definice splňuje standardy API vyžadované organizací.
  • Detekce zásadních změn pomocí nástrojů, jako 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

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

Publikování definice rozhraní API do služby API Management probíhá prostřednictvím nasazovacího kanálu. 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 nasazují 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 commit a spustit nástroje 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ů. Většina situací je však pokryta kombinací následujících nástrojů a služeb:

Dosáhli jsme největšího úspěchu v zákaznických nasazeních díky použití následujících postupů:

  • Nastavte gitHub nebo Azure Repos pro váš systém správy zdrojového kódu. Tato volba zároveň určuje váš výběr vykonavatele pipeline. 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 SKU typu 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í publikačního nástroje sady Azure APIOps Toolkit publikujte rozhraní API do produkční služby pro správu rozhraní API.

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

  • Last updated on