Preisplan mit benutzerdefinierten Attributen konfigurieren

Sie sehen die Dokumentation zu Apigee Edge.
Zur Apigee X-Dokumentation
weitere Informationen

Einführung

In einigen Fällen müssen Transaktionszähler möglicherweise auf einer Variablen oder einem benutzerdefinierten Wert basieren. Beispielsweise müssen Sie eventuell Folgendes tun:

  • Sie können Entwicklern einen variablen Betrag basierend auf einem Wert in Rechnung stellen, der in der Nachricht eines API-Aufrufs angegeben ist. Sie können beispielsweise App-Entwicklern die Anzahl der in der API-Anfrage übertragenen Byte in Rechnung stellen.
  • Fassen Sie mehrere API-Aufrufe in einer einzigen Transaktion zusammen.

Mithilfe von Tarifplänen mit benutzerdefinierten Attributen können Sie einen Wert in der Nachricht eines API-Aufrufs identifizieren, der als Zähler fungiert und zur Berechnung der Anzahl und Kosten der Transaktionen verwendet wird.

Die folgenden Preispläne mit benutzerdefinierten Attributen werden unterstützt:

  • Preisliste mit benutzerdefiniertem Attribut
  • Anpassbare Benachrichtigung mit benutzerdefiniertem Attribut

Pro Preisplan können maximal zehn benutzerdefinierte Attribute festgelegt werden.

Erläuterungen zur Berechnung benutzerdefinierter Attribute

Wie der Wert des benutzerdefinierten Attributs bei der Anzahl und den Gebühren der Preisplantransaktionen berücksichtigt wird, hängt vom Abrechnungsmodell ab, wie in der folgenden Tabelle dargestellt.

Lademodell Berechnung benutzerdefinierter Attribute
Pauschalpreis und Band

custom attribute number * rate = charge to developer

Bei einem Pauschalpreis entspricht die Nummer des benutzerdefinierten Attributs der Anzahl der Transaktionen, die mit der Rate multipliziert werden. Bei Volume Banded wird die Anzahl der Transaktionen in einem Band um die Nummer des benutzerdefinierten Attributs erhöht und dem Entwickler wird diese Anzahl von Transaktionen in Rechnung gestellt. Wenn in der Nachricht beispielsweise der Wert eines benutzerdefinierten Attributs 10 ist, werden dem Entwickler 10 Transaktionen in Rechnung gestellt. Zur aktuellen Bandzahl werden 10 Transaktionen addiert. Wenn der Entwickler nur noch 6 Transaktionen im aktuellen Band hat, wird 6 mit der Rate für dieses Band multipliziert. Die restlichen vier gehen in das nächste Band und werden mit der Rate dieses Bandes multipliziert.

Wenn in einem Volumenband-Plan ein Limit für das letzte Volumenband vorliegt (nicht "unbegrenzt") und eine Transaktion dieses Limit überschreitet, passieren zwei Dinge:

Pakete

Da Pakete nach der Gruppe und nicht nach der Transaktion in Rechnung gestellt werden, erfolgt die folgende Berechnung:

custom attribute number = amount added to bundle count

Wenn in der Nachricht beispielsweise das benutzerdefinierte Attribut number 10 lautet, wird der Anzahl der in der Gruppierung verwendeten Transaktionen 10 hinzugefügt. Wenn im aktuellen Bundle nur noch 6 Transaktionen vorliegen, wird das Bundle gefüllt und die Anzahl der nächsten Bundles wird um 4 erhöht. Es wird gegebenenfalls der Preis für das nächste Paket berechnet.

Wenn das letzte Bundle ein Limit hat (nicht "unbegrenzt") und eine Transaktion dieses Limit überschreitet, passieren zwei Dinge:

Anpassbare Benachrichtigungen

Für anpassbare Benachrichtigungen wird folgende Berechnung durchgeführt:

custom attribute number = amount added to transaction count

Wenn das benutzerdefinierte Attribut number in der Nachricht beispielsweise 10 ist, wird 10 zur Gesamtzahl der Transaktionen addiert.

Wo der Preisplan den benutzerdefinierten Attributwert erhält

Die Richtlinie zur Transaktionsaufzeichnung (im API-Produktpaket) teilt der Monetarisierung mit, wo in der Nachricht nach dem Wert des benutzerdefinierten Attributs gesucht werden soll. Sie definieren das benutzerdefinierte Attribut im Abschnitt „Benutzerdefinierte Attribute“ der Richtlinie zur Transaktionsaufzeichnung für das API-Produktpaket.

Anschließend können Sie dieses benutzerdefinierte Attribut im Preisplan auswählen, nachdem Sie ein API-Produktpaket erstellt haben, das die Richtlinie zur Transaktionsaufzeichnung mit dem definierten benutzerdefinierten Attribut enthält.

Hier der allgemeine Ablauf:

  1. Definieren Sie die benutzerdefinierten Attribute, wenn Sie ein API-Produkt hinzufügen.
  2. Erstellen Sie ein API-Produktpaket, das das Produkt enthält.
    Fügen Sie in der Richtlinie zur Transaktionsaufzeichnung für das API-Produktpaket die benutzerdefinierten Attribute hinzu, die zum Definieren von Preisplänen verwendet werden.
  3. Erstellen Sie einen Preisplan vom Typ Preisliste oder anpassbare Benachrichtigung für das API-Produktpaket und geben Sie einen benutzerdefinierten Bewertungsparameter an.

Die folgende Abbildung zeigt die Beziehung zwischen dem in der Richtlinie zur Transaktionsaufzeichnung definierten benutzerdefinierten Attribut und der Konfiguration des Preislistenplans. Die anpassbare Benachrichtigung mit dem Preisplan-Verhältnis für benutzerdefinierte Attribute ist ähnlich, auch wenn der Wert für das Volumenband nicht anwendbar ist.

So generieren Sie den Wert des benutzerdefinierten Attributs in der Nachricht

Die Richtlinie zur Transaktionsaufzeichnung kann an verschiedenen Stellen nach dem benutzerdefinierten Attributwert suchen, z. B. im Antwortheader, im Antworttext oder in den vordefinierten Flussvariablen in der Antwort. Die Anfrage ist nicht verfügbar, da eine Transaktion erst offiziell ist, wenn Sie eine erfolgreiche Antwort erhalten. Die folgenden Beispiele zeigen, wie Sie der Nachricht einen Antwortheader mit seinem numerischen Wert hinzufügen. In beiden Fällen verwenden wir die Assign Message Policy in Verbindung mit Variablen.

Größe der Anfragenutzlast zum Antwortheader hinzufügen

In jeder Nachrichtenanfrage gibt es eine client.received.content.length-Variable, die die Anzahl der Byte in der Nutzlast der Anfrage enthält. Durch Anhängen einer Richtlinie zum Zuweisen von Nachrichten an die Antwort des Proxy-Endpunkts können wir einen Antwortheader mit dem Namen messageSize generieren, der den Längenwert enthält:

<AssignMessage async="false" continueOnError="false" enabled="true" name="Assign-Message-1">
    <DisplayName>Assign Message 1</DisplayName>
    <Set>
        <Headers>
          <Header name="messageSize">{client.received.content.length}</Header> 
        </Headers>  
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

Dem Header einen Wert für ein benutzerdefiniertes App-Attribut hinzufügen

Auf ähnliche Weise können wir einen Header mit dem Wert eines benutzerdefinierten Attributs in einer App generieren. Beispiel: Sie fügen für jede Entwickler-App ein benutzerdefiniertes Attribut mit dem Namen apprating ein:

Bei Verwendung der Richtlinie zum Überprüfen des API-Schlüssels (die für die Monetarisierung erforderlich ist) wird dieser Wert in einer Variablen namens verifyapikey.{policy_name}.apprating gespeichert. Mit der Richtlinie zum Zuweisen von Nachrichten, die an die Antwort des Proxy-Endpunkts angehängt ist, können Sie einen Header mit dem Namen apprating generieren, der den apprating-Wert der Anwendung enthält:

<AssignMessage async="false" continueOnError="false" enabled="true" name="Assign-Message-1">
    <DisplayName>Assign Message 1</DisplayName>
    <Set>
        <Headers>
          <Header name="apprating">{verifyapikey.Verify-API-Key-1.apprating}</Header> 
        </Headers>  
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

Preisplan einrichten

Abgesehen von der oben beschriebenen Einrichtung benutzerdefinierter Attribute wird der Preisplan wie gewohnt eingerichtet (für Preispläne ohne benutzerdefinierte Attribute), muss jedoch die folgenden Anforderungen erfüllen.

