Udostępnij za pośrednictwem

Zasady w usłudze Azure API Management

DOTYCZY: Wszystkich poziomów zarządzania API

W usłudze Azure API Management wydawcy interfejsów API mogą zmieniać zachowanie interfejsu API za pomocą konfiguracji przy użyciu zasad. W tym artykule opisano sposób używania zasad.

Zasady to zbiór instrukcji uruchamianych sekwencyjnie na żądanie lub odpowiedź interfejsu API. Usługa API Management udostępnia ponad 75 zasad, które można skonfigurować tak, aby rozwiązywać typowe scenariusze interfejsu API, takie jak uwierzytelnianie, ograniczanie szybkości, buforowanie i przekształcanie żądań lub odpowiedzi. Aby uzyskać pełną listę, zobacz Dokumentacja zasad usługi API Management.

Popularne zasady obejmują:

  • Formatuj konwersję z 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. Mimo że 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 pisania 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 uruchamiana w celu żądania i odpowiedzi. Oto jak wygląda:

<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's 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:

  • Pozostałe kroki w sekcjach inbound, backend lub outbound są pomijane.
  • Wykonanie przechodzi do instrukcji w on-error sekcji .

Umieszczając oświadczenia dotyczące zasad w sekcji on-error, można:

  • Przejrzyj błąd, stosując właściwość context.LastError.
  • Skontroluj i dostosuj odpowiedź na błędy, używając polityki set-body.
  • 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 polityki

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 jest jednym z następujących elementów:

  • Pojedyncza instrukcja języka C# ujęta w @(expression)
  • Blok kodu w języku C# z wieloma instrukcjami, ujęty w znaczniku @{expression}, który 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, przedstawionych tutaj od najszerszego do najwęższego:

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

Diagram ilustrujący pięć zakresów 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 każdym zakresie i sekcji 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 / Notatka

    Jeśli używasz subskrypcji o zakresie API, subskrypcji obejmującej wszystkie interfejsy API lub wbudowanej subskrypcji z pełnym dostępem, to zasady skonfigurowane na poziomie produktu nie są stosowane do żądań z tej subskrypcji.

Aby uzyskać więcej informacji, zobacz:

Polityki resolverów GraphQL

W usłudze API Management program GraphQL resolver jest skonfigurowany z zasadami 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ą interfejs API HTTP, usługę Azure Cosmos DB lub źródła danych usługi Azure SQL. Na przykład można skonfigurować pojedynczą http-data-source zasadę z elementami, aby określić żądanie do (i opcjonalnie odpowiedź z) źródła danych HTTP.
  • Nie można uwzględnić polityki rozwiązywania w definicjach zasad na innych poziomach, takich jak interfejs API, produkt czy wszystkie interfejsy API. Polityka nie dziedziczy również zasad skonfigurowanych w innych obszarach.
  • Brama ocenia politykę ograniczoną do rozpoznawania po zakończeniu konfiguracji zasad inbound i backend w ramach potoku wykonywania.

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

Uzyskaj pomoc Copilota

Możesz uzyskać pomoc dotyczącą sztucznej inteligencji od Copilot, aby utworzyć i edytować definicje zasad usługi API Management. Za pomocą narzędzia Copilot można tworzyć i aktualizować zasady spełniające określone wymagania bez konieczności znajomości składni XML. Możesz również uzyskać wyjaśnienia istniejących zasad. Rozwiązanie Copilot może pomóc w tłumaczeniu zasad, które mogły zostać skonfigurowane w innych rozwiązaniach do zarządzania interfejsami API.

Przykładowy monit:

Generate a policy that adds an Authorization header to the request with a Bearer token.

Copilot jest obsługiwany przez sztuczną inteligencję, więc możliwe są niespodzianki i błędy. Aby uzyskać więcej informacji, zobacz także Copilot często zadawane pytania dotyczące ogólnego użytkowania.

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 poprzedniej przykładowej definicji zasad:

Uwaga / Notatka

Jeśli usuniesz element base w zakresie interfejsu API, zostaną zastosowane tylko zasady skonfigurowane w tym zakresie. Zasady skonfigurowane w produktach i szerszych zakresach nie będą stosowane.

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 żądań przychodzących. Dodany nagłówek zawiera identyfikator użytkownika powiązany z kluczem subskrypcji w żądaniu oraz region, w którym znajduje się brama przetwarzająca to żą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>

Treści powiązane

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