Jak konfigurować i zapisywać konfigurację usługi API Management za pomocą narzędzia Git

Artykuł
05/12/2023

DOTYCZY: Developer | Podstawowa | Standardowa | Premium

Każde wystąpienie usługi API Management przechowuje bazę danych konfiguracji, która zawiera informacje o konfiguracji i metadanych wystąpienia usługi. Zmiany w wystąpieniu usługi można wprowadzić, zmieniając ustawienie w Azure Portal przy użyciu narzędzi platformy Azure, takich jak Azure PowerShell lub interfejsu wiersza polecenia platformy Azure, lub wywołując interfejs API REST. Oprócz tych metod można zarządzać konfiguracją wystąpienia usługi przy użyciu usługi Git, włączając scenariusze, takie jak:

Przechowywanie wersji konfiguracji — pobieranie i przechowywanie różnych wersji konfiguracji usługi
Zmiany konfiguracji zbiorczej — wprowadź zmiany w wielu częściach konfiguracji usługi w repozytorium lokalnym i zintegruj zmiany z powrotem na serwerze z jedną operacją
Znany łańcuch narzędzi i przepływ pracy usługi Git — użyj narzędzi i przepływów pracy usługi Git, które znasz już

Na poniższym diagramie przedstawiono przegląd różnych sposobów konfigurowania wystąpienia usługi API Management.

Diagram porównujący sposoby konfigurowania usługi Azure API Management.

Po wprowadzeniu zmian w usłudze przy użyciu witryny Azure Portal narzędzia platformy Azure, takie jak program Azure PowerShell lub interfejs wiersza polecenia platformy Azure lub interfejs API REST, zarządzasz bazą danych konfiguracji usługi przy użyciu https://{name}.management.azure-api.net punktu końcowego, jak pokazano po prawej stronie diagramu. Po lewej stronie diagramu przedstawiono sposób zarządzania konfiguracją usługi przy użyciu repozytorium Git i Git dla usługi znajdującej się w https://{name}.scm.azure-api.netlokalizacji .

Poniższe kroki zawierają omówienie zarządzania wystąpieniem usługi API Management przy użyciu usługi Git.

Uzyskiwanie dostępu do konfiguracji usługi Git w usłudze
Zapisywanie bazy danych konfiguracji usługi w repozytorium Git
Sklonuj repozytorium Git na komputer lokalny
Pobierz najnowsze repozytorium na komputer lokalny i zatwierdź i wypchnij zmiany z powrotem do repozytorium
Wdrażanie zmian z repozytorium w bazie danych konfiguracji usługi

W tym artykule opisano sposób włączania i używania usługi Git do zarządzania konfiguracją usługi oraz zawiera informacje o plikach i folderach w repozytorium Git.

Ważne

Ta funkcja jest przeznaczona do pracy z małymi i średnimi konfiguracjami usług API Management, takimi jak konfiguracje o rozmiarze eksportowanym mniejszym niż 10 MB lub z mniej niż 10 000 encji. Usługi z dużą liczbą jednostek (produkty, interfejsy API, operacje, schematy itd.) mogą doświadczać nieoczekiwanych błędów podczas przetwarzania poleceń usługi Git. Jeśli wystąpią takie błędy, zmniejsz rozmiar konfiguracji usługi i spróbuj ponownie. Jeśli potrzebujesz pomocy, skontaktuj się z pomocą techniczną platformy Azure.

Uzyskiwanie dostępu do konfiguracji usługi Git w usłudze

Przejdź do wystąpienia usługi API Management w witrynie Azure Portal.
W menu po lewej stronie w obszarze Wdrażanie i infrastruktura wybierz pozycję Repozytorium.

Zrzut ekranu przedstawiający sposób uzyskiwania dostępu do konfiguracji usługi Git dla usługi API Management.

Zapisywanie konfiguracji usługi w repozytorium Git

Uwaga

Wszystkie wpisy tajne, które nie są zdefiniowane jako nazwane wartości, będą przechowywane w repozytorium i pozostaną w jego historii. Nazwane wartości zapewniają bezpieczne miejsce do zarządzania stałymi wartościami ciągów, w tym wpisami tajnymi, we wszystkich konfiguracjach i zasadach interfejsu API, dzięki czemu nie trzeba ich przechowywać bezpośrednio w instrukcjach zasad. Aby uzyskać więcej informacji, zobacz Używanie nazwanych wartości w zasadach usługi Azure API Management.

Przed sklonowaniem repozytorium zapisz bieżący stan konfiguracji usługi w repozytorium.

Na stronie Repozytorium wybierz pozycję Zapisz w repozytorium.
Wprowadź wszelkie żądane zmiany na ekranie potwierdzenia, takie jak nazwa gałęzi do zapisania konfiguracji, a następnie wybierz pozycję Zapisz.

Po kilku chwilach konfiguracja zostanie zapisana i zostanie wyświetlony stan konfiguracji repozytorium, w tym data i godzina ostatniej zmiany konfiguracji oraz ostatnia synchronizacja między konfiguracją usługi a repozytorium.

Po zapisaniu konfiguracji w repozytorium można ją sklonować.

Aby uzyskać informacje na temat zapisywania konfiguracji usługi przy użyciu interfejsu API REST, zobacz Konfiguracja dzierżawy — Zapisywanie.

Uzyskiwanie poświadczeń dostępu

Aby sklonować repozytorium, oprócz adresu URL do repozytorium, potrzebna jest nazwa użytkownika i hasło.

Na stronie Repozytorium wybierz pozycję Poświadczenia dostępu w górnej części strony.
Zanotuj nazwę użytkownika podaną na stronie Poświadczenia dostępu.
Aby wygenerować hasło, najpierw upewnij się, że wygaśnięcie jest ustawione na żądaną datę i godzinę wygaśnięcia, a następnie wybierz pozycję Generuj.

Ważne

Zanotuj to hasło. Po opuszczeniu tej strony hasło nie będzie ponownie wyświetlane.

Sklonowanie repozytorium na komputerze lokalnym

W poniższych przykładach użyto narzędzia Git Bash z usługi Git dla systemu Windows , ale możesz użyć dowolnego narzędzia Git, które znasz.

Otwórz narzędzie Git w żądanym folderze i uruchom następujące polecenie, aby sklonować repozytorium Git na komputer lokalny przy użyciu następującego polecenia:

git clone https://{name}.scm.azure-api.net/

Podaj nazwę użytkownika i hasło po wyświetleniu monitu.

Jeśli wystąpią jakiekolwiek błędy, spróbuj zmodyfikować polecenie git clone , aby uwzględnić nazwę użytkownika i hasło, jak pokazano w poniższym przykładzie.

git clone https://username:password@{name}.scm.azure-api.net/

Jeśli wystąpi błąd, spróbuj kodować część hasła w poleceniu za pomocą adresu URL. Jednym z szybkich sposobów wykonania tej czynności jest otwarcie programu Visual Studio i wydanie następującego polecenia w oknie bezpośrednim. Aby otworzyć okno natychmiastowe, otwórz dowolne rozwiązanie lub projekt w programie Visual Studio (lub utwórz nową pustą aplikację konsolową), a następnie wybierz pozycję Windows, natychmiast z menu Debugowanie .

?System.Net.WebUtility.UrlEncode("password from the Azure portal")

Użyj zakodowanego hasła wraz z nazwą użytkownika i lokalizacją repozytorium, aby skonstruować polecenie git.

git clone https://username:url encoded password@{name}.scm.azure-api.net/

Po zakończeniu klonowania zmień katalog na repozytorium, uruchamiając polecenie podobne do poniższego.

cd {name}.scm.azure-api.net/

Jeśli konfiguracja zostanie zapisana w gałęzi innej niż gałąź domyślna (master), wyewidencjonuj gałąź:

git checkout <branch_name>

Po sklonowanym repozytorium możesz wyświetlić je i pracować z nim w lokalnym systemie plików. Aby uzyskać więcej informacji, zobacz Dokumentacja struktury plików i folderów lokalnego repozytorium Git.

Aktualizowanie repozytorium lokalnego przy użyciu najnowszej konfiguracji wystąpienia usługi

Jeśli wprowadzisz zmiany w wystąpieniu usługi API Management w witrynie Azure Portal lub przy użyciu innych narzędzi platformy Azure, musisz zapisać te zmiany w repozytorium, zanim będzie można zaktualizować repozytorium lokalne przy użyciu najnowszych zmian.

Aby zapisać zmiany w witrynie Azure Portal, wybierz pozycję Zapisz w repozytorium na karcie Repozytorium dla wystąpienia usługi API Management.

Następnie, aby zaktualizować repozytorium lokalne:

Upewnij się, że jesteś w folderze repozytorium lokalnym. Jeśli polecenie zostało ukończone git clone , musisz zmienić katalog na repozytorium, uruchamiając polecenie podobne do poniższego.
```
cd {name}.scm.azure-api.net/
```
W folderze repozytorium lokalnego wydaj następujące polecenie.
```
git pull
```

Wypychanie zmian z repozytorium lokalnego do repozytorium serwera

Aby wypchnąć zmiany z repozytorium lokalnego do repozytorium serwerów, musisz zatwierdzić zmiany, a następnie wypchnąć je do repozytorium serwera. Aby zatwierdzić zmiany, otwórz narzędzie poleceń Git, przejdź do katalogu repozytorium lokalnego i wydaj następujące polecenia.

git add --all
git commit -m "Description of your changes"

Aby wypchnąć wszystkie zatwierdzenia do serwera, uruchom następujące polecenie.

git push

Wdrażanie zmian konfiguracji usługi w wystąpieniu usługi API Management

Po zatwierdzeniu lokalnych zmian i wypchnięciu ich do repozytorium serwera możesz wdrożyć je w wystąpieniu usługi API Management.

Przejdź do wystąpienia usługi API Management w witrynie Azure Portal.
W menu po lewej stronie w obszarze Wdrażanie i infrastruktura wybierz pozycję Repository Deploy to API Management (Wdrażanie repozytorium w usłudze>API Management).
Na stronie Konfiguracja wdrożenia repozytorium wprowadź nazwę gałęzi zawierającej żądane zmiany konfiguracji i opcjonalnie wybierz pozycję Usuń subskrypcje usuniętych produktów. Wybierz pozycję Zapisz.

Aby uzyskać informacje na temat wykonywania tej operacji przy użyciu interfejsu API REST, zobacz Konfiguracja dzierżawy — wdrażanie.

Dokumentacja struktury plików i folderów lokalnego repozytorium Git

Pliki i foldery w lokalnym repozytorium Git zawierają informacje o konfiguracji wystąpienia usługi.

Element	opis
główny folder api-management	Zawiera konfigurację najwyższego poziomu dla wystąpienia usługi
folder apiReleases	Zawiera konfigurację wydań interfejsu API w wystąpieniu usługi
folder apis	Zawiera konfigurację interfejsów API w wystąpieniu usługi
folder apiVersionSets	Zawiera konfigurację zestawów wersji interfejsu API w wystąpieniu usługi
folder zaplecza	Zawiera konfigurację zasobów zaplecza w wystąpieniu usługi
folder groups	Zawiera konfigurację grup w wystąpieniu usługi
folder zasad	Zawiera zasady w wystąpieniu usługi
folder portalStyles	Zawiera konfigurację dostosowań portalu deweloperów w wystąpieniu usługi
folder portalTemplates	Zawiera konfigurację szablonów portalu dla deweloperów w wystąpieniu usługi
folder products	Zawiera konfigurację produktów w wystąpieniu usługi
folder templates	Zawiera konfigurację szablonów wiadomości e-mail w wystąpieniu usługi

