Jak zarządzać konfiguracją zarządzania API za pomocą APIOps CLI

DOTYCZY: Wszystkich poziomów zarządzania API

APIOps CLI to narzędzie do zarządzania konfiguracją jako kodem dla Azure API Management. W tym artykule używasz go do wyodrębniania konfiguracji zarządzania API do lokalnych artefaktów, przeglądania artefaktów w Gicie, podglądu zmian oraz publikowania zatwierdzonych artefaktów do instancji zarządzania API. CLI może również wspierać pliki GitHub Actions lub Azure Pipelines dla workflow APIOps.

Kroki te zapewniają minimalny przepływ pracy, który możesz zweryfikować za pomocą instancji zarządzania API poza produkcją. Wskazówki dotyczące architektury i projektowania znajdują się w artykule Zautomatyzowane wdrożenia API za pomocą APIOps.

Użyj tego przepływu pracy, aby:

  • Przeglądaj definicje API, polityki oraz inne konfiguracje zarządzania API poprzez pull requesty.
  • Prowadź audytowalną historię zatwierdzonych zmian konfiguracji.
  • Promuj recenzowane artefakty pomiędzy środowiskami zarządzania API.
  • Zacznij od konfiguracji wyodrębnionej z istniejącej instancji lub utwórz zgodne z CLI artefakty w postaci kodu.

APIOps CLI uzupełnia podejścia API DevOps opisane w Use DevOps oraz CI/CD do publikowania API. Oceń CLI i zamierzony przepływ pracy z artefaktami w środowisku nieprodukcyjnym, zanim zaczniesz używać go do wdrożeń produkcyjnych.

Wymagania wstępne

  • Node.js w wersji 22 lub nowszej.
  • Azure CLI, dla lokalnych kroków uwierzytelniania w tym artykule.
  • Subskrypcja Azure oraz istniejąca nieprodukcyjna instancja zarządzania API.
  • Repozytorium Git dla artefaktów zarządzania API.
  • Tożsamość z dostępem do instancji zarządzania API. Wytyczne dotyczące rozpoczęcia pracy z CLI APIOps wymieniają role Współautor usługi API Management i Czytelnik w zakresie zasobu API Management na potrzeby przepływu pracy wyodrębniania i publikowania.

W automatyzacji produkcji używaj oddzielnych, najmniej przywilejowanych tożsamości, gdy to możliwe. Tożsamość używana do ekstrakcji wymaga dostępu do odczytu instancji źródłowej. Tożsamość używana do publikowania wymaga jedynie uprawnień niezbędnych do zaktualizowania instancji docelowej.

Install APIOps CLI

@azure-tools/apiops-cli Zainstaluj pakiet npm:

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

Sprawdź zainstalowaną wersję:

apiops --version

Nagraj i przypiń wersję, którą zaakceptujesz dla swoich CI/CD pipeline'ów. Przejrzyj changelog APIOps CLI przed aktualizacją.

Uwierzytelnianie na platformie Azure

Do użytku lokalnego zaloguj się za pomocą Azure CLI i wybierz subskrypcję, która zawiera Twoją nieprodukcyjną instancję zarządzania API:

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

APIOps CLI używa DefaultAzureCredential. Oprócz poświadczeń Azure CLI obsługiwane są także poświadczenia środowiskowe, tożsamość obciążenia roboczego, tożsamość zarządzana, Azure PowerShell oraz poświadczenia Azure Developer CLI.

W przypadku CI/CD należy preferować federację tożsamości obciążeń lub tożsamość zarządzaną zamiast klucza tajnego klienta. Nigdy nie umieszczaj poświadczeń, tokenów dostępu, kluczy subskrypcji ani nazwanych wartości tajnych w systemie kontroli wersji. Aby poznać obsługiwane opcje uwierzytelniania, zobacz przewodnik po uwierzytelnianiu APIOps CLI.

Przygotuj repozytorium artefaktów

Uruchamiaj polecenia APIOps CLI z rootu repozytorium Gita, który zawiera artefakty zarządzania API.

Aby utworzyć szkielet potoków i szablonów konfiguracji dla GitHub Actions, wykonaj:

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

W przypadku usługi Azure Pipelines użyj:

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

