Richtlinien für die Transaktionsaufzeichnung konfigurieren

Sie lesen gerade die Dokumentation zu Apigee Edge.
Apigee X-Dokumentation aufrufen info

Konfigurieren Sie Richtlinien zur Transaktionsaufzeichnung für jedes API-Produkt in Ihrem API-Produktpaket, wie in den folgenden Abschnitten beschrieben.

Einführung

Mit einer Richtlinie zur Transaktionsaufzeichnung können Transaktionsparameter und benutzerdefinierte Attribute für die Monetarisierung erfasst werden. Für die Monetarisierung sind diese Informationen erforderlich, um die Monetarisierung abzuwickeln, z. B. Anwenden von Ratenplänen.

Wenn Sie beispielsweise einen Tarifplan für die Umsatzbeteiligung einrichten, wird ein Prozentsatz des Umsatzes, der mit jeder Transaktion mit Ihrem monetarisierten API-Produkt generiert 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 verwendet wird). Das heißt, ein Prozentsatz des Brutto- oder Nettopreises jeder Transaktion wird zur Berechnung der Umsatzbeteiligung verwendet. Aus diesem Grund muss bei der Monetarisierung der Brutto- oder Nettopreis einer Transaktion angegeben werden. Der Brutto- oder Nettopreis wird aus den Einstellungen in der Richtlinie zur Transaktionserfassung abgerufen.

Wenn Sie ein Preismodell mit Ratenkarte einrichten, bei dem Sie dem Entwickler jede Transaktion in Rechnung stellen, können Sie den Preis für das Preismodell anhand eines benutzerdefinierten Attributs wie der Anzahl der in einer Transaktion übertragenen Byte festlegen. Für die Monetarisierung muss bekannt sein, was das benutzerdefinierte Attribut ist und wo es zu finden ist. Sie müssen das benutzerdefinierte Attribut also in der Richtlinie zur Erfassung von Transaktionen angeben.

Zusätzlich zur Angabe von Transaktionsattributen in der Richtlinie zur Aufzeichnung von Transaktionen können Sie auch Kriterien für erfolgreiche Transaktionen angeben, um festzulegen, wann eine Transaktion erfolgreich ist (für Abrechnungszwecke). Beispiele für das Festlegen von Erfolgskriterien für Transaktionen finden Sie unter Beispiele für das Festlegen von Erfolgskriterien für Transaktionen in einer Richtlinie zur Aufzeichnung von Transaktionen. Sie können auch benutzerdefinierte Attribute für ein API-Produkt angeben, auf denen die Gebühren für das Tarifpaket basieren.

Richtlinie zur Transaktionsaufzeichnung konfigurieren

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

Transaktionsattribute konfigurieren

Geben Sie im Abschnitt Transaktionsattribute die Kriterien an, die auf eine erfolgreiche Monetarisierungstransaktion hinweisen.

1. Geben Sie im Feld Kriterien für erfolgreiche Transaktionen den Ausdruck basierend auf dem Wert des Attributs „Status“ (siehe unten) an, mit dem bestimmt wird, wann die Transaktion erfolgreich ist (für Abrechnungszwecke). Transaktionen, die nicht erfolgreich sind (d. h. die Kriterien im Ausdruck nicht erfüllen), werden aufgezeichnet, aber es werden keine Ratenpläne auf sie angewendet. Beispiel:

   txProviderStatus == 'OK'

2. Das Attribut Status enthält den Wert, der vom Ausdruck verwendet wird, der im Feld Kriterien für erfolgreiche Transaktionen konfiguriert ist. Konfigurieren Sie das Attribut Status, indem Sie die folgenden Felder definieren:

   Feld	Beschreibung
   API-Ressource	URI-Muster, die im API-Produkt definiert sind und zum Identifizieren monetarisierter Transaktionen verwendet werden.
   Antwortposition	Speicherort der Antwort, in der das Attribut angegeben ist. Gültige Werte sind: „Flow Variable“ (Flussvariable), „Header“, „JSON Body“ (JSON-Text) und „XML Body“ (XML-Text).
   Wert	Wert der Antwort. Wenn Sie mehrere Werte angeben 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 alle in der folgenden Tabelle definierten Transaktionsattribute.

   Attribut	Beschreibung
   Bruttopreis	Dieses Attribut gilt nur für Preismodelle, die das Umsatzbeteiligungsmodell verwenden. Für diese Preispläne ist entweder der Bruttopreis oder der Nettopreis erforderlich. Achten Sie darauf, dass der numerische Wert als String-Typ ausgedrückt wird. Bruttopreis für eine Transaktion. Bei Umsatzbeteiligungsmodellen müssen Sie entweder das Attribut „Bruttopreis“ oder das Attribut „Nettopreis“ erfassen. Welches Attribut erforderlich ist, hängt von der Grundlage der Umsatzbeteiligung ab. Sie können beispielsweise einen Tarif 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 Preismodelle, die das Umsatzbeteiligungsmodell verwenden. Für diese Preispläne ist entweder der Bruttopreis oder der Nettopreis erforderlich. Achten Sie darauf, dass der numerische Wert als String-Typ ausgedrückt wird. Nettopreis für eine Transaktion. Bei Plänen mit Umsatzbeteiligung müssen Sie entweder das Feld „Nettopreis“ oder das Feld „Bruttopreis“ aufzeichnen. Welches Feld erforderlich ist, hängt von der Grundlage der Umsatzbeteiligung ab. Sie können beispielsweise einen Tarif für die Umsatzbeteiligung einrichten, der auf dem Nettopreis einer Transaktion basiert. In diesem Fall ist das Feld „Nettopreis“ erforderlich.
   Währung	Dieses Attribut ist für Preismodelle erforderlich, die das Umsatzbeteiligungsmodell verwenden. Währungstyp für die Transaktion.
   Fehlercode	Der Fehlercode, der der Transaktion zugeordnet ist. Sie enthält weitere Informationen zu einer fehlgeschlagenen Transaktion.
   Artikelbeschreibung	Beschreibung der Transaktion.
   Steuern	Dieses Attribut ist nur für Modelle zur Umsatzbeteiligung relevant und nur, wenn der Steuerbetrag in den API-Aufrufen erfasst wird. Achten Sie darauf, dass der numerische Wert als String-Typ angegeben wird. Steuerbetrag für den Kauf. Nettopreis + Steuern = Bruttopreis.

Wenn Sie beispielsweise die folgenden Werte festlegen, ruft die Monetarisierung den Wert der Ablaufvariablen aus der Nachrichtenantwort in einer Variablen mit dem Namen response.reason.phrase ab. Wenn der Wert in Ordnung ist und die Monetization Limits Check policy an die ProxyEndpoint-Anfrage des API-Proxys angehängt ist, wird die Monetarisierung als Transaktion gezählt.

Benutzerdefinierte Attribute konfigurieren

Im Abschnitt Benutzerdefinierte Attribute geben Sie benutzerdefinierte Attribute an, die in die Richtlinie zur Transaktionsaufzeichnung aufgenommen werden sollen. Wenn Sie beispielsweise ein Preismodell mit Ratenkarte einrichten, bei dem Sie dem Entwickler jede Transaktion in Rechnung stellen, können Sie den Preis für das Modell anhand eines benutzerdefinierten Attributs wie der Anzahl der in einer Transaktion übertragenen Byte festlegen. Anschließend müssen Sie dieses benutzerdefinierte Attribut in die Richtlinie zur Erfassung von Transaktionen aufnehmen.

Jedes dieser Attribute wird im Transaktionslog gespeichert, das Sie abfragen können. Sie werden auch angezeigt, wenn Sie einen Tarif erstellen, damit Sie ein oder mehrere dieser Attribute auswählen können, auf denen Ihr Tarif für den Plan basieren soll.

Sie können benutzerdefinierte Attribute, die in der Richtlinie zur Transaktionsaufzeichnung definiert sind, in Ihre zusammenfassenden Umsatzberichte einbeziehen. Weitere Informationen finden Sie unter Benutzerdefinierte Transaktionsattribute in zusammenfassende Umsatzberichte einbeziehen.

