Jak spravovat konfiguraci správy API pomocí APIOps CLI

Platí pro: Všechny úrovně služby API Management

APIOps CLI je nástroj pro konfiguraci jako kód pro Azure API Management. V tomto článku ho použijete k extrakci konfigurace API Management do lokálních artefaktů, kontrole artefaktů v Gitu, náhledu změn a publikování schválených artefaktů do instance API Management. CLI může také vygenerovat základní soubory GitHub Actions nebo Azure Pipelines pro pracovní postup APIOps.

Kroky poskytují minimální pracovní postup, který můžete ověřit pomocí neprodukční instance API Management. Pro rady o architektuře a návrhu viz Automatizovaná nasazení API s APIOps.

Použijte tento postup k:

  • Zkontrolujte definice API, politiky a další konfigurace správy API prostřednictvím pull requestů.
  • Udržujte auditovatelnou historii schválených změn konfigurace.
  • Podporovat recenzované artefakty mezi prostředími správy API.
  • Začněte konfigurací extrahovanou z existující instance nebo vytvořte artefakty kompatibilní s CLI v kódu.

APIOps CLI doplňuje přístupy API DevOps popsané v článku Použití DevOps a CI/CD k publikování rozhraní API. Vyhodnoťte CLI a zamýšlený pracovní postup pro artefakty v neprodukčním prostředí před jejich použitím pro nasazení do produkce.

Předpoklady

  • Node.js verze 22 nebo novější.
  • Azure CLI, pro lokální autentizační kroky v tomto článku.
  • Předplatné Azure a existující neprodukční instance správy API.
  • Repozitář Git pro artefakty API Managementu.
  • Identita s přístupem k instanci správy API. Úvodní příručka k APIOps CLI uvádí role Přispěvatel služby API Management a Čtenář v oboru prostředků API Management pro pracovní postup extrakce a publikování.

Pro produkční automatizaci používejte pokud možno samostatné identity s nejmenšími privilegiováními. Extrakční identita potřebuje oprávnění ke čtení zdrojové instance. Publikační identita potřebuje pouze oprávnění potřebná k aktualizaci cílové instance.

Install APIOps CLI

@azure-tools/apiops-cli Nainstalujte balíček npm:

npm install -g @azure-tools/apiops-cli

Ověřte nainstalovanou verzi:

apiops --version

Nahrajte a připněte verzi, kterou schválíte pro své CI/CD pipeline. Před upgradem si prohlédněte seznam změn APIOps CLI .

Ověřování v Azure

Pro lokální použití se přihlaste pomocí Azure CLI a vyberte předplatné, které obsahuje vaši neprodukční instanci správy API:

az login
az account set --subscription <subscription-id>

APIOps CLI používá DefaultAzureCredential. Kromě přihlašovacích údajů Azure CLI podporuje přihlašovací údaje do prostředí, identitu pracovní zátěže, spravovanou identitu, Azure PowerShell a přihlašovací údaje Azure Developer CLI.

Pro CI/CD upřednostňujte federaci identit úloh nebo spravovanou identitu místo tajného klíče klienta. Nikdy nedávejte přihlašovací údaje, přístupové tokeny, předplatné klíče ani tajné pojmenované hodnoty do správy zdrojového kódu. Pro podporované autentizační možnosti viz APIOps CLI autentizační průvodce.

Připravte úložiště artefaktů

Spusť příkazy APIOps CLI z kořene Git repozitáře, který obsahuje artefakty pro správu API.

Chcete-li vygenerovat kanály a šablony konfigurace pro GitHub Actions, spusťte:

apiops init --ci github-actions --environments dev,prod --non-interactive

Pro Azure Pipelines použijte:

apiops init --ci azure-devops --environments dev,prod --non-interactive

Příkaz vytváří definice pipeline, šablonu extrakčního filtru, šablony pro přepisování prostředí, pokyny pro nastavení identity a adresář.apim-artifacts Před tím, než pipeline commitujete nebo povolíte, zkontrolujte každý vygenerovaný soubor. Nepoužívejte --force v repozitáři s existujícími soubory, pokud nepřezkoumáte soubory, které příkaz přepíše.

