Použití pojmenovaných hodnot v zásadách služby Azure API Management

PLATÍ PRO: Všechny úrovně služby API Management

Zásady služby API Management představují výkonnou funkci systému, která vydavateli umožňuje změnit chování rozhraní API prostřednictvím konfigurace. Zásady představují kolekci příkazů, které se postupně provádí na základě požadavku nebo odezvy z rozhraní API. Příkazy zásad je možné vytvořit pomocí textových hodnot literálů, výrazů zásad a pojmenovaných hodnot.

Pojmenované hodnoty jsou globální kolekce párů názvů a hodnot v každé instanci služby API Management. Počet položek v kolekci není nijak omezen. Pojmenované hodnoty se dají použít ke správě konstantních řetězcových hodnot a tajných kódů napříč všemi konfiguracemi a zásadami rozhraní API.

Typy hodnot

Typ	Popis
Prostý	Literálový řetězec nebo výraz zásad
Tajný	Řetězcový literál nebo výraz zásad, který je šifrovaný službou API Management
Trezor klíčů	Identifikátor tajného klíče uloženého v trezoru klíčů Azure.

Prosté hodnoty nebo tajné kódy můžou obsahovat výrazy zásad. Výraz například @(DateTime.Now.ToString()) vrátí řetězec obsahující aktuální datum a čas.

Podrobnosti o pojmenovaných atributech hodnot najdete v referenčních informacích k rozhraní REST API služby API Management.

Tajné kódy trezoru klíčů

Hodnoty tajných kódů je možné uložit buď jako šifrované řetězce ve službě API Management (vlastní tajné kódy), nebo odkazovat na tajné kódy ve službě Azure Key Vault.

Použití tajných kódů trezoru klíčů se doporučuje, protože pomáhá zlepšit zabezpečení služby API Management:

• Tajné kódy uložené v trezorech klíčů je možné opakovaně používat napříč službami.
• Podrobné zásady přístupu se dají použít na tajné kódy.
• Tajné kódy aktualizované v trezoru klíčů se ve službě API Management automaticky obměňují. Po aktualizaci v trezoru klíčů se pojmenovaná hodnota ve službě API Management aktualizuje do 4 hodin. Tajný kód můžete aktualizovat také ručně pomocí webu Azure Portal nebo přes rozhraní REST API pro správu.

Požadavky

• Pokud jste ještě nevytvořili instanci služby API Management, přečtěte si téma Vytvoření instance služby API Management.

Požadavky na integraci trezoru klíčů

• Pokud ještě trezor klíčů nemáte, vytvořte ho. Postup vytvoření trezoru klíčů najdete v tématu Rychlý start: Vytvoření trezoru klíčů pomocí webu Azure Portal.

  Informace o vytvoření nebo importu tajného kódu do trezoru klíčů najdete v tématu Rychlý start: Nastavení a načtení tajného klíče ze služby Azure Key Vault pomocí webu Azure Portal.

• Povolte spravovanou identitu přiřazenou systémem nebo přiřazenou uživatelem v instanci služby API Management.

Konfigurace přístupu k trezoru klíčů

1. Na portálu přejděte do trezoru klíčů.

2. V nabídce vlevo vyberte konfiguraci accessu a poznamenejte si nakonfigurovaný model oprávnění.

