Richtlinien für die Transaktionsaufzeichnung konfigurieren

Sie sehen sich die Apigee Edge-Dokumentation an.
Sehen Sie sich die Apigee X-Dokumentation an.

Konfiguriere die Transaktionsaufzeichnungsrichtlinien für jedes API-Produkt in deinem API-Produktpaket, wie in den folgenden Abschnitten beschrieben.

Einführung

Mit einer Richtlinie zur Transaktionsaufzeichnung kann die Monetarisierung Transaktionsparameter und benutzerdefinierte Attribute erfassen. Die Monetarisierung benötigt diese Informationen für die Verarbeitung der Monetarisierung, beispielsweise die Anwendung von Preisplänen.

Wenn Sie beispielsweise einen Tarif mit Umsatzbeteiligung einrichten, wird ein Prozentsatz des Umsatzes, der mit jeder Transaktion mit Ihrem monetarisierten API-Produkt erzielt wird, an den Entwickler der App weitergegeben, von der die Anfrage stammt. Die Umsatzbeteiligung basiert auf dem Netto- oder Bruttopreis der Transaktion (Sie geben an, welcher Preis vorliegt), also ein Prozentsatz des Brutto- oder Nettopreises jeder Transaktion, der für die Ermittlung der Umsatzbeteiligung verwendet wird. Deshalb muss die Monetarisierung den Brutto- oder Nettopreis einer Transaktion kennen. Der Brutto- oder Nettopreis ergibt sich aus den Einstellungen, die Sie in der Richtlinie für die Transaktionsaufzeichnung festlegen.

Wenn Sie einen Preislistenplan einrichten, in dem Sie den Entwickler für jede Transaktion in Rechnung stellen, können Sie den Preis für den Tarif auf der Grundlage eines benutzerdefinierten Attributs festlegen, z. B. der Anzahl der in einer Transaktion übertragenen Byte. Bei der Monetarisierung muss angegeben werden, was das benutzerdefinierte Attribut ist und wo es zu finden ist. Sie müssen daher das benutzerdefinierte Attribut in der Richtlinie zur Transaktionsaufzeichnung angeben.

Neben dem Festlegen von Transaktionsattributen in der Richtlinie zur Transaktionsaufzeichnung können Sie auch Erfolgskriterien für die Transaktion angeben, um zu bestimmen, wann eine Transaktion erfolgreich ist (für Abbuchungen). Beispiele für die Festlegung von Erfolgskriterien für Transaktionen finden Sie unter Erfolgskriterien für Transaktionen in einer Transaktionsrichtlinie festlegen. Sie können auch benutzerdefinierte Attribute für ein API-Produkt angeben, auf dem die Gebühren für den Basis-Abo basieren.

Richtlinien für die Transaktionsaufzeichnung konfigurieren

Rufen Sie die Seite „Produktsets“ wie unten beschrieben auf.

Transaktionsattribute konfigurieren

Geben Sie im Abschnitt Transaktionsattribute die Kriterien für eine erfolgreiche Monetarisierungstransaktion an.

1. Geben Sie im Feld Erfolgskriterien für die Transaktion den Ausdruck basierend auf dem Wert des Statusattributs (wie unten beschrieben) an, um festzustellen, wann die Transaktion erfolgreich ist (für Abbuchungen). Transaktionen, die nicht erfolgreich sind, also die Kriterien im Ausdruck nicht erfüllen, werden aufgezeichnet, aber keine Preispläne auf sie angewendet. Beispiel:

   txProviderStatus == 'OK'

2. Das Attribut Status enthält den Wert, der vom Ausdruck im Feld Transaction Success Criteria verwendet wird. Konfigurieren Sie das Attribut Status, indem Sie die folgenden Felder definieren:

   Feld	Beschreibung
   API-Ressource	Die im API-Produkt definierten URI-Muster, die zur Identifizierung monetarisierter Transaktionen verwendet werden.
   Speicherort der Antwort	Speicherort der Antwort, in der das Attribut angegeben ist. Zulässige Werte sind: Flow Variable, Header, JSON Body und XML Body.
   Wert	Wert der Antwort Wenn Sie mehr als einen Wert festlegen möchten, klicken Sie auf + x hinzufügen (z. B. + Ablaufvariable hinzufügen).

