Udostępnij za pośrednictwem

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. Nazwane wartości mogą być używane do zarządzania stałymi wartościami ciągów i tajemnicami we wszystkich konfiguracjach i zasadach Interfejsu API.

Nazwane wartości w portalu Azure

Typy wartości

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

Zaleca się korzystanie z sekretów skarbca kluczy, ponieważ pomaga to zwiększyć bezpieczeństwo usługi zarządzania API.

  • Wpisy tajne przechowywane w magazynach kluczy mogą być ponownie używane w usługach
  • Granularne zasady dostępu można stosować do tajemnic
  • Tajne informacje zaktualizowane w magazynie kluczy są automatycznie aktualizowane w 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ć 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

Wymagania wstępne dotyczące integracji z sejfem kluczy

Uwaga

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

Konfigurowanie dostępu do magazynu kluczy

  1. W portalu przejdź do skrytki kluczy.
  2. W menu po lewej stronie wybierz pozycję 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 Podmiot wybierz pozycję Podmiot, wyszukaj nazwę zasobu tożsamości zarządzanej, a następnie wybierz 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 tajemnic Key Vault.
  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.

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

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

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:

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

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

  7. Dodaj jeden lub więcej opcjonalnych tagów, aby ułatwić organizowanie nazwanych wartości, a następnie Zapisz.

  8. Wybierz pozycję Utwórz.

    Dodawanie wartości wpisu tajnego magazynu kluczy

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

  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. W polu Typ wartości 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.

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.

Wartości nazwane 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ć lub połączyć z częścią dosłownego wyrażenia tekstowego, 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 ta polityka jest oceniana, {{ExpressionProperty}} jest zastępowana wartością @(DateTime.Now.ToString()). Ponieważ wartość jest wyrażeniem polityki, to 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.

Testowa odpowiedź interfejsu API

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.

Ślad inspektora API

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 tajemnicy 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łączonym śledzeniem żądań 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ść