Använda namngivna värden i Azure API Management principer

API Management principer är en kraftfull funktion i systemet som gör att utgivaren kan ändra API:ets beteende genom konfiguration. Principer är en samling instruktioner som körs sekventiellt på begäran av eller efter ett svar från ett API. Principuttryck kan konstrueras med hjälp av literaltextvärden, principuttryck och namngivna värden.

Namngivna värden är en global samling namn/värde-par i varje API Management instans. Det finns ingen begränsning för antalet objekt i samlingen. Namngivna värden kan användas för att hantera konstanta strängvärden och hemligheter i alla API-konfigurationer och principer.

Värdetyper

Oformaterad värden eller hemligheter kan innehålla principuttryck. Uttrycket returnerar till exempel @(DateTime.Now.ToString()) en sträng som innehåller aktuellt datum och tid.

Mer information om namngivna värdeattribut finns i API Management REST API referens.

Key Vault-hemligheter

Hemliga värden kan lagras antingen som krypterade strängar i API Management (anpassade hemligheter) eller genom att referera till hemligheter i Azure Key Vault.

Vi rekommenderar att du använder Key Vault-hemligheter eftersom det hjälper API Management säkerheten:

• Hemligheter som lagras i nyckelvalv kan återanvändas i olika tjänster
• Detaljerade åtkomstprinciper kan tillämpas på hemligheter
• Hemligheter som uppdateras i nyckelvalvet roteras automatiskt i API Management. Efter uppdateringen i nyckelvalvet uppdateras ett namngivet värde API Management inom 4 timmar. Du kan också uppdatera hemligheten manuellt med hjälp Azure Portal eller via REST API.

Krav för Key Vault-integrering

1. Anvisningar för hur du skapar ett nyckelvalv finns i Snabbstart: Skapa ett nyckelvalv med hjälp av Azure Portal.
2. Aktivera en system-tilldelad eller användar tilldelad hanterad identitet i API Management instansen.
3. Tilldela en åtkomstprincip för nyckelvalv till den hanterade identiteten med behörighet att hämta och lista hemligheter från valvet. Så här lägger du till principen:
   1. Navigera till ditt nyckelvalv i portalen.
   2. Välj Inställningar > Åtkomstprinciper > +Lägg till åtkomstprincip.
   3. Välj Hemliga behörigheter och sedan Hämta och Lista.
   4. I Välj huvudnamn väljer du resursnamnet för din hanterade identitet. Om du använder en system tilldelad identitet är huvudnamnet namnet på din API Management instans.
4. Skapa eller importera en hemlighet till nyckelvalvet. Se Snabbstart: Ange och hämta en hemlighet från Azure Key Vault med hjälp av Azure Portal.

Om du vill använda hemligheten för nyckelvalvet lägger du till eller redigerar ett namngivetvärde och anger en typ av nyckelvalv. Välj hemligheten från nyckelvalvet.

Krav för Key Vault brandvägg

Om Key Vault brandväggen är aktiverad på ditt nyckelvalv, är följande ytterligare krav:

• Du måste använda den API Management instansens system tilldelade hanterade identitet för att få åtkomst till nyckelvalvet.
• I Key Vault brandväggen aktiverar du alternativet Tillåt betrodda Microsoft-tjänster att kringgå brandväggen.

Krav för virtuellt nätverk

Om API Management-instansen distribueras i ett virtuellt nätverk konfigurerar du även följande nätverksinställningar:

• Aktivera en tjänstslutpunkt för Azure Key Vault på API Management undernätet.
• Konfigurera en regel för nätverkssäkerhetsgrupp (NSG) för att tillåta utgående trafik till tjänsttaggarna AzureKeyVault och AzureActiveDirectory.

Mer information finns i informationen om nätverkskonfiguration i Anslut till ett virtuellt nätverk.

Lägga till eller redigera ett namngivet värde

Lägga till en nyckelvalvshemlighet

Se Krav för Key Vault-integrering.

1. I Azure Portalnavigerar du till din API Management instans.

2. Under API:er väljer du Namngivna värden > +Lägg till.

3. Ange ett Namn-ID och ange ett Visningsnamn som används för att referera till egenskapen i principer.

4. I Värdetyp väljer du Nyckelvalv.

5. Ange identifieraren för en nyckelvalvshemlighet (utan version) eller välj Välj för att välja en hemlighet från ett nyckelvalv.

   Viktigt

   Om du själv anger ett nyckelvalvshemlighets-ID måste du se till att det inte har versionsinformation. Annars roteras hemligheten inte automatiskt i API Management efter en uppdatering i nyckelvalvet.

6. I Klientidentitet väljer du en system-tilldelad eller en befintlig användar tilldelad hanterad identitet. Lär dig hur du lägger till eller ändrar hanterade identiteter i API Management tjänsten.

   Anteckning

   Identiteten måste ha behörighet att hämta och lista hemligheter från nyckelvalvet. Om du inte redan har konfigurerat åtkomst till nyckelvalvet uppmanas du API Management så att den automatiskt kan konfigurera identiteten med nödvändiga behörigheter.

7. Lägg till en eller flera valfria taggar för att organisera dina namngivna värden och sedan Spara.

8. Välj Skapa.

   

Lägga till ett oformaterad eller hemligt värde

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

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

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

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

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

Använda ett namngivet värde

Exemplen i det här avsnittet använder de namngivna värden som visas i följande tabell.

Om du vill använda ett namngivet värde i en princip placerar du dess visningsnamn i ett dubbelt par med kparenteser som , som {{ContosoHeader}} du ser i följande exempel:

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

I det här ContosoHeader exemplet används som namn på en rubrik i en princip och används som värde för set-header ContosoHeaderValue rubriken. När den här principen utvärderas under en begäran eller ett svar API Management gatewayen {{ContosoHeader}} {{ContosoHeaderValue}} och ersätts med deras respektive värden.

Namngivna värden kan användas som fullständiga attribut- eller elementvärden som visas i föregående exempel, men de kan också infogas i eller kombineras med en del av ett literalt textuttryck enligt följande exempel:

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

Namngivna värden kan också innehålla principuttryck. I följande exempel används ExpressionProperty uttrycket .

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

När den här principen utvärderas {{ExpressionProperty}} ersätts med värdet @(DateTime.Now.ToString()) . Eftersom värdet är ett principuttryck utvärderas uttrycket och principen fortsätter med körningen.

Du kan testa detta i Azure Portal eller utvecklarportalen genom att anropa en åtgärd som har en princip med namngivna värden i omfånget. I följande exempel anropas en åtgärd med de två föregående set-header exempelprinciperna med namngivna värden. Observera att svaret innehåller två anpassade huvuden som har konfigurerats med principer med namngivna värden.

Om du tittar på den utgående API-spårningen för ett anrop som innehåller de två föregående exempelprinciperna med namngivna värden kan du se de två principerna med de namngivna värdena infogade samt utvärderingen av principuttryck för det namngivna värdet som innehöll set-header principuttrycket.

Namngivna värden kan innehålla principuttryck, men de får inte innehålla andra namngivna värden. Om text som innehåller en namngiven värdereferens används för ett värde, till exempel , matchas inte Text: {{MyProperty}} den referensen och ersätts inte.

Ta bort ett namngivet värde

Om du vill ta bort ett namngivet värde väljer du namnet och sedan Ta bort på snabbmenyn (...).

Nästa steg

• Läs mer om att arbeta med principer
  • Principer i API Management
  • Principreferens
  • Principuttryck