3. Wenn Sie optionale Transaktionsattribute konfigurieren möchten, aktivieren Sie die Ein-/Aus-Schaltfläche Optionale Attribute verwenden und konfigurieren Sie eines der in der folgenden Tabelle definierten Transaktionsattribute.

   Attribut	Beschreibung
   Bruttopreis	Dieses Attribut gilt nur für Preispläne, für die das Umsatzbeteiligungsmodell verwendet wird. Für diese Preispläne ist entweder der Bruttopreis oder der Nettopreis obligatorisch. Der numerische Wert muss als Stringtyp ausgedrückt sein. Der Bruttopreis einer Transaktion. Bei Plänen zur Umsatzbeteiligung müssen Sie entweder das Bruttopreis- oder das Nettopreisattribut angeben. Welches Attribut erforderlich ist, hängt von der Umsatzbeteiligung ab. Sie können beispielsweise einen Plan für die Umsatzbeteiligung einrichten, der auf dem Bruttopreis einer Transaktion basiert. In diesem Fall ist das Feld „Bruttopreis“ erforderlich.
   Nettopreis	Dieses Attribut gilt nur für Preispläne, für die das Umsatzbeteiligungsmodell verwendet wird. Für diese Preispläne ist entweder der Bruttopreis oder der Nettopreis obligatorisch. Der numerische Wert muss als Stringtyp ausgedrückt sein. Nettopreis für eine Transaktion. Bei Plänen zur Umsatzbeteiligung müssen Sie entweder das Feld „Nettopreis“ oder „Bruttopreis“ angeben. Welches Feld erforderlich ist, hängt von der Umsatzbeteiligung ab. Du kannst beispielsweise einen Plan für die Umsatzbeteiligung einrichten, der auf dem Nettopreis einer Transaktion basiert. In diesem Fall ist das Feld „Nettopreis“ erforderlich.
   Currency	Dieses Attribut ist für Preispläne erforderlich, für die das Umsatzbeteiligungsmodell verwendet wird. Währung, die für die Transaktion gilt.
   Fehlercode	Fehlercode der Transaktion. Sie enthält weitere Informationen zu einer fehlgeschlagenen Transaktion.
   Artikelbeschreibung	Beschreibung der Transaktion
   Steuer	Dieses Attribut ist nur für Modelle mit Umsatzbeteiligung relevant und nur dann, wenn der Steuerbetrag in den API-Aufrufen erfasst wird. Der numerische Wert muss als Stringtyp ausgedrückt werden. Steuerbetrag für den Kauf. Nettopreis zuzüglich Steuern = Bruttopreis.

Wenn Sie beispielsweise die folgenden Werte festlegen, erhält die Monetarisierung den Wert der Flussvariablen aus der Nachrichtenantwort in einer Variablen namens response.reason.phrase. Wenn der Wert in Ordnung ist und die Richtlinie zur Überprüfung der Monetarisierungslimits an die ProxyEndpoint Proxy-Anfrage angehängt wird, wird die Monetarisierung als Transaktion gezählt.

Feld	Wert
Kriterien für die Transaktion	txProviderStatus == 'OK'
Status: API-Ressource	**
Status: Speicherort der Antwort	Ablaufvariable
Status: Flussvariable	response.reason.phrase

Benutzerdefinierte Attribute konfigurieren

Im Abschnitt Benutzerdefinierte Attribute geben Sie benutzerdefinierte Attribute an, die in der Richtlinie zur Transaktionsaufzeichnung enthalten sein sollen. Wenn Sie beispielsweise einen Preislistenplan einrichten, bei dem Sie den Entwickler für jede Transaktion in Rechnung stellen, können Sie den Preis für den Tarif auf der Grundlage eines benutzerdefinierten Attributs festlegen, z. B. der Anzahl der in einer Transaktion übertragenen Byte. Sie müssen dann dieses benutzerdefinierte Attribut in die Richtlinie zur Transaktionsaufzeichnung aufnehmen.