Wenn Sie benutzerdefinierte Attribute konfigurieren möchten, aktivieren Sie den Ein/Aus-Button Benutzerdefinierte Attribute verwenden und definieren Sie bis zu 10 benutzerdefinierte Attribute. Für jedes benutzerdefinierte Attribut, das Sie in die Richtlinie zur Erfassung von Transaktionen aufnehmen, müssen Sie die folgenden Informationen angeben.

Ressourcen mit eindeutiger Transaktions-ID verknüpfen

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

• Ein Aufruf einer Reserve-API, die dafür sorgt, dass ein Prepaid-Nutzer genügend Guthaben hat, um das Produkt zu kaufen, und die Mittel für den Kauf zuweist („reserviert“).
• Ein Aufruf einer Abrechnungs-API, bei dem die Beträge vom Konto des Prepaid-Nutzers abgebucht werden.

Um die gesamte Transaktion zu verarbeiten, muss die Monetarisierung die erste Ressource (den Aufruf und die Antwort an und von der Reserve API) mit der zweiten Ressource (dem Aufruf und der Antwort an und von der Charge API) verknüpfen. Dazu werden Informationen verwendet, 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, einen Antwortort und einen Attributwert an, der mit den entsprechenden Werten in den anderen Transaktionen verknüpft ist.

Angenommen, der API-Aufruf „reserve“ und der API-Aufruf „charge“ sind so verknüpft, dass ein Feld namens session_id im Antwortheader der Reserve-API einem Antwortheader namens reference_id der Charge-API entspricht. In diesem Fall können Sie die Einträge im Bereich „Ressourcen mit eindeutiger Transaktions-ID verknüpfen“ so festlegen:

Erstattungen konfigurieren

Im Abschnitt „Erstattungen“ geben Sie Attribute an, die für die Verarbeitung von Erstattungen verwendet werden.

Angenommen, ein Nutzer kauft ein Produkt über eine mobile App, in der Ihre monetarisierten APIs verwendet werden. Die Transaktion wird auf Grundlage des Plans für die Umsatzbeteiligung monetarisiert. Angenommen, der Nutzer ist mit dem Produkt nicht zufrieden und möchte es zurückgeben. Wenn das Produkt über einen Aufruf Ihrer API erstattet wird, die die Erstattung ausführt, nimmt die Monetarisierung die erforderlichen Anpassungen vor. Das erfolgt auf Grundlage von Informationen, die Sie im Abschnitt „Erstattungen“ der Richtlinie zur Aufzeichnung von Transaktionen angeben.

Wenn Sie Erstattungen konfigurieren möchten, aktivieren Sie die Ein/Aus-Schaltfläche Use Refund Attributes (Erstattungsattribute verwenden) und definieren Sie die Erstattungsdetails:

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

   Feld	Beschreibung
   Antwortposition	Ressource für die Erstattungstransaktion. Wenn das API-Produkt mehrere Ressourcen bietet, können Sie nur die Ressource auswählen, mit der die Erstattung erfolgt.
   Erfolgskriterien für Erstattungen	Ausdruck, der auf dem Wert des Attributs „Status“ (siehe unten) basiert und bestimmt, wann die Erstattungstransaktion erfolgreich ist (für Abrechnungszwecke). Erstattungstransaktionen, die nicht erfolgreich sind (d. h. die nicht den Kriterien im Ausdruck entsprechen), werden aufgezeichnet, aber es werden keine Ratenpläne auf sie angewendet. Beispiel: txProviderStatus == 'OK'

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

   Feld	Beschreibung
   Antwortposition	Speicherort der Antwort, in der das Attribut angegeben ist. Gültige Werte sind: „Flow Variable“ (Flussvariable), „Header“, „JSON Body“ (JSON-Text) und „XML Body“ (XML-Text).
   Wert	Wert der Antwort. Wenn Sie mehrere Werte angeben möchten, klicken Sie auf + x hinzufügen (z. B. + Ablaufvariable hinzufügen).

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

   Feld	Beschreibung
   Antwortposition	Speicherort der Antwort, in der das Attribut angegeben ist. Gültige Werte sind: „Flow Variable“ (Flussvariable), „Header“, „JSON Body“ (JSON-Text) und „XML Body“ (XML-Text).
   Wert	ID der Transaktion, für die eine Erstattung erfolgt. Wenn ein Nutzer beispielsweise ein Produkt kauft und dann eine Erstattung beantragt, ist die übergeordnete Transaktions-ID die ID der Kauftransaktion. Wenn Sie mehrere Werte angeben 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 dieselben wie die optionalen Transaktionsattribute, wie in Transaktionsattribute konfigurieren beschrieben.

Richtlinien zur Transaktionsaufzeichnung mit der API verwalten

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

Transaktionsaufzeichnungsrichtlinie mit der API erstellen

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

• Das URI-Suffix der Produktressource, an die die Richtlinie zur Aufzeichnung von Transaktionen angehängt ist. Das Suffix enthält eine Mustervariable, die in geschweifte Klammern gesetzt ist. Die Muster-Variable wird von API-Diensten zur Laufzeit ausgewertet. Das folgende URI-Suffix enthält beispielsweise die Muster-Variable {id}.

  /reserve/{id}**

  In diesem Fall wertet API Services das URI-Suffix der Ressource als /reserve gefolgt von einem beliebigen Unterverzeichnis aus, 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 jeder Ressource kann eine Richtlinie zur Transaktionsaufzeichnung angehängt sein, die auf eine Antwort von dieser Ressource angewendet wird.
• Eine Richtlinie zum Extrahieren von Variablen, mit der die Richtlinie zum Aufzeichnen von Transaktionen Inhalte aus einer Antwortnachricht für die Transaktionsparameter extrahieren kann, die Sie erfassen möchten.

Sie fügen das Attribut für die Transaktionsaufzeichnung 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.

Kriterien für erfolgreiche Transaktionen mit der API angeben

Sie können Erfolgskriterien für Transaktionen angeben, um festzulegen, wann eine Transaktion erfolgreich ist (für Abrechnungszwecke). Transaktionen, die nicht erfolgreich sind (d. h. die die Kriterien im Ausdruck erfüllen), werden aufgezeichnet, aber es werden keine Ratenpläne auf sie angewendet. Beispiele für das Festlegen von Erfolgskriterien für Transaktionen finden Sie unter Beispiele für das Festlegen von Erfolgskriterien für Transaktionen in einer Richtlinie zur Aufzeichnung von Transaktionen.

Sie geben die Kriterien für erfolgreiche Transaktionen 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} (und nicht an die Monetization API).

Im folgenden Beispiel ist eine Transaktion erfolgreich, wenn der Wert von txProviderStatus gleich success ist. Die Spezifikationen für die Kriterien für erfolgreiche Transaktionen sind 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 mit der API angeben

Sie können benutzerdefinierte Attribute für ein API-Produkt angeben, auf denen die Gebühren für das Tarifpaket basieren. Wenn Sie beispielsweise ein Preismodell mit Ratenkarte einrichten, bei dem Sie dem Entwickler jede Transaktion in Rechnung stellen, können Sie die Rate für das Preismodell anhand eines benutzerdefinierten Attributs wie der Anzahl der in einer Transaktion übertragenen Byte festlegen. Wenn Sie ein Preismodell erstellen, können Sie ein oder mehrere benutzerdefinierte Attribute angeben, auf denen der Preis für das Modell basieren soll. Für jedes bestimmte Produkt in einem Tarif kann jedoch nur ein benutzerdefiniertes Attribut verwendet werden, auf dem der 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 Monetization 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 Richtlinie zur Aufzeichnung von Transaktionen

Die folgende Tabelle enthält Beispiele für erfolgreiche und nicht erfolgreiche Transaktionen basierend auf dem Ausdruck für die Erfolgskriterien der Transaktion und dem von dem API-Proxy zurückgegebenen txProviderStatus-Wert. txProviderStatus ist die interne Variable, die für die Monetarisierung verwendet wird, um den Erfolg von Transaktionen zu ermitteln.