Używanie nazwanych wartości w zasadach usługi Azure API Management

DOTYCZY: Wszystkie warstwy usługi API Management

Zasady usługi API Management to zaawansowana funkcja systemu, która umożliwia wydawcy zmianę zachowania interfejsu API za pomocą konfiguracji. Zasady to zbiór instrukcji, które są wykonywane sekwencyjnie podczas żądania lub odpowiedzi interfejsu API. Instrukcje zasad można tworzyć przy użyciu wartości tekstowych literału, wyrażeń zasad i nazwanych wartości.

Nazwane wartości to globalna kolekcja par nazw/wartości w każdym wystąpieniu usługi API Management. Nie ma nałożonego limitu liczby elementów w kolekcji. Nazwane wartości mogą służyć do zarządzania stałymi wartościami ciągów i wpisami tajnymi we wszystkich konfiguracjach i zasadach interfejsu API.

Typy wartości

Type	Opis
Równina	Ciąg literału lub wyrażenie zasad
Klucz tajny	Ciąg literału lub wyrażenie zasad szyfrowane przez usługę API Management
Magazyn kluczy	Identyfikator wpisu tajnego przechowywanego w magazynie kluczy platformy Azure.

Zwykłe wartości lub wpisy tajne mogą zawierać wyrażenia zasad. Na przykład wyrażenie @(DateTime.Now.ToString()) zwraca ciąg zawierający bieżącą datę i godzinę.

Aby uzyskać szczegółowe informacje o nazwanych atrybutach wartości, zobacz dokumentację interfejsu API REST usługi API Management.

Wpisy tajne magazynu kluczy

Wartości wpisów tajnych mogą być przechowywane jako zaszyfrowane ciągi w usłudze API Management (niestandardowe wpisy tajne) lub przez odwołanie się do wpisów tajnych w usłudze Azure Key Vault.

Korzystanie z wpisów tajnych magazynu kluczy jest zalecane, ponieważ pomaga zwiększyć bezpieczeństwo usługi API Management:

• Wpisy tajne przechowywane w magazynach kluczy mogą być ponownie używane w usługach
• Szczegółowe zasady dostępu można stosować do wpisów tajnych
• Wpisy tajne zaktualizowane w magazynie kluczy są automatycznie obracane w usłudze API Management. Po aktualizacji w magazynie kluczy nazwana wartość w usłudze API Management zostanie zaktualizowana w ciągu 4 godzin. Możesz również ręcznie odświeżyć wpis tajny przy użyciu witryny Azure Portal lub za pośrednictwem interfejsu API REST zarządzania.

Uwaga

Wpisy tajne przechowywane w usłudze Azure Key Vault muszą mieć od 1 do 4096 znaków, ponieważ usługa API Management nie może pobrać wartości przekraczających ten limit.

Wymagania wstępne

• Jeśli jeszcze nie utworzono wystąpienia usługi API Management, zobacz Tworzenie wystąpienia usługi API Management.

Wymagania wstępne dotyczące integracji z magazynem kluczy

Uwaga

Obecnie ta funkcja nie jest dostępna w obszarach roboczych.

• Jeśli nie masz jeszcze magazynu kluczy, utwórz go. Aby uzyskać instrukcje tworzenia magazynu kluczy, zobacz Szybki start: tworzenie magazynu kluczy przy użyciu witryny Azure Portal.

  Aby utworzyć lub zaimportować wpis tajny do magazynu kluczy, zobacz Szybki start: ustawianie i pobieranie wpisu tajnego z usługi Azure Key Vault przy użyciu witryny Azure Portal.

• Włącz tożsamość zarządzaną przypisaną przez system lub przypisaną przez użytkownika w wystąpieniu usługi API Management.

Konfigurowanie dostępu do magazynu kluczy

1. W portalu przejdź do magazynu kluczy.

2. W menu po lewej stronie wybierz pozycję Konfiguracja dostępu i zanotuj skonfigurowany model uprawnień.

3. W zależności od modelu uprawnień skonfiguruj zasady dostępu magazynu kluczy lub dostęp RBAC platformy Azure dla tożsamości zarządzanej usługi API Management.

   Aby dodać zasady dostępu do magazynu kluczy:
   

   1. W menu po lewej stronie wybierz pozycję Zasady dostępu.
   2. Na stronie Zasady dostępu wybierz pozycję + Utwórz.
   3. Na karcie Uprawnienia w obszarze Uprawnienia w obszarze Uprawnienia tajne wybierz pozycję Pobierz i listę, a następnie wybierz pozycję Dalej.
   4. Na karcie Podmiot zabezpieczeń wybierz jednostkę, wyszukaj nazwę zasobu tożsamości zarządzanej, a następnie wybierz pozycję Dalej. Jeśli używasz tożsamości przypisanej przez system, podmiot zabezpieczeń to nazwa wystąpienia usługi API Management.
   5. Ponownie wybierz przycisk Dalej . Na karcie Przeglądanie i tworzenie wybierz pozycję Utwórz.

   Aby skonfigurować dostęp RBAC platformy Azure:
   

   1. W menu po lewej stronie wybierz pozycję Kontrola dostępu (Zarządzanie dostępem i tożsamościami)..
   2. Na stronie Kontrola dostępu (Zarządzanie dostępem i tożsamościami) wybierz pozycję Dodaj przypisanie roli.
   3. Na karcie Rola wybierz pozycję Użytkownik certyfikatu usługi Key Vault.
   4. Na karcie Członkowie wybierz pozycję Tożsamość> zarządzana+ Wybierz członków.
   5. Na stronie Wybieranie tożsamości zarządzanej wybierz tożsamość zarządzaną przypisaną przez system lub tożsamość zarządzaną przypisaną przez użytkownika skojarzona z wystąpieniem usługi API Management, a następnie wybierz pozycję Wybierz.
   6. Wybierz Przejrzyj + przypisz.

Wymagania dotyczące zapory usługi Key Vault

Jeśli zapora usługi Key Vault jest włączona w magazynie kluczy, są spełnione następujące dodatkowe wymagania:

• Aby uzyskać dostęp do magazynu kluczy, musisz użyć przypisanej przez system tożsamości zarządzanej wystąpienia usługi API Management.

• W zaporze usługi Key Vault włącz opcję Zezwalaj zaufanym usługom firmy Microsoft na obejście tej zapory .

• Upewnij się, że lokalny adres IP klienta może tymczasowo uzyskać dostęp do magazynu kluczy podczas wybierania certyfikatu lub wpisu tajnego, który ma zostać dodany do usługi Azure API Management. Aby uzyskać więcej informacji, zobacz Konfigurowanie ustawień sieci usługi Azure Key Vault.

  Po zakończeniu konfiguracji możesz zablokować adres klienta w zaporze magazynu kluczy.

Wymagania dotyczące sieci wirtualnej

Jeśli wystąpienie usługi API Management zostało wdrożone w sieci wirtualnej, skonfiguruj również następujące ustawienia sieciowe:

• Włącz punkt końcowy usługi w usłudze Azure Key Vault w podsieci usługi API Management.
• Skonfiguruj regułę sieciowej grupy zabezpieczeń, aby zezwolić na ruch wychodzący do tagów usługi AzureKeyVault i AzureActiveDirectory.

Aby uzyskać szczegółowe informacje, zobacz Konfiguracja sieci podczas konfigurowania usługi Azure API Management w sieci wirtualnej.

Dodawanie lub edytowanie nazwanej wartości

Dodawanie wpisu tajnego magazynu kluczy do usługi API Management

Zobacz Wymagania wstępne dotyczące integracji magazynu kluczy.

Ważne

Podczas dodawania wpisu tajnego magazynu kluczy do wystąpienia usługi API Management musisz mieć uprawnienia do wyświetlania listy wpisów tajnych z magazynu kluczy.

Uwaga

W przypadku korzystania z wpisu tajnego magazynu kluczy w usłudze API Management należy zachować ostrożność, aby nie usuwać wpisu tajnego, magazynu kluczy ani tożsamości zarządzanej używanej do uzyskiwania dostępu do magazynu kluczy.

1. W witrynie Azure Portal przejdź do wystąpienia usługi API Management.

2. W obszarze Interfejsy API wybierz pozycję Nazwane wartości>+Dodaj.

3. Wprowadź identyfikator nazwy i wprowadź nazwę wyświetlaną używaną do odwołowania się do właściwości w zasadach.

4. W polu Typ wartości wybierz pozycję Magazyn kluczy.

5. Wprowadź identyfikator wpisu tajnego magazynu kluczy (bez wersji) lub wybierz pozycję Wybierz , aby wybrać wpis tajny z magazynu kluczy.

   Ważne

   Jeśli samodzielnie wprowadzisz identyfikator wpisu tajnego magazynu kluczy, upewnij się, że nie ma informacji o wersji. W przeciwnym razie wpis tajny nie będzie automatycznie obracany w usłudze API Management po aktualizacji w magazynie kluczy.

6. W obszarze Tożsamość klienta wybierz tożsamość zarządzaną przypisaną przez system lub istniejącą tożsamość zarządzaną przypisaną przez użytkownika. Dowiedz się, jak dodawać lub modyfikować tożsamości zarządzane w usłudze API Management.

   Uwaga

   Tożsamość musi mieć uprawnienia do pobierania i wyświetlania listy wpisów tajnych z magazynu kluczy. Jeśli nie skonfigurowano jeszcze dostępu do magazynu kluczy, usługa API Management wyświetli monit o automatyczne skonfigurowanie tożsamości przy użyciu niezbędnych uprawnień.

7. Dodaj co najmniej jeden opcjonalny tag, aby ułatwić organizowanie nazwanych wartości, a następnie pozycję Zapisz.

8. Wybierz pozycję Utwórz.

   

Dodawanie wartości zwykłego lub tajnego do usługi API Management

Portal

1. W witrynie Azure Portal przejdź do wystąpienia usługi API Management.
2. W obszarze Interfejsy API wybierz pozycję Nazwane wartości>+Dodaj.
3. Wprowadź identyfikator nazwy i wprowadź nazwę wyświetlaną używaną do odwołowania się do właściwości w zasadach.
4. W polu Typ wartości wybierz pozycję Zwykły lub Tajny.
5. W polu Wartość wprowadź ciąg lub wyrażenie zasad.
6. Dodaj co najmniej jeden opcjonalny tag, aby ułatwić organizowanie nazwanych wartości, a następnie pozycję Zapisz.
7. Wybierz pozycję Utwórz.

Po utworzeniu nazwanej wartości możesz ją edytować, wybierając nazwę. Jeśli zmienisz nazwę wyświetlaną, wszystkie zasady odwołujące się do nazwanej wartości zostaną automatycznie zaktualizowane w celu użycia nowej nazwy wyświetlanej.

Interfejs wiersza polecenia platformy Azure

Aby rozpocząć korzystanie z interfejsu wiersza polecenia platformy Azure:

• Użyj środowiska powłoki Bash w usłudze Azure Cloud Shell. Aby uzyskać więcej informacji, zobacz Szybki start dotyczący powłoki Bash w usłudze Azure Cloud Shell.

  

• Jeśli wolisz uruchamiać polecenia referencyjne interfejsu wiersza polecenia lokalnie, zainstaluj interfejs wiersza polecenia platformy Azure. Jeśli korzystasz z systemu Windows lub macOS, rozważ uruchomienie interfejsu wiersza polecenia platformy Azure w kontenerze Docker. Aby uzyskać więcej informacji, zobacz Jak uruchomić interfejs wiersza polecenia platformy Azure w kontenerze platformy Docker.

  • Jeśli korzystasz z instalacji lokalnej, zaloguj się do interfejsu wiersza polecenia platformy Azure za pomocą polecenia az login. Aby ukończyć proces uwierzytelniania, wykonaj kroki wyświetlane w terminalu. Aby uzyskać inne opcje logowania, zobacz Logowanie się przy użyciu interfejsu wiersza polecenia platformy Azure.

  • Po wyświetleniu monitu zainstaluj rozszerzenie interfejsu wiersza polecenia platformy Azure podczas pierwszego użycia. Aby uzyskać więcej informacji na temat rozszerzeń, zobacz Korzystanie z rozszerzeń w interfejsie wiersza polecenia platformy Azure.

  • Uruchom polecenie az version, aby znaleźć zainstalowane wersje i biblioteki zależne. Aby uaktualnić do najnowszej wersji, uruchom polecenie az upgrade.

Aby dodać nazwaną wartość, użyj polecenia 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 utworzeniu nazwanej wartości można ją zaktualizować za pomocą polecenia az apim nv update . Aby wyświetlić wszystkie nazwane wartości, uruchom polecenie az apim nv list :

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