3. V závislosti na modelu oprávnění nakonfigurujte zásady přístupu trezoru klíčů nebo přístup Azure RBAC pro spravovanou identitu služby API Management.

   Přidání zásady přístupu trezoru klíčů:
   

   1. V nabídce vlevo vyberte Zásady přístupu.
   2. Na stránce Zásady přístupu vyberte + Vytvořit.
   3. Na kartě Oprávnění v části Oprávnění vyberte Získat a Seznam a pak vyberte Další.
   4. Na kartě Objekt zabezpečení vyberte objekt zabezpečení, vyhledejte název prostředku vaší spravované identity a pak vyberte Další. Pokud používáte identitu přiřazenou systémem, objekt zabezpečení je název vaší instance služby API Management.
   5. Znovu vyberte Další . Na kartě Revize a vytvoření vyberte Vytvořit.

   Konfigurace přístupu Azure RBAC:
   

   1. V nabídce vlevo vyberte Řízení přístupu (IAM).
   2. Na stránce Řízení přístupu (IAM) vyberte Přidat přiřazení role.
   3. Na kartě Role vyberte uživatele tajných kódů služby Key Vault.
   4. Na kartě Členové vyberte Spravovaná identita> + Vybrat členy.
   5. Na stránce Vybrat spravovanou identitu vyberte spravovanou identitu přiřazenou systémem nebo spravovanou identitu přiřazenou uživatelem přidruženou k vaší instanci služby API Management a pak vyberte Vybrat.
   6. Vyberte Zkontrolovat + přiřadit.

Požadavky na bránu firewall služby Key Vault

Pokud je ve vašem trezoru klíčů povolená brána firewall služby Key Vault, jsou další požadavky:

• Pro přístup k trezoru klíčů musíte použít spravovanou identitu přiřazenou systémem instance služby API Management.

• V bráně firewall služby Key Vault povolte, aby tuto možnost brány firewall vynechala důvěryhodná služba Microsoftu.

• Ujistěte se, že vaše IP adresa místního klienta má povolený přístup k trezoru klíčů dočasně, když vyberete certifikát nebo tajný klíč pro přidání do služby Azure API Management. Další informace najdete v tématu Konfigurace nastavení sítě služby Azure Key Vault.

  Po dokončení konfigurace můžete zablokovat adresu klienta v bráně firewall trezoru klíčů.

Požadavky na virtuální síť

Pokud je instance služby API Management nasazená ve virtuální síti, nakonfigurujte také následující nastavení sítě:

• Povolte koncový bod služby do služby Azure Key Vault v podsíti služby API Management.
• Nakonfigurujte pravidlo skupiny zabezpečení sítě (NSG), které povolí odchozí provoz do značek služeb AzureKeyVault a AzureActiveDirectory.

Podrobnosti najdete v tématu Konfigurace sítě při nastavování služby Azure API Management ve virtuální síti.

Přidání nebo úprava pojmenované hodnoty

Přidání tajného klíče trezoru klíčů do služby API Management

Viz Požadavky pro integraci trezoru klíčů.

Důležité

Při přidávání tajného kódu trezoru klíčů do instance služby API Management musíte mít oprávnění k výpisu tajných kódů z trezoru klíčů.

Upozornění

Při použití tajného klíče trezoru klíčů ve službě API Management dávejte pozor, abyste neodstraňovat tajný klíč, trezor klíčů nebo spravovanou identitu použitou pro přístup k trezoru klíčů.

1. Na webu Azure Portal přejděte k vaší instanci služby API Management.

2. V části Rozhraní API vyberte Pojmenované hodnoty>+ Přidat.

3. Zadejte identifikátor názvu a zadejte zobrazovaný název, který se používá pro odkaz na vlastnost v zásadách.

4. V hodnotě typu vyberte Trezor klíčů.

5. Zadejte identifikátor tajného klíče trezoru klíčů (bez verze) nebo zvolte Vybrat a vyberte tajný klíč z trezoru klíčů.

   Důležité

   Pokud zadáte identifikátor tajného klíče trezoru klíčů sami, ujistěte se, že neobsahuje informace o verzi. Jinak se tajný klíč po aktualizaci v trezoru klíčů automaticky neobměňuje ve službě API Management.

6. V části Identita klienta vyberte spravovanou identitu přiřazenou systémem nebo existující spravovanou identitu přiřazenou uživatelem. Naučte se přidávat nebo upravovat spravované identity ve službě API Management.

   Poznámka:

   Identita potřebuje oprávnění k získání a výpisu tajných kódů z trezoru klíčů. Pokud jste ještě nenakonfigurovali přístup k trezoru klíčů, služba API Management vás vyzve, aby automaticky nakonfigurovala identitu s potřebnými oprávněními.