Jedes dieser Attribute wird im Transaktionsprotokoll gespeichert und kann abgefragt werden. Sie werden auch angezeigt, wenn Sie einen Preisplan erstellen, sodass Sie ein oder mehrere dieser Attribute auswählen können, auf denen Ihr Preis für den Tarif basiert.

Sie können benutzerdefinierte Attribute, die in der Richtlinie zur Transaktionsaufzeichnung definiert sind, in zusammenfassende Berichte zum Umsatz aufnehmen, wie unter Benutzerdefinierte Attribute in Umsatzzusammenfassungen einbeziehen beschrieben.

Wenn Sie benutzerdefinierte Attribute konfigurieren möchten, aktivieren Sie die Ein-/Aus-Schaltfläche Benutzerdefinierte Attribute verwenden und definieren Sie bis zu zehn benutzerdefinierte Attribute. Sie müssen für jedes benutzerdefinierte Attribut, das Sie in die Richtlinie zur Transaktionsaufzeichnung aufnehmen, die folgenden Informationen angeben.

Feld	Beschreibung
Name des benutzerdefinierten Attributs	Geben Sie einen Namen ein, der das benutzerdefinierte Attribut beschreibt. Wenn der Preisplan auf einem benutzerdefinierten Attribut basiert, wird dem Nutzer der Name in den Details des Preisplans angezeigt. Wenn im benutzerdefinierten Attribut beispielsweise die Dauer erfasst wird, sollten Sie den Wert für das Attribut angeben. Die tatsächlichen Einheiten für das benutzerdefinierte Attribut, beispielsweise Stunden, Minuten oder Sekunden, werden im Feld für die Bewertungseinheit festgelegt, wenn Sie einen Preisplan für benutzerdefinierte Attribute erstellen (siehe Preisplan mit Details zu benutzerdefinierten Attributen angeben).
API-Ressource	Wählen Sie ein oder mehrere URI-Suffixe (d. h. das URI-Fragment nach dem Basispfad) einer API-Ressource aus, auf die in der Transaktion zugegriffen wird. Die verfügbaren Ressourcen sind die gleichen wie für Transaktionsattribute.
Speicherort der Antwort	Wählen Sie den Ort in der Antwort aus, in dem das Attribut angegeben ist. Zulässige Werte sind: Flow Variable, Header, JSON Body und XML Body.
Wert	Geben Sie einen Wert für das benutzerdefinierte Attribut an. Jeder von Ihnen angegebene Wert entspricht einem Feld, einem Parameter oder einem Inhaltselement, das bzw. das das benutzerdefinierte Attribut am von Ihnen angegebenen Standort bereitstellt. Wenn Sie mehr als einen Wert festlegen möchten, klicken Sie auf + x hinzufügen (z. B. + Ablaufvariable hinzufügen). Wenn du beispielsweise ein benutzerdefiniertes Attribut mit dem Namen „Content Length“ konfigurierst und den Header als Antwortort auswählst und der Wert für die Contentlänge im Feld „HTTP-Contentlänge“ angegeben wird, musst du als Wert Content-Length angeben.

Ressourcen mit eindeutiger Transaktions-ID verknüpfen

Einige Transaktionen sind einfach und umfassen einen API-Aufruf an eine Ressource. Andere Transaktionen können jedoch komplexer sein. Beispiel: Eine Transaktion für den Kauf eines In-App-Produkts in einer mobilen Gaming-App umfasst mehrere Ressourcenaufrufe:

• Ein Aufruf einer Reserve API, mit dem sichergestellt wird, dass ein Prepaidnutzer genügend Guthaben für den Kauf des Produkts hat und den entsprechenden Betrag für den Kauf zuweist (reserviert).
• Ein Aufruf einer Charge API, bei der der Betrag vom Konto des vorausbezahlten Nutzers abgezogen wird.

