MonetizationLimitsCheck-Richtlinie

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Richtliniensymbol

Übersicht

Mit der Richtlinie "MonetizationLimitsCheck" können Sie die Monetarisierungslimits erzwingen.

Insbesondere wird die Richtlinie ausgelöst, wenn der App-Entwickler, der auf die monetarisierte API zugreift, kein Abo für das zugehörige API-Produkt erworben hat oder wenn der Entwickler über kein ausreichendes Guthaben verfügt. In diesem Fall löst die Richtlinie "MonetizationLimitsCheck" einen Fehler aus und blockiert den API-Aufruf. Weitere Informationen finden Sie unter Entwicklerabos für API-Produkte durchsetzen.

Wenn Sie die Richtlinie "MonetizationLimitsCheck" an einen API-Proxy anhängen, werden die Ablaufvariablen mint.limitscheck.* und mint.subscription_* ausgefüllt, wie in der Referenz zu mint-Ablaufvariablen beschrieben.

Diese Richtlinie ist eine erweiterbare Richtlinie, deren Verwendung je nach Apigee-Lizenz Auswirkungen auf die Kosten oder die Nutzung haben kann. Informationen zu Richtlinientypen und Auswirkungen auf die Nutzung finden Sie unter Richtlinientypen.

<MonetizationLimitsCheck>

Definiert die MonetizationLimitsCheck-Richtlinie.

Standardwert
Erforderlich? Erforderlich
Typ Komplexer Typ
Übergeordnetes Element
Untergeordnete Elemente <DisplayName>
<FaultResponse>
<IgnoreUnresolvedVariables>

Die folgende Tabelle enthält eine allgemeine Beschreibung der untergeordneten Elemente von <MonetizationLimitsCheck>:

Untergeordnetes Element Erforderlich? Beschreibung
<DisplayName> Optional Ein benutzerdefinierter Name für die Richtlinie.
<FaultResponse> Optional Definiert die Antwortnachricht, die an den anfordernden Client zurückgegeben wird.
<IgnoreUnresolvedVariables> Optional Ignorieren Sie eventuelle nicht behobene Variablenfehler im Ablauf.

Das <MonetizationLimitsCheck>-Element verwendet die folgende Syntax:

Syntax

<?xml version="1.0" encoding="UTF-8" standalone="no"?><MonetizationLimitsCheck continueOnError="[true|false]" enabled="[true|false]" name="policy_name">
   <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
   <FaultResponse>
        <AssignVariable>
          <Name/>
          <Value/>
        </AssignVariable>
        <Add>
            <Headers/>
        </Add>
        <Copy source="request">
            <Headers/>
            <StatusCode/>
       </Copy>
        <Remove>
            <Headers/>
        </Remove>
        <Set>
            <Headers/>
            <Payload/>
            <StatusCode/>
        </Set>
    </FaultResponse>
    <IgnoreUnresolvedVariables>VALUE</IgnoreUnresolvedVariables>
</MonetizationLimitsCheck>

Beispiel

Im folgenden Beispiel wird, wenn ein Entwickler kein Abo für das zugehörige API-Produkt erworben hat, der Zugriff auf die monetarisierte API gesperrt und ein 403-Status mit einer benutzerdefinierten Meldung zurückgegeben.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MonetizationLimitsCheck continueOnError="false" enabled="true" name="MonetizationLimitsCheck-1">
  <DisplayName>Monetization-Limits-Check-1</DisplayName>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <FaultResponse>
    <Set>
      <Payload contentType="text/xml">
        <error>
          <messages>
            <message>Usage has been exceeded ({mint.limitscheck.isRequestBlocked}) or app developer has been suspended</message>
          </messages>
        </error>
      </Payload>
      <StatusCode>403</StatusCode>
    </Set>
  </FaultResponse>
</MonetizationLimitsCheck>

Dieses Element hat folgende Attribute, die allen Richtlinien gemeinsam sind:

