Benoemde waarden gebruiken in Azure API Management gebruiken

API Management zijn een krachtige mogelijkheid van het systeem waarmee de uitgever het gedrag van de API via configuratie kan wijzigen. Beleidsregels zijn een verzameling instructies die sequentieel worden uitgevoerd op de aanvraag of het antwoord van een API. Beleidsverklaringen kunnen worden samengesteld met letterlijke tekstwaarden, beleidsexpressie en benoemde waarden.

Benoemde waarden zijn een globale verzameling naam-waardeparen in elk API Management-exemplaar. Er is geen limiet voor het aantal items in de verzameling. Benoemde waarden kunnen worden gebruikt voor het beheren van constante tekenreekswaarden en geheimen in alle API-configuraties en -beleidsregels.

Waardetypen

Gewone waarden of geheimen kunnen beleidsexpressies bevatten. De expressie retourneert @(DateTime.Now.ToString()) bijvoorbeeld een tekenreeks met de huidige datum en tijd.

Zie voor meer informatie over de kenmerken van de benoemde waarde de API Management REST API verwijzing.

Key Vault-geheimen

Geheime waarden kunnen worden opgeslagen als versleutelde tekenreeksen in API Management (aangepaste geheimen) of door te verwijzen naar geheimen in Azure Key Vault.

Het gebruik van Key Vault-geheimen wordt aanbevolen omdat dit helpt om de beveiliging API Management verbeteren:

• Geheimen die zijn opgeslagen in sleutelkluizen, kunnen opnieuw worden gebruikt in verschillende services
• Gedetailleerd toegangsbeleid kan worden toegepast op geheimen
• Geheimen die zijn bijgewerkt in de sleutelkluis, worden automatisch geroteerd in API Management. Na de update in de sleutelkluis wordt een benoemde waarde in API Management binnen vier uur bijgewerkt. U kunt het geheim ook handmatig vernieuwen met behulp van de Azure Portal of via het REST API.

Vereisten voor key vault-integratie

1. Zie Voor stappen voor het maken van een sleutelkluis Quickstart: Een sleutelkluis makenmet behulp van de Azure Portal.
2. Schakel een door het systeem toegewezen of door de gebruiker toegewezen beheerde identiteit in het API Management in.
3. Wijs een toegangsbeleid voor een sleutelkluis toe aan de beheerde identiteit met machtigingen om geheimen op te halen en weer te geven uit de kluis. Het beleid toevoegen:
   1. Navigeer in de portal naar uw sleutelkluis.
   2. Selecteer Instellingen > toegangsbeleid > +Toegangsbeleid toevoegen.
   3. Selecteer Geheime machtigingen en selecteer vervolgens Get en List.
   4. Selecteer in Principal selecteren de resourcenaam van uw beheerde identiteit. Als u een door het systeem toegewezen identiteit gebruikt, is de principal de naam van uw API Management-exemplaar.
4. Maak of importeer een geheim in de sleutelkluis. Zie Quickstart: Een geheim instellen en ophalen uit Azure Key Vault met behulp van Azure Portal.

Als u het sleutelkluisgeheim wilt gebruiken, voegt u een benoemde waardetoe of bewerkt u deze en geeft u het type Sleutelkluis op. Selecteer het geheim in de sleutelkluis.

Vereisten voor Key Vault firewall

Als Key Vault firewall is ingeschakeld voor uw sleutelkluis, zijn de volgende aanvullende vereisten:

• U moet de door API Management door het systeem toegewezen beheerde identiteit van het exemplaar gebruiken om toegang te krijgen tot de sleutelkluis.
• Schakel Key Vault de optie Vertrouwde Microsoft-services toestaan deze firewall over te laten in Key Vault firewall.

Vereisten voor het virtuele netwerk

Als het API Management is geïmplementeerd in een virtueel netwerk, moet u ook de volgende netwerkinstellingen configureren:

• Schakel een service-eindpunt in Azure Key Vault in het API Management subnet.
• Configureer een regel voor een netwerkbeveiligingsgroep (NSG) om uitgaand verkeer naar de servicetags AzureKeyVault en AzureActiveDirectory toe te staan.

Zie Netwerkconfiguratiedetails in Verbinding maken naar een virtueel netwerk voor meer informatie.

Een benoemde waarde toevoegen of bewerken

Een sleutelkluisgeheim toevoegen

Zie Vereisten voor key vault-integratie.