Preislistenplan mit benutzerdefiniertem Attribut über die Benutzeroberfläche konfigurieren

Konfigurieren Sie Preislistenpläne mit benutzerdefinierten Attributen mithilfe der Edge-Benutzeroberfläche oder der Classic Edge-Benutzeroberfläche, wie in den folgenden Abschnitten beschrieben.

Edge

So konfigurieren Sie einen Preislistenplan mit benutzerdefinierten Attributen über die Edge-Benutzeroberfläche:

  1. Definieren Sie die benutzerdefinierten Attribute, wenn Sie ein API-Produkt hinzufügen.
  2. Erstellen Sie ein API-Produktpaket, das das Produkt enthält. Siehe API-Produktsets erstellen.
    Fügen Sie in der Transaktionsaufzeichnungsrichtlinie für das API-Produktpaket die benutzerdefinierten Attribute hinzu, die zum Definieren von Preisplänen verwendet werden. Weitere Informationen finden Sie in der Einführung zu diesem Thema sowie unter Richtlinie zur Transaktionsaufzeichnung erstellen.
  3. Erstellen Sie einen Tarifplan für das API-Produktpaket und geben Sie einen benutzerdefinierten Bewertungsparameter an.

Weitere Informationen finden Sie unter Details zum Preislistenplan über die Benutzeroberfläche konfigurieren.

Classic Edge (Private Cloud)

Führen Sie die folgenden Schritte aus, um eine Preisliste mit einem Plan für benutzerdefinierte Attribute mithilfe der Classic Edge-Benutzeroberfläche zu erstellen:

  1. Fügen Sie der Richtlinie zur Transaktionsaufzeichnung eines API-Produkts die benutzerdefinierten Attribute hinzu, die zum Definieren von Preisplänen verwendet werden. Weitere Informationen finden Sie in der Einführung zu diesem Thema sowie unter Richtlinie zur Transaktionsaufzeichnung erstellen. Führen Sie dies für jedes API-Produkt aus, das Sie in das API-Paket aufnehmen möchten.
  2. Sobald die API-Produkte und Richtlinien für die Transaktionsaufzeichnung genau wie gewünscht konfiguriert sind, erstellen Sie ein API-Paket, das das Produkt enthält. Siehe API-Pakete erstellen.
  3. Erstellen Sie einen Preisplan für das API-Paket und wählen Sie den Preisplantyp Preisliste mit benutzerdefiniertem Attribut aus.
  4. Klicken Sie auf den Link Preisliste. Daraufhin wird das Fenster "Preisliste" geöffnet.

  5. Wählen Sie im Dropdown-Menü Benutzerdefiniertes Attribut ein benutzerdefiniertes Attribut aus. Das Menü enthält die benutzerdefinierten Attribute, die für das Produkt in einer Richtlinie zur Transaktionsaufzeichnung erstellt wurden. Dem Entwickler wird eine Gebühr entsprechend dem Wert des ausgewählten benutzerdefinierten Attributs in jeder Transaktion berechnet.
    (Attributwert × Preis = Gebühr an Entwickler)
  6. Richten Sie optional einen Freemium-Tarif ein, wie unter Details für Preislistentarife angeben beschrieben.
  7. Richten Sie ein Abrechnungsmodell ein, wie unter Preislistentarifdetails angeben beschrieben. Beachten Sie jedoch, dass für die Preisliste mit benutzerdefiniertem Attribut vom Preisplantyp das Abrechnungsmodell auf dem von Ihnen ausgewählten benutzerdefinierten Attribut basiert. Wenn Sie beispielsweise „Pauschalpreis“ als Abrechnungsmodell auswählen, wird dem Entwickler basierend auf dem benutzerdefinierten Attribut ein fester Preis berechnet, z. B. die Anzahl der bei jeder Transaktion übertragenen Byte (nicht ein fester Preis für jede Transaktion). Weitere Informationen finden Sie unter Berechnungen.
  8. Klicken Sie auf Entwurf speichern.
    Veröffentlichen Sie den Plan nur, wenn Sie sicher sind, dass er endgültig ist. Informationen zum Festlegen des Veröffentlichungsdatums und zum Veröffentlichen des Plans finden Sie unter Preispläne veröffentlichen.

Weitere Informationen finden Sie unter Details zum Preislistentarif über die Benutzeroberfläche angeben.

Konfigurieren eines anpassbaren Benachrichtigungsplans mit benutzerdefinierten Attributen über die Benutzeroberfläche

Konfigurieren Sie anpassbare Benachrichtigungspläne mit benutzerdefinierten Attributen, wie unten beschrieben.

Edge

So konfigurieren Sie einen Preislistenplan mit benutzerdefinierten Attributen über die Edge-Benutzeroberfläche:

  1. Definieren Sie die benutzerdefinierten Attribute, wenn Sie ein API-Produkt hinzufügen.
  2. Erstellen Sie ein API-Produktpaket, das das Produkt enthält. Siehe API-Produktsets erstellen.
    Fügen Sie in der Transaktionsaufzeichnungsrichtlinie für das API-Produktpaket die benutzerdefinierten Attribute hinzu, die zum Definieren von Preisplänen verwendet werden. Weitere Informationen finden Sie in der Einführung zu diesem Thema sowie unter Richtlinie zur Transaktionsaufzeichnung erstellen.
  3. Erstellen Sie einen Tarifplan für das API-Produktpaket und geben Sie einen benutzerdefinierten Bewertungsparameter an.

Weitere Informationen finden Sie unter Anpassbaren Benachrichtigungsplan mithilfe der Benutzeroberfläche konfigurieren.

Classic Edge (Private Cloud)

So konfigurieren Sie einen Preislistenplan mit benutzerdefinierten Attributen über die Classic Edge-Benutzeroberfläche:

  1. Fügen Sie der Richtlinie zur Transaktionsaufzeichnung eines API-Produkts die benutzerdefinierten Attribute hinzu, die zum Definieren von Preisplänen verwendet werden. Weitere Informationen finden Sie in der Einführung zu diesem Thema sowie unter Richtlinie zur Transaktionsaufzeichnung erstellen. Führen Sie dies für jedes API-Produkt aus, das Sie in das API-Paket aufnehmen möchten.
  2. Sobald die API-Produkte und Richtlinien für die Transaktionsaufzeichnung genau wie gewünscht konfiguriert sind, erstellen Sie ein API-Paket, das das Produkt enthält. Siehe API-Pakete erstellen.
  3. Erstellen Sie einen Preisplan für das API-Paket und wählen Sie den Preisplantyp Adjustable Notification with Custom Attribute (Einstellbare Benachrichtigung mit benutzerdefiniertem Attribut) aus.
  4. Klicken Sie auf den Link Details. Dadurch wird das Fenster „Anpassbare Benachrichtigung“ geöffnet.

  5. Wählen Sie im Drop-down-Menü Benutzerdefiniertes Attribut ein benutzerdefiniertes Attribut aus. Im Menü werden die benutzerdefinierten Attribute aufgelistet, die für das Produkt in einer Richtlinie zur Transaktionsaufzeichnung erstellt wurden. Die Gesamtzahl der Transaktionen des Entwicklers wird auf Basis des Werts des ausgewählten benutzerdefinierten Attributs innerhalb jeder Transaktion berechnet.
  6. Legen Sie als Aggregationsgrundlage den Zeitraum fest, über den das Transaktionsvolumen aggregiert wird. Wählen Sie eine Zahl zwischen 1 und 24 Monaten aus. Der Standardwert ist 1 Monat.
  7. Klicken Sie auf Übernehmen und schließen.
  8. Klicken Sie auf Entwurf speichern.
    Veröffentlichen Sie den Plan nur, wenn Sie sicher sind, dass er endgültig ist. Informationen zum Festlegen des Veröffentlichungsdatums und zum Veröffentlichen des Plans finden Sie unter Preispläne veröffentlichen.

Weitere Informationen finden Sie unter Details zum anpassbaren Benachrichtigungsplan über die UI angeben.

Details für einen Preisplan mit benutzerdefinierten Attributen über die API angeben

Führen Sie die folgenden erforderlichen Schritte aus:

  1. Fügen Sie der Richtlinie zur Transaktionsaufzeichnung eines API-Produkts die benutzerdefinierten Attribute hinzu, die zum Definieren von Preisplänen verwendet werden. Weitere Informationen finden Sie in der Einführung zu diesem Thema sowie unter Richtlinie zur Transaktionsaufzeichnung erstellen. Führen Sie dies für jedes API-Produkt aus, das Sie in das API-Paket aufnehmen möchten.
  2. Sobald die API-Produkte und Richtlinien für die Transaktionsaufzeichnung genau wie gewünscht konfiguriert sind, erstellen Sie ein API-Paket, das das Produkt enthält. Siehe API-Pakete erstellen.

Als Nächstes verwenden Sie die API, um den Preisplan zu erstellen.

Sie geben Details für einen Preisplan mit benutzerdefinierten Attributen an, wenn Sie den Preisplan erstellen. Die Details werden im Attribut ratePlanDetails im Anfragetext in einem Aufruf von /organizations/{org_name}/monetization-packages/{package_id}/rate-plans angegeben. In den Details geben Sie einen Bewertungsparameterwert an, der den Namen des benutzerdefinierten Attributs identifiziert. Sie können auch einen Bewertungsparameterwert angeben, mit dem das benutzerdefinierte Attribut über ein bestimmtes Zeitintervall aggregiert wird.

Eine vollständige Liste der Preisplandetailoptionen finden Sie unter Konfigurationseinstellungen für Preisplandetails.

Im folgenden Beispiel wird eine Preisliste mit einem Plan für benutzerdefinierte Attribute basierend auf einem benutzerdefinierten Attribut namens messageSize (siehe Elemente fett) erstellt.

$ curl -H "Content-Type:application/json" -X POST -d \
'{
   "name": "Custom attribute-based rate card plan",
   "developer":null,
   "developerCategory":null,
   "currency": {
     "id" : "usd"
     },     
   "description": "Custom attribute-based rate card plan",
   "displayName" : "Custom attribute-based rate card plan",
   "frequencyDuration": "1",
   "frequencyDurationType": "MONTH",
   "earlyTerminationFee": "10",
   "monetizationPackage": {
      "id": "location"
        },
      "organization": {
       "id": "{org_name}"
      },    
   "paymentDueDays": "30",
   "prorate": "false",
   "published": "false",     
   "ratePlanDetails":[
      {
        "currency":{
           "id":"usd"
        },
      "duration":1,
      "durationType":"MONTH",
      "meteringType":"VOLUME",
      "paymentDueDays":"30",
      "ratingParameter":"messageSize",
      "ratingParameterUnit":"MB",
      "organization":{
         "id":"{org_name}"
      },
      "ratePlanRates":[
         {
           "rate":0.15,
           "startUnit":0,
           "type":"RATECARD",
           "endUnit":1000
         },
         {
           "rate":0.1,
           "startUnit":1000,
           "type":"RATECARD",
           "endUnit":null
         }
      ],
      "freemiumUnit":0,
      "freemiumDuration":0,
      "freemiumDurationType":"MONTH",
      "type":"RATECARD",
      "customPaymentTerm":false
      }
    ],
    "freemiumUnit":0,
    "freemiumDuration":0,
    "freemiumDurationType":"MONTH",
    "contractDuration":"1",
    "contractDurationType":"YEAR", 
    "recurringStartUnit": 1,
    "recurringType": "CALENDAR",
    "recurringFee": "10",
    "setUpFee": "10",
    "startDate": "2013-09-15 00:00:00",
    "type": "STANDARD"
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages/location/rate-plans" \
-u email:password

Im Folgenden wird ein Preisplan für anpassbare Benachrichtigung mit benutzerdefiniertem Attribut basierend auf einem benutzerdefinierten Attribut namens messageSize (siehe Artikel fett) erstellt.

$ curl -H "Content-Type:application/json" -X POST -d \
'{
     "name": "AdjustableNotification",
     "displayName": "Custom attribute-based adjustable notification plan",
     "description": "Custom attribute-based adjustable notification plan",
     "published": "true",  
     "organization": {
      "id": "myorg"
     },
     "startDate": "2016-04-15 00:00:00",
     "type": "STANDARD",
     "monetizationPackage": {
        "id": "p1",
        "name": "test"
     },
     "currency": {
        "id" : "usd",
        "name" : "USD"
     },
     "ratePlanDetails": [
        {
           "type": "USAGE_TARGET",
           "meteringType": "DEV_SPECIFIC",
           "duration": 1,
           "durationType": "MONTH",
           "ratingParameter": "messageSize",
           "ratingParameterUnit": "MB",
           "organization": {
             "id": "myorg"
           },
           "currency": {
             "id": "usd",
             "name": "USD"
           }
        }
     ]
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/myorg/monetization-packages/p1/rate-plans"  \
-u email:password