Każdy folder może zawierać co najmniej jeden plik, a w niektórych przypadkach co najmniej jeden folder, na przykład folder dla każdego interfejsu API, produktu lub grupy. Pliki w każdym folderze są specyficzne dla typu jednostki opisanej przez nazwę folderu.

Typ pliku	Purpose
json	Informacje o konfiguracji odpowiedniej jednostki
html	Opisy jednostki, często wyświetlane w portalu dla deweloperów
xml	Instrukcje zasad
Css	Arkusze stylów dostosowywania portalu dla deweloperów

Te pliki można tworzyć, usuwać, edytować i zarządzać w lokalnym systemie plików oraz zmiany wdrożone z powrotem w wystąpieniu usługi API Management.

Uwaga

Następujące jednostki nie są zawarte w repozytorium Git i nie można ich skonfigurować przy użyciu usługi Git.

Użytkownicy
Subskrypcje
Nazwane wartości
Jednostki portalu dla deweloperów inne niż style i szablony
Fragmenty zasad

Główny folder api-management

Folder główny api-management zawiera configuration.json plik zawierający informacje najwyższego poziomu dotyczące wystąpienia usługi w następującym formacie.

{
  "settings": {
    "RegistrationEnabled": "True",
    "UserRegistrationTerms": null,
    "UserRegistrationTermsEnabled": "False",
    "UserRegistrationTermsConsentRequired": "False",
    "DelegationEnabled": "False",
    "DelegationUrl": "",
    "DelegatedSubscriptionEnabled": "False",
    "DelegationValidationKey": "",
    "RequireUserSigninEnabled": "false"
  },
  "$ref-policy": "api-management/policies/global.xml"
}

Pierwsze cztery ustawienia (RegistrationEnabled, UserRegistrationTerms, UserRegistrationTermsEnabledi UserRegistrationTermsConsentRequired) są mapowe na następujące ustawienia na karcie Tożsamości w sekcji Portal deweloperów.

Ustawienie tożsamości	Mapy do
RegistrationEnabled	Obecność dostawcy tożsamości nazwy użytkownika i hasła
UserRegistrationTerms	Pole tekstowe Warunki użytkowania w polu tekstowym rejestracji użytkownika
UserRegistrationTermsEnabled	Pole wyboru Pokaż warunki użytkowania na stronie rejestracji
UserRegistrationTermsConsentRequired	Pole wyboru Wymagaj zgody
RequireUserSigninEnabled	Przekieruj anonimowych użytkowników do pola wyboru strony logowania

Następne cztery ustawienia (DelegationEnabled, DelegationUrl, DelegatedSubscriptionEnabledi DelegationValidationKey) są mapowe na następujące ustawienia na karcie Delegowanie w sekcji Portal deweloperów.

Ustawienie delegowania	Mapy do
DelegowanieEnabled	Pole wyboru Delegowanie logowania i rejestracji
Delegowanierl	Pole tekstowe Adres URL punktu końcowego delegowania
DelegatedSubscriptionEnabled	Pole wyboru Deleguj subskrypcję produktu
DelegowanieValidationKey	Deleguj pole tekstowe Klucz weryfikacji

Ostateczne ustawienie , $ref-policymapuje na plik globalnych instrukcji zasad dla wystąpienia usługi.

folder apiReleases

Folder apiReleases zawiera folder dla każdego wydania interfejsu API wdrożonego w produkcyjnym interfejsie API i zawiera następujące elementy.

apiReleases\<api release Id>\configuration.json — Konfiguracja wydania zawierająca informacje o datach wydania. Są to te same informacje, które zostaną zwrócone, jeśli chcesz wywołać operację Pobierz określoną wersję .

folder apis