Attribut Standard Erforderlich? Beschreibung
name - Erforderlich

Der interne Name der Richtlinie. Der Wert des Attributs name kann Buchstaben, Ziffern, Leerzeichen, Bindestriche, Unterstriche und Punkte enthalten. Dieser Wert darf 255 Zeichen nicht überschreiten.

Optional können Sie das Element <DisplayName> verwenden, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen Namen in einer natürlichen Sprache zu versehen.

continueOnError false Optional Legen Sie false fest, um einen Fehler zurückzugeben, wenn eine Richtlinie fehlschlägt. Dies ist für die meisten Richtlinien das erwartete Verhalten. Legen Sie true fest, damit die Ablaufausführung auch nach dem Fehlschlagen einer Richtlinie fortgesetzt wird. Weitere Informationen:
enabled wahr Optional Setzen Sie den Wert auf true, um die Richtlinie zu erzwingen. Legen Sie false fest, um die Richtlinie zu deaktivieren. Die Richtlinie wird nicht durchgesetzt, selbst wenn sie mit einem Ablauf verknüpft ist.
async   false Verworfen Dieses Attribut wurde verworfen.

Verweis auf untergeordnetes Element

In diesem Abschnitt werden die untergeordneten Elemente von <MonetizationLimitsCheck> beschrieben.

<DisplayName>

Wird zusätzlich zum Attribut name verwendet, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen, natürlicher klingenden Namen zu versehen.

Das Element <DisplayName> ist für alle Richtlinien gleich.

Standardwert
Erforderlich? Optional. Wenn Sie <DisplayName> weglassen, wird der Wert des Attributs name der Richtlinie verwendet.
Typ String
Übergeordnetes Element <PolicyElement>
Untergeordnete Elemente Keine

Das <DisplayName>-Element verwendet die folgende Syntax:

Syntax

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

Beispiel

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

Das <DisplayName>-Element hat keine Attribute oder untergeordneten Elemente.

<FaultResponse>

Definiert die Antwortnachricht, die an den anfordernden Client zurückgegeben wird. FaultResponse verwendet in der RaiseFault-Richtlinie dieselben Einstellungen wie das <FaultResponse>-Element.

Standardwert
Erforderlich? Optional
Typ Komplexer Typ
Übergeordnetes Element <MonetizationLimitsCheck>
Untergeordnete Elemente <AssignVariable>
<Add>
<Copy>
<Remove>
<Set>

<AssignVariable>

Weist einer Zielablaufvariable einen Wert zu. Wenn die Ablaufvariable nicht vorhanden ist, wird sie von AssignVariable erstellt.

Standardwert
Erforderlich? Optional
Typ Komplexer Typ
Übergeordnetes Element <FaultResponse>
Untergeordnete Elemente <Name>
<Value>

Verwenden Sie beispielsweise den folgenden Code, um die Variable mit dem Namen myFaultVar in der Richtlinie "MonetizationLimitsCheck" festzulegen:

<FaultResponse>
<AssignVariable>
  <Name>myFaultVar</Name>
  <Value>42</Value>
</AssignVariable>
</FaultResponse>

Eine Richtlinie in einer Fehlerregel kann dann auf die Variable zugreifen. Die folgende AssignMessage-Richtlinie verwendet die Variable zum Festlegen eines Headers in der Fehlerantwort:

<AssignMessage enabled="true" name="Assign-Message-1">
<Add>
  <Headers>
    <Header name="newvar">{myFaultVar}</Header>
  </Headers>
</Add>
<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
<AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

<AssignVariable> in der Richtlinie MonetizationLimitsCheck verwendet die gleiche Syntax wie das Element <AssignVariable> in der AssignMessage-Richtlinie.

<Name>

Variablenname. Weitere Informationen finden Sie unter Name in der Richtlinie „AssignMessage“.

