Uložení a konfigurace nastavení služby API Management pomocí Gitu

Článek
10/24/2023

PLATÍ PRO: Vývojář | Základní | Standardní | Premium

Každá instance služby API Management udržuje konfigurační databázi, která obsahuje informace o konfiguraci a metadatech instance služby. Změny instance služby je možné provést změnou nastavení v Azure Portal pomocí nástrojů Azure, jako jsou Azure PowerShell nebo Azure CLI, nebo voláním rozhraní REST API. Kromě těchto metod můžete spravovat konfiguraci instance služby pomocí Gitu a povolit například následující scénáře:

Správa verzí konfigurace – Stažení a uložení různých verzí konfigurace služby
Hromadné změny konfigurace – Proveďte změny v několika částech konfigurace služby v místním úložišti a integrujte změny zpět na server pomocí jedné operace.
Známá sada nástrojů a pracovní postup Gitu – Použijte nástroje a pracovní postupy Gitu, které už znáte.

Následující diagram znázorňuje přehled různých způsobů konfigurace instance služby API Management.

Diagram, který porovnává způsoby konfigurace služby Azure API Management

Když ve své službě provedete změny pomocí webu Azure Portal, nástrojů Azure, jako je Azure PowerShell nebo Azure CLI nebo rozhraní REST API, spravujete konfigurační databázi služeb pomocí koncového https://{name}.management.azure-api.net bodu, jak je znázorněno na pravé straně diagramu. Na levé straně diagramu je znázorněno, jak můžete spravovat konfiguraci služby pomocí úložiště Git a Git pro vaši službu umístěnou na adrese https://{name}.scm.azure-api.net.

Následující kroky poskytují přehled správy instance služby API Management pomocí Gitu.

Přístup ke konfiguraci Gitu ve vaší službě
Uložení konfigurační databáze služby do úložiště Git
Klonování úložiště Git do místního počítače
Stáhněte si nejnovější úložiště do místního počítače a potvrďte a nasdílejte změny zpět do úložiště.
Nasazení změn z úložiště do konfigurační databáze služby

Tento článek popisuje, jak povolit a používat Git ke správě konfigurace služby a poskytuje referenční informace o souborech a složkách v úložišti Git.

Důležité

Tato funkce je navržená tak, aby fungovala s malými až středními konfiguracemi služeb API Management, například s exportovanou velikostí menší než 10 MB nebo s méně než 10 000 entitami. U služeb s velkým počtem entit (produkty, rozhraní API, operace, schémata atd.) může dojít při zpracování příkazů Gitu k neočekávaným selháním. Pokud narazíte na taková selhání, zmenšete konfiguraci služby a zkuste to znovu. Pokud potřebujete pomoc, obraťte se na podporu Azure.

Přístup ke konfiguraci Gitu ve vaší službě

Na webu Azure Portal přejděte k vaší instanci služby API Management.
V nabídce vlevo v části Nasazení a infrastruktura vyberte Úložiště.

Snímek obrazovky znázorňující přístup ke konfiguraci Gitu pro API Management

Uložení konfigurace služby do úložiště Git

Upozornění

Všechny tajné kódy, které nejsou definovány jako pojmenované hodnoty, budou uloženy v úložišti a zůstanou v historii. Pojmenované hodnoty poskytují bezpečné místo pro správu konstantních řetězcových hodnot, včetně tajných kódů, napříč všemi konfiguracemi a zásadami rozhraní API, takže je nemusíte ukládat přímo do příkazů zásad. Další informace najdete v tématu Použití pojmenovaných hodnot v zásadách služby Azure API Management.

Před klonováním úložiště uložte aktuální stav konfigurace služby do úložiště.

Na stránce Úložiště vyberte Uložit do úložiště.
Na potvrzovací obrazovce proveďte požadované změny, například název větve pro uložení konfigurace, a vyberte Uložit.

Po chvíli se konfigurace uloží a zobrazí se stav konfigurace úložiště, včetně data a času poslední změny konfigurace a poslední synchronizace mezi konfigurací služby a úložištěm.

Jakmile se konfigurace uloží do úložiště, můžete ji naklonovat.

Informace o uložení konfigurace služby pomocí rozhraní REST API najdete v tématu Konfigurace tenanta – Uložit.

Získání přihlašovacích údajů pro přístup

Pokud chcete naklonovat úložiště, kromě adresy URL do úložiště potřebujete uživatelské jméno a heslo.

Na stránce Úložiště vyberte přístupové přihlašovací údaje v horní části stránky.
Poznamenejte si uživatelské jméno zadané na stránce přihlašovacích údajů accessu.
Pokud chcete vygenerovat heslo, nejprve se ujistěte, že je vypršení platnosti nastavené na požadované datum a čas vypršení platnosti, a pak vyberte Generovat.

Důležité

Poznamenejte si toto heslo. Po opuštění této stránky se heslo znovu nezobrazí.

Klonování úložiště do místního počítače

Následující příklady používají nástroj Git Bash z Gitu pro Windows , ale můžete použít jakýkoli nástroj Git, který znáte.

Otevřete nástroj Git v požadované složce a spuštěním následujícího příkazu naklonujte úložiště Git do místního počítače pomocí následujícího příkazu:

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

Po zobrazení výzvy zadejte uživatelské jméno a heslo.

Pokud se zobrazí nějaké chyby, zkuste git clone příkaz upravit tak, aby zahrnoval uživatelské jméno a heslo, jak je znázorněno v následujícím příkladu.

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

Pokud se zobrazí chyba, zkuste adresu URL kódovat část hesla příkazu. Jedním z rychlých způsobů, jak to udělat, je otevřít Visual Studio a vydat následující příkaz v příkazovém okně. Pokud chcete otevřít okamžité okno, otevřete jakékoli řešení nebo projekt v sadě Visual Studio (nebo vytvořte novou prázdnou konzolovou aplikaci) a v nabídce Ladění zvolte Windows, Okamžitě.

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

Pomocí zakódovaného hesla spolu s uživatelským jménem a umístěním úložiště vytvořte příkaz Git.

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

Po dokončení klonování změňte adresář do úložiště spuštěním příkazu podobného následujícímu.

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

Pokud jste konfiguraci uložili do jiné větve, než je výchozí větev (master), podívejte se na větev:

git checkout <branch_name>

Jakmile se úložiště naklonuje, můžete ho zobrazit a pracovat s ním v místním systému souborů. Další informace najdete v tématu Odkaz na strukturu souborů a složek místního úložiště Git.

Aktualizace místního úložiště s použitím nejnovější konfigurace instance služby

Pokud provedete změny instance služby API Management na webu Azure Portal nebo pomocí jiných nástrojů Azure, musíte tyto změny uložit do úložiště, abyste mohli aktualizovat místní úložiště nejnovějšími změnami.

Pokud chcete uložit změny pomocí webu Azure Portal, vyberte Uložit do úložiště na kartě Úložiště pro vaši instanci služby API Management.

Potom aktualizujte místní úložiště:

Ujistěte se, že jste ve složce místního úložiště. Pokud jste příkaz právě dokončili git clone , musíte změnit adresář na úložiště spuštěním příkazu podobného následujícímu.
```
cd {name}.scm.azure-api.net/
```
Ve složce místního úložiště zadejte následující příkaz.
```
git pull
```

Nasdílení změn z místního úložiště do úložiště serveru

Pokud chcete odeslat změny z místního úložiště do úložiště serveru, musíte změny potvrdit a pak je odeslat do úložiště serveru. Pokud chcete potvrdit změny, otevřete nástroj pro příkaz Git, přepněte do adresáře místního úložiště a zadejte následující příkazy.

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

Pokud chcete odeslat všechna potvrzení na server, spusťte následující příkaz.

git push

Nasazení změn konfigurace služby do instance služby API Management

Jakmile se místní změny potvrdí a nasdílí do úložiště serveru, můžete je nasadit do instance služby API Management.