Folder apis zawiera folder dla każdego interfejsu API w wystąpieniu usługi, który zawiera następujące elementy.

apis\<api name>\configuration.json — Konfiguracja interfejsu API zawierająca informacje o adresie URL usługi zaplecza i operacjach. Są to te same informacje, które zostaną zwrócone w przypadku wywołania operacji Uzyskiwanie określonego interfejsu API .
apis\<api name>\api.description.html — Opis interfejsu API odpowiadający description właściwości jednostki interfejsu API w interfejsie API REST.
apis\<api name>\operations\ — Folder zawierający pliki mapujące <operation name>.description.html operacje w interfejsie API. Każdy plik zawiera opis pojedynczej operacji w interfejsie API, która mapuje na description właściwość jednostki operacji w interfejsie API REST.

folder apiVersionSets

Folder apiVersionSets zawiera folder dla każdego zestawu wersji interfejsu API utworzonego dla interfejsu API i zawiera następujące elementy.

apiVersionSets\<api version set Id>\configuration.json — Konfiguracja zestawu wersji. Są to te same informacje, które zostaną zwrócone, jeśli chcesz wywołać operację Pobierz określony zestaw wersji.

folder groups

Folder groups zawiera folder dla każdej grupy zdefiniowanej w wystąpieniu usługi.

groups\<group name>\configuration.json — Konfiguracja grupy. Są to te same informacje, które zostaną zwrócone, jeśli chcesz wywołać operację Pobierz określoną grupę .
groups\<group name>\description.html — Opis grupy odpowiadającej description właściwości jednostki grupy.

folder zasad

Folder policies zawiera instrukcje zasad dla wystąpienia usługi.

policies\global.xml - Zasady zdefiniowane w zakresie globalnym dla wystąpienia usługi.
policies\apis\<api name>\ — Jeśli masz zasady zdefiniowane w zakresie interfejsu API, znajdują się one w tym folderze.
policies\apis\<api name>\<operation name>\ folder — jeśli masz zasady zdefiniowane w zakresie operacji, znajdują się one w tym folderze w <operation name>.xml plikach mapujących na instrukcje zasad dla każdej operacji.
policies\products\ — Jeśli masz zasady zdefiniowane w zakresie produktu, znajdują się one w tym folderze, który zawiera <product name>.xml pliki mapowane na instrukcje zasad dla każdego produktu.

folder portalStyles

Folder portalStyles zawiera konfigurację i arkusze stylów służące do dostosowywania przestarzałego portalu deweloperów wystąpienia usługi.

portalStyles\configuration.json — Zawiera nazwy arkuszy stylów używanych przez portal dla deweloperów
portalStyles\<style name>.css — Każdy <style name>.css plik zawiera style portalu dla deweloperów (Preview.css i Production.css domyślnie).

folder portalTemplates

Folder portalTemplates zawiera szablony dostosowywania przestarzałego portalu deweloperów wystąpienia usługi.

portalTemplates\<template name>\configuration.json - Konfiguracja szablonu.
portalTemplates\<template name>\<page name>.html - Oryginalne i zmodyfikowane strony HTML szablonu.

folder products

Folder products zawiera folder dla każdego produktu zdefiniowanego w wystąpieniu usługi.

products\<product name>\configuration.json - Konfiguracja produktu. Są to te same informacje, które zostaną zwrócone w przypadku wywołania operacji Uzyskiwanie określonego produktu .
products\<product name>\product.description.html — Opis produktu odpowiadający description właściwości jednostki produktu w interfejsie API REST.

szablony

Folder templates zawiera konfigurację szablonów wiadomości e-mail wystąpienia usługi.

<template name>\configuration.json — Konfiguracja szablonu wiadomości e-mail.
<template name>\body.html — Treść szablonu wiadomości e-mail.

Następne kroki

Aby uzyskać informacje na temat innych sposobów zarządzania wystąpieniem usługi, zobacz:

Udostępnij za pośrednictwem