7. Přidejte jednu nebo více volitelných značek, které vám pomůžou uspořádat pojmenované hodnoty a pak uložit.

8. Vyberte Vytvořit.

   

Přidání hodnoty prostého nebo tajného kódu do služby API Management

Azure Portal

1. Na webu Azure Portal přejděte k vaší instanci služby API Management.
2. V části Rozhraní API vyberte Pojmenované hodnoty>+ Přidat.
3. Zadejte identifikátor názvu a zadejte zobrazovaný název, který se používá pro odkaz na vlastnost v zásadách.
4. V typu Hodnota vyberte Prostý nebo Tajný kód.
5. Do pole Hodnota zadejte řetězec nebo výraz zásad.
6. Přidejte jednu nebo více volitelných značek, které vám pomůžou uspořádat pojmenované hodnoty a pak uložit.
7. Vyberte Vytvořit.

Po vytvoření pojmenované hodnoty ji můžete upravit výběrem názvu. Pokud změníte zobrazovaný název, všechny zásady, které odkazují na pojmenovanou hodnotu, se automaticky aktualizují tak, aby používaly nový zobrazovaný název.

Azure CLI

Jak začít používat Azure CLI:

• Použijte prostředí Bash v Azure Cloud Shellu. Další informace najdete v tématu Rychlý start pro Bash v Azure Cloud Shellu.

  

• Pokud dáváte přednost místnímu spouštění referenčních příkazů rozhraní příkazového řádku, nainstalujte Azure CLI. Pokud používáte Windows nebo macOS, zvažte spuštění Azure CLI v kontejneru Docker. Další informace najdete v tématu Jak spustit Azure CLI v kontejneru Dockeru.

  • Pokud používáte místní instalaci, přihlaste se k Azure CLI pomocí příkazu az login. Pokud chcete dokončit proces ověřování, postupujte podle kroků zobrazených na terminálu. Další možnosti přihlášení najdete v tématu Přihlášení pomocí Azure CLI.

  • Po zobrazení výzvy nainstalujte rozšíření Azure CLI při prvním použití. Další informace o rozšířeních najdete v tématu Využití rozšíření v Azure CLI.

  • Spuštěním příkazu az version zjistěte verzi a závislé knihovny, které jsou nainstalované. Pokud chcete upgradovat na nejnovější verzi, spusťte az upgrade.

Pokud chcete přidat pojmenovanou hodnotu, použijte příkaz az apim nv create :

az apim nv create --resource-group apim-hello-word-resource-group \
    --display-name "named_value_01" --named-value-id named_value_01 \
    --secret true --service-name apim-hello-world --value test

Po vytvoření pojmenované hodnoty ji můžete aktualizovat pomocí příkazu az apim nv update . Pokud chcete zobrazit všechny pojmenované hodnoty, spusťte příkaz az apim nv list :

az apim nv list --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --output table

Pokud chcete zobrazit podrobnosti o pojmenované hodnotě, kterou jste vytvořili v tomto příkladu, spusťte příkaz az apim nv show :

az apim nv show --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

Tento příklad je hodnota tajného kódu. Předchozí příkaz nevrací hodnotu. Pokud chcete zobrazit hodnotu, spusťte příkaz az apim nv show-secret :

az apim nv show-secret --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

Pokud chcete odstranit pojmenovanou hodnotu, použijte příkaz az apim nv delete :

az apim nv delete --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

Použití pojmenované hodnoty

Příklady v této části používají pojmenované hodnoty uvedené v následující tabulce.

Jméno	Hodnota	Tajný
ContosoHeader	TrackingId	False
ContosoHeaderValue	••••••••••••••••••••••	True
ExpressionProperty	@(DateTime.Now.ToString())	False
ContosoHeaderValue2	This is a header value.	False