Standardwert
Erforderlich? Optional
Typ String
Übergeordnetes Element <AssignVariable>
Untergeordnete Elemente Keine
<Value>

Variablenwert. Weitere Informationen finden Sie unter Wert in der Richtlinie „AssignMessage“.

Standardwert
Erforderlich? Optional
Typ String
Übergeordnetes Element <AssignVariable>
Untergeordnete Elemente Keine

<Add>

Fügt HTTP-Header zur Fehlermeldung hinzu.

Standardwert
Erforderlich? Optional
Typ Komplexer Typ
Übergeordnetes Element <FaultResponse>
Untergeordnete Elemente <Headers>
<Headers>

Gibt den HTTP-Header an, der hinzugefügt, festgelegt, kopiert oder entfernt werden soll.

Standardwert
Erforderlich? Optional
Typ Komplexer Typ
Übergeordnetes Element <Add>
<Copy>
<Remove>
<Set>
Untergeordnete Elemente Keine

Beispiele:

Header hinzufügen

Im folgenden Beispiel wird der Wert der Ablaufvariablen request.user.agent in den Header kopiert:

<Add>
    <Headers>
        <Header name="user-agent">{request.user.agent}</Header>
    </Headers>
</Add>
Header festlegen

Im folgenden Beispiel wird der user-agent-Header auf die Nachrichtenvariable gesetzt, die mit dem <AssignTo>-Element angegeben wird.

<Set>
    <Headers>
        <Header name="user-agent">{request.header.user-agent}</Header>
    </Headers>
</Set>
Header kopieren – 1

Im folgenden Beispiel wird headerA aus der Anfrage kopiert:

<Copy source='request'>
    <Headers>
        <Header name="headerA"/>
    </Headers>
</Copy>
Header kopieren – 1

Im folgenden Beispiel werden mehrere Header kopiert:

<Copy source='request'>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
</Copy>

In diesem Beispiel werden "h1", "h2" und der zweite Wert von "h3" kopiert. Wenn „h3“ nur einen Wert hat, wird „h3“ nicht kopiert.

Header entfernen – 1

Im folgenden Beispiel wird ein Header entfernt:

<Remove>
    <Headers>
        <Header name="user-agent"/>
    </Headers>
</Remove>
Header entfernen – 2

Im folgenden Beispiel werden mehrere Header entfernt:

<Remove>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
</Remove>

In diesem Beispiel werden "h1", "h2" und der zweite Wert von "h3" entfernt. Wenn „h3“ nur einen Wert hat, wird „h3“ nicht entfernt.

<Copy>

Kopiert Informationen von der durch das Attribut source angegebenen Nachricht an die Fehlermeldung.

Standardwert
Erforderlich? Optional
Typ Komplexer Typ
Übergeordnetes Element <FaultResponse>
Untergeordnete Elemente <Headers>
<StatusCode>

In der folgenden Tabelle werden die Attribute von <Copy> beschrieben:

Attribut Erforderlich? Typ Beschreibung
Quelle Optional String

Gibt das Quellobjekt der Kopie an.

  • Wenn source nicht angegeben wird, wird sie als einfache Nachricht behandelt. Befindet sich die Richtlinie beispielsweise im Anfrageablauf, verwendet die Quelle standardmäßig das Objekt request. Wenn sich die Richtlinie im Antwortablauf befindet, wird standardmäßig das Objekt response verwendet. Wenn Sie source weglassen, können Sie eine absolute Referenz auf eine Ablaufvariable als Quelle der Kopie verwenden. Geben Sie beispielsweise den Wert als {request.header.user-agent} an.
  • Wenn die Quellvariable nicht aufgelöst werden kann oder in einen nicht-Nachrichtentyp aufgelöst wird, reagiert <Copy> nicht.
<StatusCode>

Gibt den HTTP-Statuscode in der Fehlermeldung an. Sie können den Wert für das im Attribut source angegebene Objekt kopieren oder festlegen.

