Zasady w usłudze Azure API Management

  • Artykuł

DOTYCZY: Wszystkie warstwy usługi API Management

W usłudze Azure API Management wydawcy interfejsu API mogą zmieniać zachowanie interfejsu API za pomocą konfiguracji przy użyciu zasad. Zasady to zbiór instrukcji, które są uruchamiane sekwencyjnie na żądanie lub odpowiedź interfejsu API. Usługa API Management udostępnia ponad 50 zasad, które można skonfigurować w celu obsługi typowych scenariuszy interfejsu API, takich jak uwierzytelnianie, ograniczanie szybkości, buforowanie i przekształcanie żądań lub odpowiedzi. Aby uzyskać pełną listę, zobacz dokumentację zasad API Management.

Popularne zasady obejmują:

  • Konwertowanie formatu z formatu XML na JSON
  • Ograniczanie szybkości wywołań w celu ograniczenia liczby połączeń przychodzących od dewelopera
  • Filtrowanie żądań pochodzących z określonych adresów IP

Zasady są stosowane wewnątrz bramy między odbiorcą interfejsu API a zarządzanym interfejsem API. Podczas gdy brama odbiera żądania i przekazuje je, bez zmian, do bazowego interfejsu API, zasady mogą stosować zmiany zarówno do żądania przychodzącego, jak i odpowiedzi wychodzącej.

Informacje o konfiguracji zasad

Definicje zasad to proste dokumenty XML, które opisują sekwencję instrukcji do zastosowania do żądań i odpowiedzi. Aby ułatwić konfigurowanie definicji zasad, portal udostępnia następujące opcje:

  • Edytor oparty na formularzach upraszczający konfigurowanie popularnych zasad bez kodowania KODU XML
  • Edytor kodu, w którym można wstawić fragmenty kodu XML lub edytować kod XML bezpośrednio

Aby uzyskać więcej informacji na temat konfigurowania zasad, zobacz Ustawianie lub edytowanie zasad.

Konfiguracja xml zasad jest podzielona na inboundsekcje , backend, outboundi on-error . Ta seria określonych instrukcji zasad jest wykonywana w celu żądania i odpowiedzi.

<policies>
  <inbound>
    <!-- statements to be applied to the request go here -->
  </inbound>
  <backend>
    <!-- statements to be applied before the request is forwarded to 
         the backend service go here -->
  </backend>
  <outbound>
    <!-- statements to be applied to the response go here -->
  </outbound>
  <on-error>
    <!-- statements to be applied if there is an error condition go here -->
  </on-error>
</policies>

Aby zapoznać się z przykładami xml zasad, zobacz repozytorium fragmentów zasad usługi API Management.

Obsługa błędów

Jeśli podczas przetwarzania żądania wystąpi błąd:

  • Wszystkie pozostałe kroki w inboundsekcjach , backendlub outbound są pomijane.
  • Wykonanie przechodzi do instrukcji w on-error sekcji .

Umieszczając instrukcje zasad w on-error sekcji, można wykonywać następujące czynności:

  • Przejrzyj błąd przy użyciu context.LastError właściwości .
  • Sprawdź i dostosuj odpowiedź na błędy przy użyciu set-body zasad.
  • Skonfiguruj, co się stanie w przypadku wystąpienia błędu.

Aby uzyskać więcej informacji, zobacz Obsługa błędów w zasadach usługi API Management.

Wyrażenia zasad

Jeśli zasady nie określają inaczej, wyrażenia zasad mogą być używane jako wartości atrybutów lub wartości tekstowe w dowolnej z zasad usługi API Management. Wyrażenie zasad to:

  • pojedyncza instrukcja języka C# ujęta w , @(expression)lub
  • blok kodu języka C# z wieloma instrukcjami , który @{expression}zwraca wartość

Każde wyrażenie ma dostęp do niejawnie podanej context zmiennej i dozwolonego podzestawu typów programu .NET Framework.

Wyrażenia zasad zapewniają zaawansowane metody kontrolowania ruchu i modyfikowania zachowania interfejsu API bez konieczności pisania wyspecjalizowanego kodu lub modyfikowania usług zaplecza. Niektóre zasady są oparte na wyrażeniach zasad, takich jak Przepływ sterowania i Ustaw zmienną.

Zakresy

Usługa API Management umożliwia definiowanie zasad w następujących zakresach— od najbardziej szerokiego do najbardziej wąskiego:

  • Globalny (wszystkie interfejsy API)
  • Obszar roboczy (wszystkie interfejsy API skojarzone z wybranym obszarem roboczym)
  • Product (wszystkie interfejsy API skojarzone z wybranym produktem)
  • Interfejs API (wszystkie operacje w interfejsie API)
  • Operacja (pojedyncza operacja w interfejsie API)

Podczas konfigurowania zasad należy najpierw wybrać zakres, w którym mają zastosowanie zasady.

Zakresy zasad