Damit die gesamte Transaktion verarbeitet werden kann, muss die erste Ressource (der Aufruf und die Antwort an die Reservierungs-API) mit der zweiten Ressource (der Aufruf und die Antwort auf die und von der Charge API) verknüpft werden. Dazu stützt es sich auf Informationen, die Sie im Abschnitt Ressourcen mit eindeutiger Transaktions-ID verknüpfen angeben.

Wenn Sie benutzerdefinierte Attribute konfigurieren möchten, aktivieren Sie die Ein-/Aus-Schaltfläche Eindeutige Transaktions-IDs verwenden und verknüpfen Sie die Transaktionen. Für jede Transaktion geben Sie eine Ressource, den Antwortort und den Attributwert an, die mit den entsprechenden Werten in den anderen Transaktionen verknüpft sind.

Angenommen, der Reserve API-Aufruf und der Charge API-Aufruf sind so verknüpft: Ein Feld mit dem Namen session_id im Antwortheader der Reserve API entspricht einem Antwortheader mit dem Namen reference_id aus der Charge API. In diesem Fall könnten Sie die Einträge im Abschnitt „Ressourcen mit eindeutiger Transaktions-ID verknüpfen“ so festlegen:

Ressource	Speicherort der Antwort	Wert
reserve/{id}**	Header	session_id
/charge/{id}**	Header	reference_id

Erstattungen konfigurieren

Im Abschnitt Erstattungen legst du Attribute fest, die bei der Monetarisierung von Erstattungen verwendet werden.

Angenommen, ein Nutzer kauft ein Produkt in einer mobilen App, in der Ihre monetarisierten APIs verwendet werden. Die Transaktion wird auf Grundlage des gemeinsamen Umsatzplans monetarisiert. Angenommen, der Nutzer ist mit dem Produkt unzufrieden und möchte es zurückgeben. Wenn das Produkt über einen Aufruf an die API erstattet wird, über den die Erstattung erfolgt, werden die erforderlichen Anpassungen bei der Monetarisierung vorgenommen. Dazu werden die Informationen verwendet, die du im Abschnitt zu Erstattungen der Richtlinie zur Transaktionsaufzeichnung angegeben hast.

Um Erstattungen zu konfigurieren, aktivieren Sie die Ein-/Aus-Schaltfläche Erstattungsattribute verwenden und definieren Sie die Erstattungsdetails:

1. Definieren Sie die Erstattungskriterien, indem Sie die folgenden Felder definieren:

   Feld	Beschreibung
   Speicherort der Antwort	Ressource für die Erstattungstransaktion. Wenn das API-Produkt mehrere Ressourcen bereitstellt, kannst du nur die Ressource auswählen, die die Erstattung ausführt.
   Kriterien für die Erstattung erfolgreich	Ausdruck, der auf dem Wert des Statusattributs (wie unten beschrieben) zum Ermitteln des Erfolgs der Erstattungstransaktion (zu Abrechnungszwecken) basiert. Erstattungen, die nicht erfolgreich sind, also die Kriterien im Ausdruck nicht erfüllen, werden erfasst, aber keine Preispläne auf sie angewendet. Beispiel: txProviderStatus == 'OK'

2. Konfigurieren Sie das Attribut Status, indem Sie die folgenden Felder definieren:

   Feld	Beschreibung
   Speicherort der Antwort	Speicherort der Antwort, in der das Attribut angegeben ist. Zulässige Werte sind: Flow Variable, Header, JSON Body und XML Body.
   Wert	Wert der Antwort Wenn Sie mehr als einen Wert festlegen möchten, klicken Sie auf + x hinzufügen (z. B. + Ablaufvariable hinzufügen).

3. Konfigurieren Sie das Attribut Übergeordnete ID, indem Sie die folgenden Felder definieren:

   Feld	Beschreibung
   Speicherort der Antwort	Speicherort der Antwort, in der das Attribut angegeben ist. Zulässige Werte sind: Flow Variable, Header, JSON Body und XML Body.
   Wert	ID der Transaktion, für die eine Erstattung verarbeitet wird. Wenn ein Nutzer beispielsweise ein Produkt kauft und dann eine Erstattung beantragt, ist die übergeordnete Transaktions-ID die ID der Kauftransaktion. Wenn Sie mehr als einen Wert festlegen möchten, klicken Sie auf + x hinzufügen (z. B. + Ablaufvariable hinzufügen).

4. Wenn Sie optionale Erstattungsattribute konfigurieren möchten, aktivieren Sie die Ein-/Aus-Schaltfläche Optionale Erstattungsattribute verwenden und konfigurieren Sie die Attribute. Die optionalen Erstattungsattribute sind identisch mit den optionalen Transaktionsattributen, die unter Transaktionsattribute konfigurieren definiert sind.

Richtlinien für die Transaktionsaufnahme mit der API verwalten

In den folgenden Abschnitten wird beschrieben, wie Sie Richtlinien für die Transaktionsaufzeichnung mit der API verwalten.

Transaktionsaufzeichnungsrichtlinie mit der API erstellen

Sie geben eine Transaktionsaufzeichnungsrichtlinie als Attribut eines API-Produkts an. Der Wert des Attributs gibt Folgendes an:

• Das URI-Suffix der Produktressource, an die die Transaktionsaufzeichnungsrichtlinie angehängt ist. Das Suffix enthält eine Mustervariable, die in geschweiften Klammern steht. Die Mustervariable wird zur Laufzeit von API-Diensten ausgewertet. Das folgende URI-Suffix enthält beispielsweise die Mustervariable {id}.

  /reserve/{id}**
  

  In diesem Fall wertet API-Dienste das URI-Suffix der Ressource als /reserve aus, gefolgt von einem Unterverzeichnis, das mit einer vom API-Anbieter definierten ID beginnt.

• Die Ressource in der Antwort, an die sie angehängt ist. Ein API-Produkt kann mehrere Ressourcen haben und an jede Ressource kann eine Richtlinie zur Transaktionsaufzeichnung angehängt werden, die an die Antwort der Ressource angehängt ist.
• Eine Extraktionsvariablen-Richtlinie, die es der Transaktionsaufzeichnungsrichtlinie ermöglicht, Inhalte aus einer Antwortnachricht für die zu erfassenden Transaktionsparameter zu extrahieren.

Sie fügen das Attribut der Transaktionsaufzeichnungsrichtlinie einem API-Produkt hinzu, indem Sie eine PUT-Anfrage an die Management-API https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (und nicht an eine Monetarisierungs-API) senden.

Erfolgskriterien für Transaktionen mit der API angeben

Sie können Kriterien für den Transaktionserfolg angeben, um zu bestimmen, wann eine Transaktion erfolgreich ist (für Abbuchungen). Nicht erfolgreiche Transaktionen, d. h., sie erfüllen die Kriterien im Ausdruck, werden aufgezeichnet, aber keine Preispläne auf sie angewendet. Beispiele zum Festlegen von Erfolgskriterien für Transaktionen finden Sie unter Beispiele für die Festlegung von Erfolgskriterien für Transaktionen in einer Transaktionsaufzeichnungsrichtlinie.

Sie geben die Kriterien für den Transaktionserfolg als Attribut eines API-Produkts an. Senden Sie dazu eine PUT-Anfrage an die Management API https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (nicht an die Monetarisierungs-API).

Beispielsweise wird in der folgenden Anfrage eine Transaktion erfolgreich abgeschlossen, wenn der Wert von txProviderStatus auf success gesetzt ist. Die zugehörigen Spezifikationen sind dann hervorgehoben.

$ curl -H "Content-Type: application/json" -X PUT -d \ 
'{
        "apiResources": [
        "/reserve/{id}**"       
        ],
        "approvalType": "auto",
        "attributes": [                         
        {
                "name": "MINT_TRANSACTION_SUCCESS_CRITERIA",
                "value": "txProviderStatus == 'OK'"
        }
        ],
        "description": "Payment",
        "displayName": "Payment",
        "environments": [
        "dev"
        ],
        "name": "payment",
        "proxies": [],
        "scopes": [
        ""
        ]
}' \
"https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/payment" \
-u email:password