1. Blader in Azure Portal naar uw API Management-exemplaar.

2. Selecteer onder API's benoemde waarden > +Toevoegen.

3. Voer een naam-id in en voer een Weergavenaam in die wordt gebruikt om te verwijzen naar de eigenschap in beleidsregels.

4. Selecteer in Waardetype de optie Sleutelkluis.

5. Voer de id in van een sleutelkluisgeheim (zonder versie) of kies Selecteren om een geheim uit een sleutelkluis te selecteren.

   Belangrijk

   Als u zelf een geheime id voor een sleutelkluis op geeft, moet u ervoor zorgen dat deze geen versiegegevens heeft. Anders wordt het geheim niet automatisch geroteerd in API Management na een update in de sleutelkluis.

6. Selecteer in Clientidentiteit een door het systeem toegewezen of een bestaande door de gebruiker toegewezen beheerde identiteit. Meer informatie over het toevoegen of wijzigen van beheerde identiteiten in API Management service.

   Notitie

   De identiteit heeft machtigingen nodig om geheimen uit de sleutelkluis op te halen en weer te geven. Als u de toegang tot de sleutelkluis nog niet hebt geconfigureerd, wordt API Management gevraagd om de identiteit automatisch te configureren met de benodigde machtigingen.

7. Voeg een of meer optionele tags toe om de benoemde waarden te organiseren en klik vervolgens op Opslaan.

8. Selecteer Maken.

   

Een gewone of geheime waarde toevoegen

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

Een benoemde waarde gebruiken

In de voorbeelden in deze sectie worden de benoemde waarden gebruikt die in de volgende tabel worden weergegeven.

Als u een benoemde waarde in een beleid wilt gebruiken, moet u de weergavenaam binnen een dubbel paar accolades plaatsen, zoals {{ContosoHeader}} wordt weergegeven in het volgende voorbeeld:

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

In dit voorbeeld wordt gebruikt als de naam van een header in een beleid en wordt gebruikt als de ContosoHeader set-header waarde van die ContosoHeaderValue header. Wanneer dit beleid wordt geëvalueerd tijdens een aanvraag of reactie op API Management gateway en {{ContosoHeader}} wordt vervangen door de respectieve {{ContosoHeaderValue}} waarden.

Benoemde waarden kunnen worden gebruikt als volledige kenmerk- of elementwaarden zoals weergegeven in het vorige voorbeeld, maar ze kunnen ook worden ingevoegd in of gecombineerd met een deel van een letterlijke tekstexpressie, zoals wordt weergegeven in het volgende voorbeeld:

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

Benoemde waarden kunnen ook beleidsexpressie bevatten. In het volgende voorbeeld wordt de ExpressionProperty expressie gebruikt.

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

Wanneer dit beleid wordt geëvalueerd, {{ExpressionProperty}} wordt vervangen door de waarde ervan, @(DateTime.Now.ToString()) . Omdat de waarde een beleidsexpressie is, wordt de expressie geëvalueerd en wordt het beleid uitgevoerd.

U kunt dit testen in de Azure Portal of de ontwikkelaarsportal door een bewerking aan te roepen die een beleid met benoemde waarden binnen het bereik heeft. In het volgende voorbeeld wordt een bewerking aangeroepen met de twee vorige set-header voorbeeldbeleidsregels met benoemde waarden. U ziet dat het antwoord twee aangepaste headers bevat die zijn geconfigureerd met behulp van beleidsregels met benoemde waarden.

Als u de uitgaande API-traceer bekijkt voor een aanroep die de twee vorige voorbeeldbeleidsregels met benoemde waarden bevat, ziet u de twee beleidsregels met de benoemde waarden die zijn ingevoegd, evenals de evaluatie van de beleidsexpressie voor de benoemde waarde die de beleidsexpressie set-header bevat.

Benoemde waarden kunnen beleidsexpressies bevatten, maar ze kunnen geen andere benoemde waarden bevatten. Als tekst met een verwijzing naar een benoemde waarde wordt gebruikt voor een waarde, zoals , wordt die verwijzing niet Text: {{MyProperty}} opgelost en vervangen.

Een benoemde waarde verwijderen

Als u een benoemde waarde wilt verwijderen, selecteert u de naam en selecteert u vervolgens Verwijderen in het contextmenu (...).

Volgende stappen

• Meer informatie over het werken met beleidsregels
  • Beleid in API Management
  • Naslaginformatie over beleidsregels
  • Beleidsexpressies