Pokud už máte repozitář a návrh pipeline, můžete místo toho vytvořit nebo vybrat adresář artefaktů a přímo použít příkazy pro extrakci a publikování.

Vytvořte počáteční artefakty

Vyberte si jeden z následujících přístupů, jak zjistit artefakty, které vaše úložiště vlastní.

Extrahování existující konfigurace

Pro vytvoření základní hodnoty z existující instance správy API extrahujte její konfiguraci:

apiops extract \
  --subscription-id <source-subscription-id> \
  --resource-group <source-resource-group> \
  --service-name <source-apim-name> \
  --output ./apim-artifacts

Příkaz vytváří JSON informační soubory, XML policy soubory a API specifikační soubory v hierarchii pod .apim-artifacts Pro velkou instanci nakonfigurujte extrakční filtr tak, aby repozitář spravoval pouze zamýšlené zdroje.

Začněte s artefakty, které jsou na prvním místě v kódu

Pro workflow zaměřený na kód přidejte specifikaci OpenAPI a požadované informace o správě API a soubory politik pomocí formátu artefaktů APIOps CLI. Nepředpokládejte, že stávající rozložení repozitáře aplikací nebo samotný OpenAPI soubor je připraven pro apiops publish.

Pokud jste v artefaktovém formátu noví, nejdřív extrahujte malé referenční API z neprodukční instance. Použijte výsledné soubory jako šablony a seznamte se s pokyny k postupu code-first.

Projděte si artefakty

Než publikujete:

  1. Prohlédněte si vygenerované nebo autorské soubory a ověřte, že repozitář obsahuje pouze zdroje, které hodláte spravovat.
  2. Projděte si specifikace API, politiky, backendy, pojmenované hodnoty, produkty a jejich závislosti.
  3. Odstraňte hodnoty specifické pro prostředí, které by se neměly přesunout do jiného prostředí. Používejte zkontrolované soubory přepsání prostředí nebo odkazy na Azure Key Vault, kde je to vhodné.
  4. Hledejte přihlašovací údaje a tajné hodnoty. Extrakce rediguje podporovaná pole s tajnými údaji a rozpoznané vzory zásad, ale nemusí odhalit všechny vložené tajné údaje. Nevkládejte do commitu tajné údaje ani nevyřešené hodnoty *** REDACTED ***.
  5. Commitujte artefakty do větve a použijte pull request pro ověření a schválení.

Náhled a publikování

Spusť zkušební test na neprodukční cílové instanci. Zkušební běh zobrazí plánovaná vytvoření, aktualizace a odstranění, aniž by je provedl:

apiops publish \
  --subscription-id <target-subscription-id> \
  --resource-group <target-resource-group> \
  --service-name <target-apim-name> \
  --source ./apim-artifacts \
  --dry-run

Zkontrolujte výstup a vyřešte neočekávané změny nebo chybějící závislosti. Úspěšný suchý test nenahradí testování chování API, politik, oprávnění ani backendové konektivity.

Caution

Nepřidávejte --delete-unmatched do svého prvního pracovního postupu. Tato možnost maže zdroje v cílové instanci, které nejsou reprezentovány ve zdrojových artefaktech.

Publikujte recenzované artefakty

Po schválení pull requestu a úspěšném zkušebním testu publikujte stejné recenzované artefakty pro neprodukční cíl:

apiops publish \
  --subscription-id <target-subscription-id> \
  --resource-group <target-resource-group> \
  --service-name <target-apim-name> \
  --source ./apim-artifacts

Ověřte API a politiky v cílové instanci po publikování. Když tento workflow automatizujete, nakonfigurujte pipeline tak, aby publikoval schválený commit a chránil prostředí nasazení požadovanými kontrolami a schváleními vaší organizace.

Další kroky

  • Last updated on