Na webu Azure Portal přejděte k vaší instanci služby API Management.
V nabídce vlevo v části Nasazení a infrastruktura vyberte Úložiště>nasadit do služby API Management.
Na stránce Konfigurace nasazení úložiště zadejte název větve obsahující požadované změny konfigurace a volitelně vyberte Odebrat předplatná odstraněných produktů. Zvolte Uložit.

Informace o provedení této operace pomocí rozhraní REST API najdete v tématu Konfigurace tenanta – Nasazení.

Odkaz na strukturu souborů a složek místního úložiště Git

Soubory a složky v místním úložišti Git obsahují informace o konfiguraci instance služby.

Položka	Popis
kořenová složka api-management	Obsahuje konfiguraci nejvyšší úrovně pro instanci služby.
složka apiReleases	Obsahuje konfiguraci pro vydané verze rozhraní API v instanci služby.
Složka apis	Obsahuje konfiguraci pro rozhraní API v instanci služby.
složka apiVersionSets	Obsahuje konfiguraci pro sady verzí rozhraní API v instanci služby.
back-endová složka	Obsahuje konfiguraci back-endových prostředků v instanci služby.
složka groups	Obsahuje konfiguraci pro skupiny v instanci služby.
složka policies	Obsahuje zásady v instanci služby.
složka portalStyles	Obsahuje konfiguraci pro přizpůsobení portálu pro vývojáře v instanci služby.
složka portalTemplates	Obsahuje konfiguraci šablon portálu pro vývojáře v instanci služby.
products folder	Obsahuje konfiguraci pro produkty v instanci služby.
templates folder	Obsahuje konfiguraci pro e-mailové šablony v instanci služby.

Každá složka může obsahovat jeden nebo více souborů a v některých případech jednu nebo více složek, například složku pro každé rozhraní API, produkt nebo skupinu. Soubory v každé složce jsou specifické pro typ entity, který popisuje název složky.

Typ souboru	Účel
json	Informace o konfiguraci příslušné entity
html	Popisy o entitě, často zobrazené na portálu pro vývojáře
xml	Příkazy zásad
Css	Šablony stylů pro přizpůsobení portálu pro vývojáře

Tyto soubory je možné vytvářet, odstraňovat, upravovat a spravovat v místním systému souborů a změny nasazené zpět do instance služby API Management.

Poznámka:

Následující entity nejsou obsaženy v úložišti Git a není možné je nakonfigurovat pomocí Gitu.

Uživatelé
Předplatná
Pojmenované hodnoty
Entity portálu pro vývojáře jiné než styly a šablony
Fragmenty zásad

Kořenová složka api-management

Kořenová api-management složka obsahuje configuration.json soubor, který obsahuje informace nejvyšší úrovně o instanci služby v následujícím formátu.

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

První čtyři nastavení (, , a ) se mapuje na následující nastavení na kartě Identity v části Portál pro vývojáře.UserRegistrationTermsConsentRequiredUserRegistrationTermsEnabledUserRegistrationTermsRegistrationEnabled

Nastavení identity	Mapy do
RegistrationEnabled	Přítomnost zprostředkovatele identity uživatelského jména a hesla
UserRegistrationTerms	Podmínky použití v textovém poli registrace uživatele
UserRegistrationTermsEnabled	Zaškrtávací políčko Zobrazit podmínky použití na registrační stránce
UserRegistrationTermsConsentRequired	Vyžadovat zaškrtnutí políčka souhlasu
RequireUserSigninEnabled	Přesměrování anonymních uživatelů na zaškrtávací políčko přihlašovací stránky

Následující čtyři nastavení (, , a ) se mapuje na následující nastavení na kartě Delegování v části Portál pro vývojáře.DelegationValidationKeyDelegatedSubscriptionEnabledDelegationUrlDelegationEnabled

Nastavení delegování	Mapy do
Delegování	Zaškrtávací políčko delegovat přihlášení a registraci
Delegování	Textové pole adresy URL koncového bodu delegování
DelegatedSubscriptionEnabled	Delegování předplatného produktu – zaškrtávací políčko
DelegationValidationKey	Delegování ověřovacího klíče – textové pole

Konečné nastavení $ref-policy, , mapovat na soubor globální zásady prohlášení pro instanci služby.