Standardwert
Erforderlich? Optional
Typ Komplexer Typ
Übergeordnetes Element <Copy>
<Set>
Untergeordnete Elemente Keine

Beispiel:

Statuscode kopieren
<Copy source='response'>
    <StatusCode>404</StatusCode>
</Copy>
Statuscode festlegen
<Set source='request'>
    <StatusCode>404</StatusCode>
</Set>

<Remove>

Entfernt angegebene HTTP-Header aus der Fehlermeldung. Wenn Sie alle Header entfernen möchten, geben Sie <Remove><Headers/></Remove> an.

Standardwert
Erforderlich? Optional
Typ Komplexer Typ
Übergeordnetes Element <FaultResponse>
Untergeordnete Elemente <Headers>

<Set>

Legt Informationen in der Fehlermeldung fest.

Standardwert
Erforderlich? Optional
Typ Komplexer Typ
Übergeordnetes Element <FaultResponse>
Untergeordnete Elemente <Headers>
<Payload>
<StatusCode>
<Payload>

Legt die Nutzlast der Fehlermeldung fest.

Standardwert
Erforderlich? Optional
Typ String
Übergeordnetes Element <Set>
Untergeordnete Elemente Keine

Beispiele:

Textnutzlast festlegen
<Set>
    <Payload contentType="text/plain">test1234</Payload>
</Set>
JSON-Nutzlast festlegen – 1
<Set>
    <Payload contentType="application/json">
        {"name":"foo", "type":"bar"}
    </Payload>
</Set>
JSON-Nutzlast festlegen – 2
<Set>
    <Payload contentType="application/json" variablePrefix="@" variableSuffix="#">
        {"name":"foo", "type":"@variable_name#"}
    </Payload>
</Set>

In diesem Beispiel werden Variablen mithilfe der Attribute variablePrefix und variableSuffix mit Trennzeichen eingefügt.

JSON-Nutzlast festlegen – 3
<Set>
    <Payload contentType="application/json">
        {"name":"foo", "type":"{variable_name}"}
    </Payload>
</Set>

In diesem Beispiel werden Variablen mit geschweiften Klammern eingefügt. Sie können geschweifte Klammern ab Version 16.08.17 verwenden.

XML-Nutzlast festlegen
<Set>
    <Payload contentType="text/xml">
        <root>
          <e1>sunday</e1>
          <e2>funday</e2>
          <e3>{var1}</e3>
    </Payload>
</Set>

In diesem Beispiel werden Variablen mit geschweiften Klammern eingefügt. Sie können geschweifte Klammern ab Version 16.08.17 verwenden.

<IgnoreUnresolvedVariables>

Bestimmt, ob die Verarbeitung beendet wird, wenn eine nicht aufgelöste Variable erkannt wird.

Auf true festlegen, um nicht aufgelöste Variablen zu ignorieren und die Verarbeitung fortzusetzen. Andernfalls false. Der Standardwert ist true.

Das Festlegen von true für <IgnoreUnresolvedVariables> unterscheidet sich vom Festlegen von continueOnError auf true für <MonetizationLimitsCheck>. Wenn Sie true für continueOnError angeben, ignoriert Apigee alle Fehler, also nicht nur Fehler in Variablen.

Das <IgnoreUnresolvedVariables>-Element verwendet die folgende Syntax:

Syntax

<IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables>

Beispiel

Im folgenden Beispiel wird für <IgnoreUnresolvedVariables> der Wert false festgelegt:

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

Fehlercodes

In diesem Abschnitt werden die zurückgegebenen Fehlercodes und Fehlermeldungen beschrieben, die von Apigee festgelegt werden, wenn die Richtlinie einen Fehler auslöst. Diese Informationen sind wichtig, wenn Sie Fehlerregeln zur Verarbeitung von Fehlern entwickeln. Weitere Informationen finden Sie unter Was Sie über Richtlinienfehler wissen müssen und Fehler beheben.