Polecenie tworzy definicje potoków, szablon filtru wyodrębniania, szablony zastąpień środowiskowych, wskazówki dotyczące konfigurowania tożsamości oraz katalog apim-artifacts. Przejrzyj każdy wygenerowany plik przed zatwierdzeniem lub włączeniem pipeline. Nie używaj --force w repozytorium z istniejącymi plikami, chyba że przejrzysz pliki, które polecenie nadpisuje.

Jeśli masz już repozytorium i projekt pipeline, możesz zamiast tego stworzyć lub wybrać katalog artefaktów i bezpośrednio użyć poleceń do wyodrębniania i publikowania.

Stwórz początkowe artefakty

Wybierz jedno z poniższych sposobów ustalenia artefaktów, które posiada Twoje repozytorium.

Wyodrębniaj istniejącą konfigurację

Aby stworzyć bazę z istniejącej instancji zarządzania API, wyodrębnij jej konfigurację:

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

Polecenie tworzy pliki informacyjne JSON, pliki polityki XML oraz pliki specyfikacji API w hierarchii pod .apim-artifacts Dla dużego przypadku skonfiguruj filtr ekstrakcji tak, aby repozytorium zarządzało tylko zamierzonymi zasobami.

Zacznij od artefaktów code-first

W przepływie pracy opartym na kodzie dodaj specyfikację OpenAPI oraz wymagane informacje usługi API Management i pliki zasad, używając formatu artefaktów APIOps CLI. Nie zakładaj, że istniejący układ repozytorium aplikacji lub samodzielny plik OpenAPI jest gotowy do apiops publish.

Jeśli dopiero zaczynasz przygodę z formatem artefaktów, najpierw wyodrębnij małe API referencyjne z instancji nieprodukcyjnej. Użyj powstałych plików jako szablonów i zapoznaj się z wytycznymi dotyczącymi przepływu pracy opartego na kodowaniu.

Przejrzyj artefakty

Zanim opublikujesz:

  1. Sprawdź wygenerowane lub autorskie pliki i popewnij, że repozytorium zawiera tylko zasoby, którymi zamierzasz zarządzać.
  2. Przeglądaj specyfikacje API, polityki, backendy, wartości nazwane, produkty oraz ich zależności.
  3. Usuń wartości specyficzne dla środowiska, które nie powinny przenosić się do innego środowiska. Używaj sprawdzonych plików zastąpień środowiska lub odnośników do Azure Key Vault w odpowiednich przypadkach.
  4. Wyszukaj dane poświadczenia i wartości tajnych. Funkcja ekstrakcji maskuje obsługiwane pola wpisów tajnych i rozpoznane wzorce zasad, ale może nie wykryć każdego osadzonego wpisu tajnego. Nie popełniaj tajemnic ani nie podejmuj nierozwiązanych *** REDACTED *** wartości.
  5. Zatwierdzaj artefakty w gałęzi i użyj pull requestu do weryfikacji i zatwierdzenia.

Podgląd publikacji

Uruchom próbne uruchomienie na docelowej instancji nieprodukcyjnej. Przebieg próbny pokazuje planowane operacje tworzenia, aktualizacji i usuwania bez ich wykonywania:

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

Przejrzyj wyniki i rozwiń nieoczekiwane zmiany lub brakujące zależności. Udana próba na sucho nie zastąpi testowania zachowania API, polityk, uprawnień czy łączności backendu.

Caution

Nie dodawaj --delete-unmatched do swojego pierwszego przepływu pracy. Ta opcja usuwa zasoby w docelowej instancji, które nie są reprezentowane w artefaktach źródłowych.

Publikuj recenzowane artefakty

Po zatwierdzeniu pull requestu i pomyślnym zakończeniu próby na sucho opublikuj te same zweryfikowane artefakty do środowiska nieprodukcyjnego:

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

Zweryfikuj API i polityki w docelowej instancji po opublikowaniu. Gdy zautomatyzujesz ten przepływ pracy, skonfiguruj potok tak, aby publikował zatwierdzony commit i chronił środowiska wdrożeniowe za pomocą wymaganych przez Twoją organizację kontroli i zatwierdzeń.

Następne kroki

  • Last updated on