Pokud chcete v zásadě použít pojmenovanou hodnotu, umístěte její zobrazovaný název do dvojité dvojice složených závorek {{ContosoHeader}}, jak je znázorněno v následujícím příkladu:

<set-header name="{{ContosoHeader}}" exists-action="override">
  <value>{{ContosoHeaderValue}}</value>
</set-header>

V tomto příkladu ContosoHeader se používá jako název hlavičky v set-header zásadě a ContosoHeaderValue slouží jako hodnota této hlavičky. Když se tato zásada vyhodnotí během požadavku nebo odpovědi na bránu {{ContosoHeader}} služby API Management a {{ContosoHeaderValue}} nahradí se příslušnými hodnotami.

Pojmenované hodnoty lze použít jako úplný atribut nebo hodnoty prvků, jak je znázorněno v předchozím příkladu, ale dají se také vložit nebo kombinovat s částí literálového textového výrazu, jak je znázorněno v následujícím příkladu:

<set-header name = "CustomHeader{{ContosoHeader}}" ...>

Pojmenované hodnoty mohou také obsahovat výrazy zásad. V následujícím příkladu se ExpressionProperty výraz použije.

<set-header name="CustomHeader" exists-action="override">
    <value>{{ExpressionProperty}}</value>
</set-header>

Při vyhodnocování {{ExpressionProperty}} této zásady se nahradí hodnotou @(DateTime.Now.ToString()). Vzhledem k tomu, že hodnota je výraz zásad, výraz se vyhodnotí a zásada pokračuje jeho spuštěním.

Můžete to otestovat na webu Azure Portal nebo na portálu pro vývojáře voláním operace, která má zásadu s pojmenovanými hodnotami v oboru. V následujícím příkladu se volá operace se dvěma předchozími ukázkovými set-header zásadami s pojmenovanými hodnotami. Všimněte si, že odpověď obsahuje dvě vlastní hlavičky, které byly nakonfigurovány pomocí zásad s pojmenovanými hodnotami.

Pokud se podíváte na trasování odchozího rozhraní API pro volání, které obsahuje dvě předchozí ukázkové zásady s pojmenovanými hodnotami, uvidíte dvě set-header zásady s vloženými pojmenovanými hodnotami a také vyhodnocení výrazu zásad pro pojmenovanou hodnotu, která obsahovala výraz zásad.

Interpolace řetězců se dá použít také s pojmenovanými hodnotami.

<set-header name="CustomHeader" exists-action="override">
    <value>@($"The URL encoded value is {System.Net.WebUtility.UrlEncode("{{ContosoHeaderValue2}}")}")</value>
</set-header>

Hodnota bude CustomHeaderThe URL encoded value is This+is+a+header+value..

Upozornění

Pokud zásada odkazuje na tajný klíč ve službě Azure Key Vault, bude hodnota z trezoru klíčů viditelná uživatelům, kteří mají přístup k předplatným povoleným pro trasování požadavků rozhraní API.

Pojmenované hodnoty sice můžou obsahovat výrazy zásad, ale nemůžou obsahovat jiné pojmenované hodnoty. Pokud se pro hodnotu použije text obsahující pojmenovaný odkaz na hodnotu, například Text: {{MyProperty}}, tento odkaz se nepřeloží a nahradí.

Odstranění pojmenované hodnoty

Pokud chcete odstranit pojmenovanou hodnotu, vyberte název a pak v místní nabídce (...) vyberte Odstranit.

Důležité

Pokud na pojmenovanou hodnotu odkazují nějaké zásady služby API Management, nemůžete ji odstranit, dokud pojmenovanou hodnotu neodeberete ze všech zásad, které ji používají.

Další kroky

• Další informace o práci se zásadami
  • Zásady ve službě API Management
  • referenční příručce o zásadách
  • Výrazy zásad