Laufzeitfehler

Diese Fehler können bei Ausführung der Richtlinie auftreten.

Fehlercode HTTP-Status Ursache
mint.service.subscription_not_found_for_developer 500 Dieser Fehler tritt auf, wenn ein Entwickler kein Abo für das API-Produkt hat.
mint.service.wallet_not_found_for_developer 500 Dieser Fehler tritt auf, wenn ein Prepaid-Entwickler versucht, eine monetarisierte API zu nutzen, ohne ein Wallet für die im Tarif enthaltene Währung zu verwalten.
mint.service.developer_usage_exceeds_balance 500 Dieser Fehler tritt auf, wenn die Nutzung eines Prepaid-Entwicklers das Guthaben einer Wallet überschreitet.
mint.service.wallet_blocked_due_to_inactivity 500 Dieser Fehler tritt auf, wenn die Wallet eines Prepaid-Entwicklers seit über 1,5 Jahren nicht mehr aufgeladen wurde und der Entwickler versucht, eine API zu nutzen.

Fehlervariablen

Wenn in einer Richtlinie Ausführungsfehler auftreten, generiert Apigee Fehlermeldungen. Sie können sich diese Fehlermeldungen in der Fehlerantwort ansehen. Häufig sind vom System generierte Fehlermeldungen im Kontext Ihres Produkts möglicherweise nicht relevant. Sie können die Fehlermeldungen basierend auf dem Fehlertyp anpassen, um die Nachrichten aussagekräftiger zu machen.

Zum Anpassen der Fehlermeldungen können Sie entweder Fehlerregeln oder die RaiseFault-Richtlinie verwenden. Informationen zu Unterschieden zwischen Fehlerregeln und der RaiseFault-Richtlinie finden Sie unter FaultRules-Richtlinie im Vergleich zur RaiseFault-Richtlinie. Prüfen Sie, ob Bedingungen mit dem Element Condition in den Fehlerregeln und in der RaiseFault-Richtlinie verwendet werden. Apigee stellt Fehlervariablen bereit, die für jede Richtlinie eindeutig sind. Die Werte der Fehlervariablen werden festgelegt, wenn eine Richtlinie Laufzeitfehler auslöst. Mit diesen Variablen können Sie nach bestimmten Fehlerbedingungen suchen und entsprechende Maßnahmen ergreifen. Weitere Informationen zum Prüfen von Fehlerbedingungen finden Sie unter Bedingungen erstellen.

Variablen Wo Beispiel
fault.name Der fault.name kann mit einem der Fehler übereinstimmen, die in der Tabelle Laufzeitfehler aufgeführt sind. Der Fehlername ist der letzte Teil des Fehlercodes. fault.name Matches "UnresolvedVariable"
MonetizationLimitsCheck.POLICY_NAME.failed POLICY_NAME ist der benutzerdefinierte Name der Richtlinie, die den Fehler ausgelöst hat. MonetizationLimitsCheck.monetization-limits-check-1.failed = true
Weitere Informationen zu Richtlinienfehlern finden Sie unter Was Sie über Richtlinienfehler wissen müssen.

Ablaufvariablen

Die folgenden vordefinierten Flussvariablen beim Ausführen der Richtlinie „MonetizationLimitsCheck“ automatisch ausgefüllt. Weitere Informationen finden Sie unter mint-Ablaufvariablen.

Ablaufvariable Beschreibung
mint.limitscheck.is_request_blocked true für blockierte Anfragen.
mint.limitscheck.is_subscription_found true, wenn ein API-Abo gefunden wird
mint.limitscheck.purchased_product_name Name des erworbenen API-Produkts. Beispiel: MyProduct.
mint.limitscheck.status_message Statusmeldung. Beispiel: limits_check_success.
mint.subscription_end_time_ms Ende des API-Produktabos
mint.subscription_start_time_ms Beginn des API-Produktabos Beispiel: 1618433956209.