Benutzerdefinierte Attribute mithilfe der API angeben

Sie können benutzerdefinierte Attribute für ein API-Produkt angeben, auf dem die Gebühren für den Basis-Abo basieren. Wenn Sie beispielsweise einen Preislistenplan einrichten, bei dem Sie den Entwickler für jede Transaktion in Rechnung stellen, können Sie den Preis für den Tarif auf der Grundlage eines benutzerdefinierten Attributs festlegen, z. B. der Anzahl der in einer Transaktion übertragenen Byte. Wenn Sie einen Preisplan erstellen, können Sie ein oder mehrere benutzerdefinierte Attribute angeben, auf denen der Preis für den Tarif basieren soll. Allerdings kann für ein bestimmtes Produkt in einem Preisplan nur ein benutzerdefiniertes Attribut vorhanden sein, auf dem der Preis für den Tarif basiert.

Sie geben benutzerdefinierte Attribute als Attribute eines API-Produkts an. Senden Sie dazu eine PUT-Anfrage an die Management API https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (und nicht an die Monetarisierungs-API).

Für jedes benutzerdefinierte Attribut, das Sie einem API-Produkt hinzufügen, müssen Sie einen Namen und einen Attributwert angeben. Der Name muss das Format MINT_CUSTOM_ATTRIBUTE_{num} haben, wobei {num} eine Ganzzahl ist.

In der folgenden Anfrage werden beispielsweise drei benutzerdefinierte Attribute angegeben.

$ curl -H "Content-Type: application/json" -X PUT -d \
'{
        "apiResources": [
        "/reserve/{id}**",
        "/charge/{id}**"
        ],
        "approvalType": "auto",
        "attributes": [
        {
                "name": "MINT_CUSTOM_ATTRIBUTE_1",
                "value": "test1"
        },
        {
                "name": "MINT_CUSTOM_ATTRIBUTE_2",
                "value": "test2"
        }
 
        ],
        "name": "payment",
        "proxies": [],
        "scopes": [
                ""
        ]
}' \
"https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/payment" \
-u email:password

Beispiele für das Festlegen von Erfolgskriterien für Transaktionen in einer Transaktionsaufzeichnungsrichtlinie

Die folgende Tabelle enthält Beispiele für erfolgreiche und nicht erfolgreiche Transaktionen, die auf dem Ausdruck für Transaktionserfolgskriterien und dem vom API-Proxy zurückgegebenen txProviderStatus-Wert basieren. txProviderStatus ist die interne Variable, mit der die Monetarisierung den Transaktionserfolg bestimmt.

Ausdruck für Erfolgskriterien	Gültiger Ausdruck?	Wert „txProviderStatus“ aus API-Proxy	Ergebnis der Bewertung
null	true	"200"	false
""	false	"200"	false
" "	false	"200"	false
"sdfsdfsdf"	false	"200"	false
"txProviderStatus =='100'"	true	"200"	false
"txProviderStatus =='200'"	true	"200"	true
"true"	true	"200"	true
"txProviderStatus=='OK' OR txProviderStatus=='Not Found' OR txProviderStatus=='Bad Request'"	true	"OK"	true
"txProviderStatus matches '(OK)|(Not Found)|(Bad Request)'"	true	"OK"	true
"txProviderStatus matches '(OK)|(Not Found)|(Bad Request)'"	true	"Not Found"	true
"txProviderStatus matches '(OK)|(Not Found)|(Bad Request)'"	true	"Bad Request"	true
"(txProviderStatus?:'') matches '(?i)(OK)|(Not Found)|(Bad Request)'"	true	"Bad Request"	true
"(txProviderStatus?:'') matches '(?i)(OK)|(Not Found)|(Bad Request)'"	true	null	false
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'"	true	"bad request"	true
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'"	true	"Redirect"	false
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'"	true	"heeeelllooo"	false
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'"	true	null	false
"txProviderStatus == 100"	true	"200"	false