složka apiReleases

Složka apiReleases obsahuje složku pro každou verzi rozhraní API nasazenou do produkčního rozhraní API a obsahuje následující položky.

apiReleases\<api release Id>\configuration.json – Konfigurace pro vydání, která obsahuje informace o datech vydání. Jedná se o stejné informace, které by se vrátily, pokud byste chtěli volat operaci získání konkrétní verze .

Složka apis

Složka apis obsahuje složku pro každé rozhraní API v instanci služby, která obsahuje následující položky.

apis\<api name>\configuration.json – Konfigurace rozhraní API obsahující informace o adrese URL back-endové služby a operacích. Jedná se o stejné informace, které by se vrátily, pokud byste chtěli volat konkrétní operaci rozhraní API .
apis\<api name>\api.description.html – Popis rozhraní API odpovídající description vlastnosti entity rozhraní API v rozhraní REST API.
apis\<api name>\operations\ – Složka obsahující <operation name>.description.html soubory, které se mapuje na operace v rozhraní API. Každý soubor obsahuje popis jedné operace v rozhraní API, která se mapuje na description vlastnost entity operace v rozhraní REST API.

složka apiVersionSets

Složka apiVersionSets obsahuje složku pro každou sadu verzí rozhraní API vytvořenou pro rozhraní API a obsahuje následující položky.

apiVersionSets\<api version set Id>\configuration.json – Konfigurace pro sadu verzí. Jedná se o stejné informace, které by se vrátily, pokud byste chtěli volat operaci Získat konkrétní sadu verzí .

složka groups

Složka groups obsahuje složku pro každou skupinu definovanou v instanci služby.

groups\<group name>\configuration.json - Konfigurace pro skupinu. Jedná se o stejné informace, které by se vrátily, pokud byste chtěli volat operaci Získat konkrétní skupinu .
groups\<group name>\description.html - Popis skupiny odpovídající description vlastnosti entity skupiny.

složka policies

Složka policies obsahuje prohlášení o zásadách pro vaši instanci služby.

policies\global.xml – Zásady definované v globálním rozsahu pro vaši instanci služby.
policies\apis\<api name>\ – Pokud máte zásady definované v oboru rozhraní API, jsou obsažené v této složce.
policies\apis\<api name>\<operation name>\ složka – Pokud máte zásady definované v oboru operace, jsou obsaženy v této složce v <operation name>.xml souborech, které se mapují na prohlášení o zásadách pro každou operaci.
policies\products\ – Pokud máte zásady definované v rozsahu produktu, jsou obsaženy v této složce, které obsahují <product name>.xml soubory, které se mapují na prohlášení o zásadách pro každý produkt.

složka portalStyles

Složka portalStyles obsahuje konfigurační a šablony stylů pro přizpůsobení zastaralého portálu pro vývojáře instance služby.

portalStyles\configuration.json – Obsahuje názvy šablon stylů používané portálem pro vývojáře.
portalStyles\<style name>.css – Každý <style name>.css soubor obsahuje styly pro portál pro vývojáře (Preview.css a Production.css ve výchozím nastavení).

složka portalTemplates

Složka portalTemplates obsahuje šablony pro přizpůsobení zastaralého portálu pro vývojáře instance služby.

portalTemplates\<template name>\configuration.json - Konfigurace šablony.
portalTemplates\<template name>\<page name>.html - Původní a změněné stránky HTML šablony.

products folder

Složka products obsahuje složku pro každý produkt definovaný v instanci služby.

products\<product name>\configuration.json - Konfigurace produktu. Jedná se o stejné informace, které by se vrátily, pokud byste volali operaci Získání konkrétního produktu .
products\<product name>\product.description.html - Popis produktu, který odpovídá description vlastnosti entity produktu v rozhraní REST API.

šablony

Složka templates obsahuje konfiguraci pro e-mailové šablony instance služby.

<template name>\configuration.json - Konfigurace šablony e-mailu.
<template name>\body.html - Text e-mailové šablony.

Další kroky

Informace o dalších způsobech správy instance služby najdete v těchto tématech: