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 dosłownych wartości tekstowych, 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. Za pomocą nazwanych wartości można zarządzać stałymi wartościami ciągów oraz tajemnicami we wszystkich konfiguracjach i zasadach interfejsu API.

Typy wartości

Typ	Opis
Równina	Ciąg literału lub wyrażenie zasad
Klucz tajny	Ciąg znaków lub wyrażenie zasad, które są szyfrowane przez usługę zarządzania API
Magazyn kluczy	Identyfikator tajemnicy przechowywanej w Azure Key Vault.

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 atrybutach nazwanej wartości, sprawdź dokumentację interfejsu API REST usługi API Management.

Sekrety 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.

Zalecamy używanie tajemnic magazynu kluczy, ponieważ pomagają one zwiększyć bezpieczeństwo zarządzania API.

Uwaga

Obecnie integracja z magazynem kluczy dla tego scenariusza nie jest dostępna w obszarach roboczych.

• Możesz ponownie używać sekretów przechowywanych w magazynach kluczy w różnych usługach.
• Można zastosować szczegółowe zasady dostępu do tajnych danych.
• Tajne informacje zaktualizowane w magazynie kluczy są automatycznie aktualizowane w API Management. Po zaktualizowaniu magazynu kluczy nazwana wartość w Zarządzaniu API zostaje zaktualizowana w ciągu czterech godzin. Możesz również ręcznie odświeżyć tajne dane za pomocą portalu Azure 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 Szybki start: tworzenie nowego wystąpienia usługi Azure API Management przy użyciu witryny Azure Portal.

Wymagania wstępne dotyczące integracji z sejfem 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 przypisaną przez system lub użytkownika tożsamość zarządzaną w wystąpieniu usługi API Management.

Konfigurowanie dostępu do magazynu kluczy

1. W portalu przejdź do skrytki kluczy.
2. W menu po lewej stronie wybierz pozycję Ustawienia>Konfiguracja dostępu. Zwróć uwagę na skonfigurowany model uprawnień .
3. W zależności od modelu uprawnień skonfiguruj albo politykę dostępu do magazynu kluczy, albo dostęp platformy Azure RBAC dla zarządzanej tożsamości w usłudze 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 wyświetl, a następnie wybierz pozycję Dalej.
4. Na karcie Główne 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 to nazwa wystąpienia 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 (IAM) wybierz pozycję Dodaj przypisanie roli.
3. Na karcie Rola wybierz pozycję Użytkownik wpisów tajnych usługi Key Vault, a następnie wybierz pozycję Dalej.
4. Na karcie Członkowie wybierz Tożsamość zarządzana>+ Wybierz członków.
5. Na stronie Wybierz tożsamość zarządzaną wybierz tożsamość zarządzaną przypisaną przez system lub przypisaną przez użytkownika, która jest skojarzona z Twoim 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, musisz spełnić następujące wymagania:

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

• Upewnij się, że instancja API Management ma dostęp sieciowy do magazynu kluczy. W zależności od scenariuszy skonfiguruj jedną z następujących opcji dostępu do sieci w magazynie kluczy:

  • Zezwalaj na dostęp publiczny ze wszystkich sieci.

  • Ustaw regułę zabezpieczeń sieci, aby zezwolić na ruch usługi API Management na podstawie adresu IP lub łączności z siecią wirtualną.

  • Zabezpieczanie ruchu z usługi API Management za pomocą łączności usługi Private Link.

  • Użyj obwodu zabezpieczeń sieci , aby zabezpieczyć magazyn kluczy i zezwolić na ruch z usługi API Management.

• Upewnij się, że twój lokalny adres IP klienta może tymczasowo uzyskać dostęp do sejfu kluczy, podczas wybierania certyfikatu lub tajemnicy, które mają zostać dodane do usługi zarządzania API Azure. 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.

Ważne

Od marca 2026 r. obsługa zaufanego połączenia z usługą Azure Key Vault z usługi API Management dzięki włączeniu ustawienia Zezwalaj zaufanym usługom Microsoft na obejście tej zapory w zaporze magazynu kluczy nie będzie już wspierana. Aby kontynuować korzystanie z usługi Key Vault z usługą API Management po tej zmianie, upewnij się, że wybrano obsługiwaną opcję dostępu do sieci zgodnie z powyższym opisem. Dowiedz się więcej.

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 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 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 tajemnicy do magazynu kluczy w wystąpieniu usługi API Management, musisz mieć uprawnienia do przeglądania tajemnic w magazynie kluczy.

Uwaga

Podczas korzystania z tajemnicy magazynu kluczy w usłudze API Management, należy uważać, aby nie usuwać tajemnicy, magazynu kluczy ani tożsamości zarządzanej używanej do dostępu do magazynu kluczy.

1. W portalu Azure przejdź do instancji usługi API Management.

2. W sekcji Interfejsy API wybierz opcję Nazwane wartości>+ Dodaj.

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

4. Dodaj co najmniej jeden opcjonalny tag , aby ułatwić organizowanie nazwanych wartości.

5. W polu rozwijanym Typ wybierz Magazyn kluczy.

6. 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 tajny identyfikator w magazynie kluczy, upewnij się, że nie zawiera danych o wersji. W przeciwnym razie tajemnica nie będzie automatycznie rotować w usłudze zarządzania API po aktualizacji w magazynie kluczy.

7. 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 uzyskiwania dostępu i wyświetlania tajemnic 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ń.

8. Wybierz pozycję Zapisz, a następnie wybierz pozycję Utwórz.

   

Dodaj zwykłą lub tajną wartość do zarządzania interfejsem API

Portal

1. W portalu Azure przejdź do instancji usługi API Management.
2. W obszarze Interfejsy API wybierz pozycję Nazwane wartości>+Dodaj.
3. Wprowadź identyfikator nazwy, a następnie wprowadź nazwę wyświetlaną używaną do odwoływania się do właściwości w zasadach.
4. Z listy rozwijanej Typ wybierz pozycję Zwykły lub Tajny.
5. W polu Wartość wprowadź ciąg lub wyrażenie zasad.
6. Dodaj jeden lub więcej opcjonalnych tagów, aby ułatwić organizowanie nazwanych wartości, a następnie 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 Get started with 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 Uwierzytelnianie na platformie Azure 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 Używanie rozszerzeń i zarządzanie nimi za pomocą interfejsu 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 . Zastąp nazwę grupy zasobów i nazwę wystąpienia usługi API Management w wartości resource-group i service-name.

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 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 polityce, umieść jej wyświetlaną nazwę 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 zasady te są oceniane podczas żądania lub odpowiedzi na bramę usługi API Management, {{ContosoHeader}} oraz {{ContosoHeaderValue}} są zastępowane odpowiednimi wartościami.

Można użyć nazwanych wartości jako pełnych wartości atrybutu bądź elementu, jak pokazano w poprzednim przykładzie, ale można je również wstawić albo połączyć z częścią wyrażenia tekstowego literału, co ilustruje poniższy przykład:

<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 ta polityka jest oceniana, {{ExpressionProperty}} jest zastępowana wartością @(DateTime.Now.ToString()). Ponieważ wartość jest wyrażeniem polityki, wyrażenie jest oceniane, a polityka kontynuuje swoją realizację.

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 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 ewaluację wyrażenia zasad dla nazwanej wartości, która zawierała wyrażenie zasad.

Można również użyć interpolacji ciągów 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 sekretu w usłudze Azure Key Vault, wartość magazynu kluczy jest widoczna dla użytkowników, którzy mają dostęp do subskrypcji, w których włączono śledzenie żą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ływana przez jakiekolwiek zasady w usłudze API Management, nie możesz jej usunąć, dopóki nie usuniesz tej nazwanej wartości ze wszystkich zasad, które jej używają.

Powiązana zawartość

Dowiedz się więcej o pracy z zasadami:

• Zasady w usłudze API Management
• Odniesienie do polityki
• Wyrażenia zasad