Aby wyświetlić szczegóły nazwanej wartości utworzonej na potrzeby tego przykładu , uruchom polecenie 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

W tym przykładzie jest wartość wpisu tajnego. Poprzednie polecenie nie zwraca wartości. Aby wyświetlić wartość, uruchom polecenie 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

Aby usunąć nazwaną wartość, użyj polecenia 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

Używanie nazwanej wartości

W przykładach w tej sekcji użyto nazwanych wartości przedstawionych w poniższej tabeli.

Nazwa/nazwisko	Wartość	Klucz tajny
ContosoHeader	TrackingId	Fałsz
ContosoHeaderValue	••••••••••••••••••••••	Prawda
ExpressionProperty	@(DateTime.Now.ToString())	Fałsz
ContosoHeaderValue2	This is a header value.	Fałsz

Aby użyć nazwanej wartości w zasadach, umieść jej nazwę wyświetlaną w podwójnej parze nawiasów klamrowych, takich jak {{ContosoHeader}}, jak pokazano w poniższym przykładzie:

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

W tym przykładzie ContosoHeader jest używana jako nazwa nagłówka w set-header zasadach i ContosoHeaderValue jest używana jako wartość tego nagłówka. Gdy te zasady są oceniane podczas żądania lub odpowiedzi na bramę usługi API Management i {{ContosoHeader}} {{ContosoHeaderValue}} są zastępowane odpowiednimi wartościami.

Nazwane wartości mogą być używane jako pełne wartości atrybutu lub elementu, jak pokazano w poprzednim przykładzie, ale można je również wstawić do lub połączyć z częścią wyrażenia tekstowego literału, jak pokazano w poniższym przykładzie:

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

Nazwane wartości mogą również zawierać wyrażenia zasad. W poniższym przykładzie ExpressionProperty jest używane wyrażenie.

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

Gdy te zasady zostaną ocenione, {{ExpressionProperty}} zostanie zastąpiona wartością @(DateTime.Now.ToString()). Ponieważ wartość jest wyrażeniem zasad, wyrażenie jest oceniane, a zasady są wykonywane zgodnie z jego wykonaniem.

Można to przetestować w witrynie Azure Portal lub portalu dla deweloperów, wywołując operację, która zawiera zasady z nazwanymi wartościami w zakresie. W poniższym przykładzie operacja jest wywoływana przy użyciu dwóch poprzednich przykładowych set-header zasad z nazwanymi wartościami. Zwróć uwagę, że odpowiedź zawiera dwa nagłówki niestandardowe, które zostały skonfigurowane przy użyciu zasad z nazwanymi wartościami.

Jeśli przyjrzysz się śladowi interfejsu API ruchu wychodzącego dla wywołania zawierającego dwa poprzednie przykładowe zasady z nazwanymi wartościami, zobaczysz dwie set-header zasady z wstawionymi nazwanymi wartościami, a także ocenę wyrażenia zasad dla nazwanej wartości, która zawierała wyrażenie zasad.

Interpolacja ciągów może być również używana z nazwanymi wartościami.

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

Wartość parametru CustomHeader będzie mieć wartość The URL encoded value is This+is+a+header+value..

Uwaga

Jeśli zasady odwołują się do wpisu tajnego w usłudze Azure Key Vault, wartość z magazynu kluczy będzie widoczna dla użytkowników, którzy mają dostęp do subskrypcji z włączoną obsługą śledzenia żądań interfejsu API.

Chociaż nazwane wartości mogą zawierać wyrażenia zasad, nie mogą zawierać innych nazwanych wartości. Jeśli tekst zawierający odwołanie do nazwanej wartości jest używany dla wartości, takiej jak Text: {{MyProperty}}, odwołanie nie zostanie rozpoznane i zamienione.

Usuwanie nazwanej wartości

Aby usunąć nazwaną wartość, wybierz nazwę, a następnie wybierz pozycję Usuń z menu kontekstowego (...).

Ważne

Jeśli nazwana wartość jest przywoływała dowolne zasady usługi API Management, nie można jej usunąć, dopóki nie usuniesz nazwanej wartości ze wszystkich zasad, które go używają.

Następne kroki

• Dowiedz się więcej o pracy z zasadami
  • Zasady w usłudze API Management
  • Dokumentacja zasad
  • Wyrażenia zasad