Erkunden von API Management-Richtlinien

Abgeschlossen

In Azure API Management ermöglichen Richtlinien dem Herausgeber, das Verhalten der API per Konfiguration zu ändern. Richtlinien sind eine Sammlung von Anweisungen, die sequenziell bei Anfragen oder Antworten einer API ausgeführt werden.

Richtlinien werden im Gateway, das sich zwischen API-Consumer und der verwalteten API befindet, angewendet. Das Gateway empfängt alle Anfragen und leitet diese normalerweise unverändert an die zugrunde liegende API weiter. Richtlinien können jedoch Änderungen an der eingehenden Anfrage und an der ausgehenden Antwort vornehmen. Richtlinienausdrücke können als Attributwerte oder Textwerte in einer beliebigen API Management-Richtlinie verwendet werden, sofern in der Richtlinie nicht anders angegeben.

Grundlegendes zur Richtlinienkonfiguration

Die Richtliniendefinition ist ein einfaches XML-Dokument, das eine Sequenz eingehender und ausgehender Anweisungen beschreibt. Das XML-Dokument kann direkt im Definitionsfenster bearbeitet werden.

Die Konfiguration ist in inbound, backend, outbound und on-error unterteilt. Die Richtlinienanweisungen werden in der Reihenfolge für Anforderung und Antwort ausgeführt.

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

Wenn bei der Verarbeitung einer Anfrage ein Fehler auftritt, werden alle verbleibenden Schritte in den Abschnitten inbound, backend oder outbound übersprungen, und die Ausführung wird bei den Anweisungen im Abschnitt on-error fortgesetzt. Durch Platzieren von Richtlinienanweisungen im on-error-Abschnitt können Sie den Fehler überprüfen, indem Sie die context.LastError-Eigenschaft verwenden, die Fehlerantwort mit der set-body-Richtlinie untersuchen und anpassen sowie konfigurieren, was geschieht, wenn ein Fehler auftritt.

Richtlinienausdrücke

Sofern in der Richtlinie nicht anders angegeben, können Richtlinienausdrücke als Attribut- oder Textwerte in allen API Management-Richtlinien verwendet werden. Bei einem Richtlinienausdruck ist entweder:

• eine einzelne, in @(expression) eingeschlossene C#-Anweisung oder
• ein in @{expression} eingeschlossener C#-Codeblock mit mehreren Anweisungen, der einen Wert zurückgibt

Jeder Ausdruck hat Zugriff auf die implizit bereitgestellte context-Variable und eine zulässige Teilmenge von .NET Framework-Typen.

Richtlinienausdrücke bieten eine fortgeschrittene Möglichkeit zum Steuern des Datenverkehrs und zum Ändern des API-Verhaltens, ohne dass Sie speziellen Code schreiben oder Back-End-Dienste ändern müssen.

Im folgenden Beispiel werden Richtlinienausdrücke und die Richtlinie „set-header“ (Header festlegen) verwendet, um der eingehenden Anforderung Benutzerdaten hinzuzufügen. Der hinzugefügte Header enthält die dem Abonnementschlüssel in der Anforderung zugehörige Benutzer-ID und die Region des Gateways, das die Anforderung verarbeitet.

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

Anwenden von Richtlinien, die für verschiedene Bereiche angegeben sind

Wenn Sie eine Richtlinie auf der globalen Ebene und eine Richtlinie für eine API konfiguriert haben, dann werden immer beide Richtlinien angewendet, wenn diese API aufgerufen wird. API Management ermöglicht eine deterministische Festlegung der Reihenfolge kombinierter Richtlinienanweisungen über das Basiselement.

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

In der vorherigen Beispielrichtliniendefinition würde die cross-domain-Anweisung zuerst ausgeführt. Die Richtlinie find-and-replace wird nach allen für übergeordnete Bereiche geltenden Richtlinien ausgeführt.

Filtern des Inhalts der Antwort

Die im folgenden Beispiel definierte Richtlinie veranschaulicht, wie Datenelemente aus den Antwortnutzdaten auf Grundlage des Produkts, das der Anforderung zugeordnet ist, gefiltert werden.

Der Codeschnipsel setzt voraus, dass der Antwortinhalt im JSON-Format vorliegt und Eigenschaften auf Stammebene mit den Namen minutely, hourly, daily und flags enthält.

<policies>
  <inbound>
    <base />
  </inbound>
  <backend>
    <base />
  </backend>
  <outbound>
    <base />
    <choose>
      <when condition="@(context.Response.StatusCode == 200 && context.Product.Name.Equals("Starter"))">
        <!-- NOTE that we are not using preserveContent=true when deserializing response body stream into a JSON object since we don't intend to access it again. See details on /azure/api-management/api-management-transformation-policies#SetBody -->
        <set-body>
          @{
            var response = context.Response.Body.As<JObject>();
            foreach (var key in new [] {"minutely", "hourly", "daily", "flags"}) {
            response.Property (key).Remove ();
           }
          return response.ToString();
          }
    </set-body>
      </when>
    </choose>    
  </outbound>
  <on-error>
    <base />
  </on-error>
</policies>