Fakty, które trzeba znać

  • W przypadku szczegółowej kontroli dla różnych użytkowników interfejsu API można skonfigurować definicje zasad w więcej niż jednym zakresie

  • Nie wszystkie zasady są obsługiwane w poszczególnych sekcjach zakresów i zasad

  • Podczas konfigurowania definicji zasad w więcej niż jednym zakresie można kontrolować dziedziczenie zasad i kolejność oceny zasad w każdej sekcji zasad przez umieszczenie base elementu

  • Zasady stosowane do żądań interfejsu API mają również wpływ na kontekst żądania, w tym obecność lub brak klucza subskrypcji używanego w żądaniu, interfejs API lub zakres produktu klucza subskrypcji oraz to, czy interfejs API lub produkt wymaga subskrypcji.

    Uwaga

    Jeśli używasz subskrypcji o zakresie interfejsu API, subskrypcji wszystkich interfejsów API lub wbudowanej subskrypcji z dostępem do wszystkich, zasady skonfigurowane w zakresie produktu nie są stosowane do żądań z tej subskrypcji.

Aby uzyskać więcej informacji, zobacz:

Zasady rozpoznawania języka GraphQL

W usłudze API Management program GraphQL resolver jest konfigurowany przy użyciu zasad o określonym typie operacji i polu w schemacie GraphQL.

  • Obecnie usługa API Management obsługuje programy rozpoznawania języka GraphQL, które określają źródła danych HTTP API, Cosmos DB lub Azure SQL. Na przykład skonfiguruj pojedyncze http-data-source zasady z elementami, aby określić żądanie (i opcjonalnie odpowiedź z) źródła danych HTTP.
  • Nie można uwzględnić zasad rozpoznawania nazw w definicjach zasad w innych zakresach, takich jak interfejs API, produkt lub wszystkie interfejsy API. Nie dziedziczy również zasad skonfigurowanych w innych zakresach.
  • Brama ocenia zasady o zakresie rozpoznawania nazw po skonfigurowaniu zasad inbound i backend zasadach w potoku wykonywania zasad.

Aby uzyskać więcej informacji, zobacz Konfigurowanie programu GraphQL resolver.

Uzyskiwanie pomocy przy tworzeniu zasad przy użyciu rozwiązania Microsoft Copilot dla platformy Azure (wersja zapoznawcza)

Rozwiązanie Microsoft Copilot dla platformy Azure (wersja zapoznawcza) udostępnia funkcje tworzenia zasad dla usługi Azure API Management. Użyj narzędzia Copilot dla platformy Azure w kontekście edytora zasad usługi API Management, aby utworzyć zasady zgodne z określonymi wymaganiami bez znajomości składni lub zostały już skonfigurowane zasady wyjaśnione dla Ciebie.

Możesz wyświetlić monit Copilot dla platformy Azure o wygenerowanie definicji zasad, a następnie skopiować wyniki do edytora zasad i wprowadzić wszelkie niezbędne korekty. Zadawaj pytania, aby uzyskać wgląd w różne opcje, zmodyfikować podane zasady lub wyjaśnić już posiadane zasady. Dowiedz się więcej

Ważne

Rozwiązanie Microsoft Copilot dla platformy Azure (wersja zapoznawcza) wymaga rejestracji i jest obecnie dostępne tylko dla zatwierdzonych klientów korporacyjnych i partnerów. Aby uzyskać więcej informacji, zobacz Ograniczony dostęp do rozwiązania Microsoft Copilot dla platformy Azure (wersja zapoznawcza).

Przykłady

Stosowanie zasad określonych w różnych zakresach

Jeśli masz zasady na poziomie globalnym i zasady skonfigurowane dla interfejsu API, obie zasady można stosować za każdym razem, gdy dany interfejs API jest używany. Usługa API Management umożliwia deterministyczne porządkowanie połączonych instrukcji zasad za pośrednictwem base elementu.

Przykładowa definicja zasad w zakresie interfejsu API:

<policies>
    <inbound>
        <cross-domain />
        <base />
        <find-and-replace from="xyz" to="abc" />
    </inbound>
</policies>

W przykładowej definicji zasad powyżej:

  • Instrukcja cross-domain zostanie wykonana najpierw.
  • Zasady find-and-replace będą wykonywane po wszystkich zasadach w szerszym zakresie.

Uwaga

Jeśli usuniesz element w zakresie interfejsu base API, zostaną zastosowane tylko zasady skonfigurowane w zakresie interfejsu API. Ani produkt, ani globalne zasady zakresu nie zostaną zastosowane.

Modyfikowanie żądań przy użyciu wyrażeń zasad

W poniższym przykładzie użyto wyrażeń zasad i set-header zasad w celu dodania danych użytkownika do żądania przychodzącego. Dodany nagłówek zawiera identyfikator użytkownika skojarzony z kluczem subskrypcji w żądaniu oraz region, w którym brama przetwarza żądanie.

<policies>
    <inbound>
        <base />
        <set-header name="x-request-context-data" exists-action="override">
            <value>@(context.User.Id)</value>
            <value>@(context.Deployment.Region)</value>
      </set-header>
    </inbound>
</policies>

Powiązana zawartość

Aby uzyskać więcej informacji na temat pracy z zasadami, zobacz: