Abrechenbare Ereignisse zu einem Anwendungspaket hinzufügen

Wenn Sie Custom Event Billing für eine Snowflake Native App verwenden, können Sie zusätzlich zu den bestehenden verbrauchsabhängigen Preistarifen bestimmte Typen der Anwendungsnutzung in Rechnung stellen. Zum Einrichten müssen Sie zwei allgemeine Schritte ausführen:

  1. Richten Sie das Anwendungspaket so ein, dass es abrechenbare Ereignisse ausgibt, indem Sie die Schritte unter diesem Thema befolgen.

  2. Wählen Sie einen verbrauchsabhängigen Preistarif mit abrechenbaren Ereignissen für das Freigabeangebot aus, über das Sie Ihre Snowflake Native App für Verbraucher veröffentlichen.

Unter diesem Thema wird beschrieben, wie Sie ein Anwendungspaket so einrichten, dass es mithilfe der Systemfunktion SYSTEM$CREATE_BILLING_EVENT abrechenbare Ereignisse ausgibt.

Übersicht der abrechenbaren Ereignisse in einem Anwendungspaket

Sie können ein Anwendungspaket so einrichten, dass es als Reaktion auf bestimmte Nutzungsereignisse abrechenbare Ereignisse ausgibt, sodass Sie den Verbrauchern die Nutzung Ihrer Snowflake Native App in Rechnung stellen können.

Sie können zum Beispiel ein abrechenbares Ereignis hinzufügen, um einem Verbraucher für jeden Aufruf einer gespeicherten Prozedur in Ihrer Snowflake Native App einen bestimmten Betrag in Rechnung zu stellen.

Um abrechenbare Ereignisse zu einem Anwendungspaket hinzuzufügen, gehen Sie wie folgt vor:

  1. Erstellen Sie gespeicherte Prozeduren, um zu definieren, welche Nutzungsereignisse Aufrufe der Systemfunktion SYSTEM$CREATE_BILLING_EVENT auslösen.

    Bemerkung

    In diesem Schritt können Sie die Ausgabe der Systemfunktion noch nicht testen. Diese Systemfunktion kann nur von einer Snowflake Native App aufgerufen werden, die in einem Verbraucherkonto installiert ist.

  2. Fügen Sie diese gespeicherten Prozeduren zum Setup-Skript des Anwendungspakets hinzu.

Wichtig

Snowflake unterstützt abrechenbare Ereignisse, die durch den Aufruf der Systemfunktion innerhalb einer gespeicherten Prozedur der Anwendung ausgegeben werden, wie in den Beispielen unter diesem Thema beschrieben.

Snowflake unterstützt keine anderen Methoden zur Berechnung der Grundgebühr für abrechenbare Ereignisse, wie z. B. Methoden, die die Ausgabe einer Tabelle oder einer benutzerdefinierten Funktion verwenden, die die Verbraucheraktivität ausgibt, oder Methoden, die in einer Ereignistabelle protokollierte Telemetriedaten verwenden.

Wenn Sie sich nicht sicher sind, ob eine vorgeschlagene Implementierung unterstützt wird, wenden Sie sich an Ihren Snowflake-Kundenbetreuer.

Beispiele für abrechenbare Ereignisse

Die Beispiele in diesem Abschnitt zeigen, wie Sie gespeicherte Prozeduren erstellen, um abrechenbare Ereignisse für typische Abrechnungsszenarios auszugeben. In jedem dieser Beispiele wird die Funktion createBillingEvent aufgerufen, die in Systemfunktion SYSTEM$CREATE_BILLING_EVENT aufrufen definiert ist.

Systemfunktion SYSTEM$CREATE_BILLING_EVENT aufrufen

Das folgende Beispiel zeigt, wie Sie eine Wrapper-Funktion in einer gespeicherten Prozedur erstellen, um die Systemfunktion SYSTEM$CREATE_BILLING_EVENT aufzurufen.

Bemerkung

Sie können diese Systemfunktion in einer gespeicherten Prozedur aufrufen, die in JavaScript, Python oder Java geschrieben wurde.

In diesem Beispiel wird eine gespeicherte JavaScript-Prozedur namens custom_event_billing in der Datenbank db_1 und dem Schema public erstellt. Die gespeicherte Prozedur erstellt eine Hilfsfunktion namens createBillingEvent, die Argumente entgegennimmt, die den von der Systemfunktion SYSTEM$CREATE_BILLING_EVENT erwarteten Parametern entsprechen.

Weitere Informationen zu den Parametern und den erforderlichen Typen finden Sie unter SYSTEM$CREATE_BILLING_EVENT.

 CREATE OR REPLACE PROCEDURE db_1.public.custom_event_billing()
 RETURNS NULL
 LANGUAGE JAVASCRIPT
 AS
 $$
   /**
    * Helper method to add a billable event
    * Format timestamps as Unix timestamps in milliseconds
    */

   function createBillingEvent(className, subclassName, startTimestampVal, timestampVal, baseCharge, objects, additionalInfo) {
        try {
            var res = snowflake.createStatement({
            sqlText: `SELECT SYSTEM$CREATE_BILLING_EVENT('${className}',
                                                      '${subclassName}',
                                                      ${startTimestampVal},
                                                      ${timestampVal},
                                                      ${baseCharge},
                                                      '${objects}',
                                                      '${additionalInfo}')`
            }).execute();

            res.next();

            return res.getColumnValue(1);
        } catch(err) {
            return err.message;
        }
    }
$$;
Copy

Die Beispiele unter diesem Thema rufen diese Hilfsfunktion auf.

Beispiel: Abrechnung auf Basis von Aufrufen einer gespeicherten Prozedur

Das folgende Beispiel zeigt, wie Sie eine gespeicherte Prozedur erstellen, die ein abrechenbares Ereignis ausgibt, wenn ein Verbraucher diese gespeicherte Prozedur in einer Snowflake Native App aufruft.

Fügen Sie diesen Beispielcode in das Setup-Skript in derselben gespeicherten Prozedur ein, die die Hilfsfunktion definiert:

...
  //
  // Send a billable event when a stored procedure is called.
  //
  var event_ts = Date.now();
  var billing_quantity = 1.0;
  var base_charge = billing_quantity;
  var objects = "[ \"db_1.public.procedure_1\" ]";
  var retVal = createBillingEvent("PROCEDURE_CALL", "", event_ts, event_ts, base_charge, objects, "");
  // Run the rest of the procedure ...
$$;
Copy

Dieser Beispielcode erstellt eine gespeicherte Prozedur, die die Funktion createBillingEvent aufruft, um ein abrechenbares Ereignis mit dem Klassennamen PROCEDURE_CALL und einer Grundgebühr von 1.0 auszugeben.

Bemerkung

Die Typen der Argumente, die an die Funktion createBillingEvent übergeben werden, müssen den typisierten Parametern entsprechen, die von der Systemfunktion SYSTEM$CREATE_BILLING_EVENT erwartet werden.

Beispiel: Abrechnung auf Basis der von einer Snowflake Native App genutzten Zeilen

Das folgende Beispiel zeigt, wie Sie eine gespeicherte Prozedur erstellen, die ein abrechenbares Ereignis auf Basis der Anzahl der genutzten Zeilen einer Tabelle im Verbraucherkonto ausgibt.

Fügen Sie diesen Beispielcode in das Setup-Skript in derselben gespeicherten Prozedur ein, die die Hilfsfunktion definiert:

...
  // Run a query and get the number of rows in the result
  var select_query = "select i from db_1.public.t1";
  res = snowflake.execute ({sqlText: select_query});
  res.next();
  //
  // Send a billable event for rows returned from the select query
  //
  var event_ts = Date.now();
  var billing_quantity = 2.5;
  var base_charge = res.getRowcount() * billing_quantity;
  var objects = "[ \"db_1.public.t1\" ]";
  createBillingEvent("ROWS_CONSUMED", "", event_ts, event_ts, base_charge, objects, "");
  // Run the rest of the procedure ...
$$;
Copy

Dieser Beispielcode erstellt eine gespeicherte Prozedur, die die Funktion createBillingEvent aufruft, um ein abrechenbares Ereignis mit dem Klassennamen ROWS_CONSUMED und einer berechneten Grundgebühr von 2.5 multipliziert mit der Anzahl der Zeilen in der Tabelle db_1.public.t1 des Verbraucherkontos auszugeben.

Bemerkung

Die Typen der Argumente, die an die Funktion createBillingEvent übergeben werden, müssen den typisierten Parametern entsprechen, die von der Systemfunktion SYSTEM$CREATE_BILLING_EVENT erwartet werden.

Beispiel: Abrechnung auf Basis der Anzahl der erfassten Zeilen

Das folgende Beispiel zeigt, wie Sie eine gespeicherte Prozedur erstellen, die ein abrechenbares Ereignis auf Basis der Anzahl der in einer Tabelle erfassten Zeilen ausgibt.

Fügen Sie diesen Beispielcode in das Setup-Skript in derselben gespeicherten Prozedur ein, die die Hilfsfunktion definiert:

...
    // Run the merge query
    var merge_query = "MERGE INTO target_table USING source_table ON target_table.i = source_table.i
        WHEN MATCHED THEN UPDATE SET target_table.j = source_table.j
        WHEN NOT MATCHED
        THEN INSERT (i, j)
        VALUES (source_table.i, source_table.j)";
    res = snowflake.execute ({sqlText: merge_query});
    res.next();
    // rows ingested = rows inserted + rows updated
    var numRowsIngested = res.getColumnValue(1) + res.getColumnValue(2);

    //
    // Send a billable event for rows changed by the merge query
    //
    var event_ts = Date.now();
    var billing_quantity = 2.5;
    var base_charge = numRowsIngested * billing_quantity;
    var objects = "[ \"db_1.public.target_table\" ]";
    createBillingEvent("ROWS_CHANGED", "", event_ts, event_ts, base_charge, objects, "");
    // Run the rest of the procedure ...
$$;
Copy

Dieser Beispielcode erstellt eine gespeicherte Prozedur, die die Funktion createBillingEvent aufruft, um ein abrechenbares Ereignis mit dem Klassennamen ROWS_CHANGED und einer berechneten Grundgebühr von 2.5 multipliziert mit der Anzahl der in der Tabelle db_1.target_table erfassten Zeilen auszugeben.

Bemerkung

Die Typen der Argumente, die an die Funktion createBillingEvent übergeben werden, müssen den typisierten Parametern entsprechen, die von der Systemfunktion SYSTEM$CREATE_BILLING_EVENT erwartet werden.

Beispiel: Abrechnung auf Basis der monatlich aktiven Zeilen

Monatlich aktive Zeilen sind die Anzahl der Zeilen, die innerhalb eines Kalendermonats erstmalig eingefügt oder aktualisiert wurden. Einige Anbieter verwenden diese Metrik, um Verbrauchern nur einzelne Zeilen in Rechnung zu stellen, die in einem Monat aktualisiert werden. Sie können dieses Beispiel abändern, um zur Ermittlung der Grundgebühr stattdessen einzelne Benutzer zu zählen oder einen einzelnen Datenladeort zu identifizieren.

Das folgende Beispiel zeigt, wie Sie eine gespeicherte Prozedur erstellen, die ein abrechenbares Ereignis auf Basis der Anzahl der monatlich aktiven Zeilen ausgibt. Fügen Sie diesen Beispielcode in das Setup-Skript in derselben gespeicherten Prozedur ein, die die Hilfsfunktion definiert:

...
    //
    // Get monthly active rows
    //
    var monthly_active_rows_query = "
     SELECT
         count(*)
     FROM
         source_table
     WHERE
         source_table.i not in
         (
           SELECT
             i
           FROM
             target_table
           WHERE
             updated_on >= DATE_TRUNC('MONTH', CURRENT_TIMESTAMP)
         )";
    res = snowflake.execute ({sqlText: monthly_active_rows_query});
    res.next();
    var monthlyActiveRows = parseInt(res.getColumnValue(1));
    //
    // Run the merge query and update the updated_on values for the rows
    //
    var merge_query = "
        MERGE INTO
            target_table
        USING
            source_table
        ON
            target_table.i = source_table.i
        WHEN MATCHED THEN
         UPDATE SET target_table.j = source_table.j
                    ,target_table.updated_on = current_timestamp
        WHEN NOT MATCHED THEN
            INSERT (i, j, updated_on) VALUES (source_table.i, source_table.j, current_timestamp)";
    res = snowflake.execute ({sqlText: merge_query});
    res.next();
    //
    // Emit a billable event for monthly active rows changed by the merge query
    //
    var event_ts = Date.now();
    var billing_quantity = 0.02
    var base_charge = monthlyActiveRows * billing_quantity;
    var objects = "[ \"db_1.public.target_table\" ]";
    createBillingEvent("MONTHLY_ACTIVE_ROWS", "", event_ts, event_ts, base_charge, objects, "");
    // Run the rest of the procedure ...
$$;
Copy

Dieser Beispielcode erstellt eine gespeicherte Prozedur, die die Anzahl der monatlich aktiven Zeilen mithilfe einer Abfrage zur Identifizierung der einzelnen Zeilen ermittelt. Das Beispiel berechnet dann die Grundgebühr anhand des Wertes der Variable monthlyActiveRows und der billing_quantity. Die Grundgebühr wird dann an die Funktion createBillingEvent übergeben.

Bemerkung

Die Typen der Argumente, die an die Funktion createBillingEvent übergeben werden, müssen den typisierten Parametern entsprechen, die von der Systemfunktion SYSTEM$CREATE_BILLING_EVENT erwartet werden.

Fügen Sie in Ihrem Setup-Skript diese gespeicherte Prozedur nach der gespeicherten Prozedur ein, die die Systemfunktion SYSTEM$CREATE_BILLING_EVENT aufruft.

Snowpark Python-Beispiel: Abrechnung auf Basis der genutzten Zeilen

Wenn Sie Ihre gespeicherte Prozedur in Snowpark Python schreiben möchten, um auf der Basis der von Ihrer Snowflake Native App genutzten Zeilen abzurechnen, verwenden Sie das folgende Beispiel:

CREATE OR REPLACE PROCEDURE app_schema.billing_event_rows()
   RETURNS STRING
   LANGUAGE PYTHON
   RUNTIME_VERSION = '3.9'
   PACKAGES = ('snowflake-snowpark-python')
   HANDLER = 'run'
   EXECUTE AS OWNER
   AS $$
import time

# Helper method that calls the system function for billing
def createBillingEvent(session, class_name, subclass_name, start_timestamp, timestamp, base_charge, objects, additional_info):
   session.sql(f"SELECT SYSTEM$CREATE_BILLING_EVENT('{class_name}', '{subclass_name}', {start_timestamp}, {timestamp}, {base_charge}, '{objects}', '{additional_info}')").collect()
   return "Success"

# Handler function for the stored procedure
def run(session):
   # insert code to identify monthly active rows and calculate a charge
   try:

      # Run a query to select rows from a table
      query =  "select i from db_1.public.t1"
      res = session.sql(query).collect()

      # Define the price to charge per row
      billing_quantity = 2.5

      # Calculate the base charge based on number of rows in the result
      charge = len(res) * billing_quantity

      # Current time in Unix timestamp (epoch) time in milliseconds
      current_time_epoch = int(time.time() * 1000)

      return createBillingEvent(session, 'ROWS_CONSUMED', '', current_time_epoch, current_time_epoch, charge, '["billing_event_rows"]', '')
   except Exception as ex:
      return "Error " + ex
$$;
Copy

Dieser Beispielcode erstellt eine gespeicherte Prozedur, die eine Hilfsmethode definiert, die die Systemfunktion SYSTEM$CREATE_BILLING_EVENT aufruft, sowie eine Methode, die diese Hilfsmethode createBillingEvent aufruft, um ein abrechenbares Ereignis mit dem Klassennamen ROWS_CONSUMED und einer Grundgebühr auszugeben, die durch Multiplikation eines Preises von 2.5 US-Dollar mit der Anzahl der Zeilen in der Tabelle db_1.public.t1 des Verbraucherkontos berechnet wird.

Bemerkung

Die Typen der Argumente, die an die Funktion createBillingEvent übergeben werden, müssen den typisierten Parametern entsprechen, die von der Systemfunktion SYSTEM$CREATE_BILLING_EVENT erwartet werden.

Testen von Custom Event Billing

Um sicherzustellen, dass Sie Custom Event Billing ordnungsgemäß einrichten und dass abrechenbare Ereignisse für Nutzungsereignisse wie erwartet ausgegeben werden, gehen Sie wie folgt vor:

  1. Aktualisieren Sie Ihr Anwendungspaket:

    1. Aktualisieren Sie Ihr Setup-Skript, um die gespeicherten Prozeduren aufzunehmen, mit der abrechenbare Ereignisse ausgegeben werden.

    2. Aktualisieren Sie Ihr Anwendungspaket mit dem neuen Setup-Skript.

    3. Aktualisieren Sie die Version und die Release-Richtlinie für Ihr Anwendungspaket.

  2. Geben Sie das Anwendungspaket für ein Verbraucherkonto in Ihrer Organisation frei, auf das Sie Zugriff haben:

    1. Erstellen Sie ein privates Freigabeangebot.

    2. Fügen Sie Custom Event Billing als Preistarif für das Freigabeangebot hinzu.

    3. Geben Sie es für das Verbraucherkonto frei.

    4. Melden Sie sich über Snowsight beim Verbraucherkonto an.

    5. Installieren Sie die Snowflake Native App.

  3. Überprüfen Sie, ob die gespeicherten Prozeduren erfolgreich abrechenbare Ereignisse ausgeben.

  4. Überprüfen Sie, ob das Freigabeangebot korrekt eingerichtet ist.

Bemerkung

Wenn Sie Custom Event Billing testen, müssen Sie eine Zahlungsmethode einrichten, wobei Ihnen die Nutzung innerhalb Ihrer Organisation nicht in Rechnung gestellt wird.

Überprüfen, ob die gespeicherten Prozeduren abrechenbare Ereignisse ausgibt

Melden Sie sich beim Verbraucherkonto an, dem Sie Ihr Angebot freigegeben haben, und rufen Sie die gespeicherten Prozeduren auf, die Sie Ihrer Snowflake Native App hinzugefügt haben.

Um beispielsweise die gespeicherte Prozedur zu testen, die für die Abrechnung auf Basis der monatlich aktiven Zeilen erstellt wurde, gehen Sie wie folgt vor:

  1. Melden Sie sich über Snowsight bei Ihrem Verbraucherkonto an.

  2. Öffnen Sie ein Arbeitsblatt, und setzen Sie den Kontext auf db_1.public.

  3. Führen Sie die folgende SQL-Anweisung aus:

    CALL merge_procedure()
    
    Copy

    Wenn die gespeicherte Prozedur den Wert Success zurückgibt, funktioniert Ihr Code.

Bemerkung

Wenn Sie diese SQL-Befehle in dem Anbieterkonto ausführen, das Sie zum Erstellen des Anwendungspakets verwendet haben, wird ein Fehler angezeigt.

Custom Event Billing-Preistarif überprüfen

Um die Benutzererfahrung einer Snowflake Native App für die Verbraucher zu überprüfen und sicherzustellen, dass Freigabeangebot und Anwendungspaket korrekt eingerichtet sind, können Sie die Ansicht MARKETPLACE_PAID_USAGE_DAILY im DATA_SHARING_USAGE-Schema der freigegebenen SNOWFLAKE-Datenbank abfragen.

Bemerkung

Aufgrund der Latenz in der Ansicht sollten Sie diese Abfragen frühestens zwei Tage nach der ersten Verwendung der Snowflake Native App ausführen.

Um sicherzustellen, dass Snowflake Native App und Freigabeangebot erfolgreich abrechenbare Ereignisse generieren, führen Sie die folgende SQL-Anweisung in dem Verbraucherkonto aus, für das Sie das Angebot freigegeben haben:

Bemerkung

Ersetzen Sie die Werte PROVIDER_ACCOUNT_NAME und PROVIDER_ORGANIZATION_NAME durch die Werte des Anbieterkontos.

SELECT listing_global_name,
   listing_display_name,
   charge_type,
   charge
FROM SNOWFLAKE.DATA_SHARING_USAGE.MARKETPLACE_PAID_USAGE_DAILY
WHERE charge_type='MONETIZABLE_BILLING_EVENTS'
      AND PROVIDER_ACCOUNT_NAME = <account_name>
      AND PROVIDER_ORGANIZATION_NAME= <organization_name>;
Copy
+---------------------+------------------------+----------------------------+--------+
| LISTING_GLOBAL_NAME |  LISTING_DISPLAY_NAME  |        CHARGE_TYPE         | CHARGE |
+---------------------+------------------------+----------------------------+--------+
| AAAA0BBB1CC         | Snowy Mountain Listing | MONETIZABLE_BILLING_EVENTS |   18.6 |
+---------------------+------------------------+----------------------------+--------+

Um alle mit dem Preistarif für das Freigabeangebot verbundenen Details anzuzeigen und zu überprüfen, ob der Tarif den Kosten für die Anwendung entspricht, führen Sie in dem Verbraucherkonto, für das Sie das Angebot freigegeben haben, die folgende SQL-Anweisung aus:

Bemerkung

Die Felder, denen pp vorangestellt ist, sind Felder, die nur im Freigabeangebot als Teil des Preistarifs angegeben sind.

SELECT
    listing_display_name,
    listing_global_name,
    be.value:display_name::varchar as class_name,
    be.value:class::varchar as class,
    units,
    be.value:billing_unit::varchar as billing_unit,
    unit_price,
    charge,
    be.value:billing_quantity::float as pp_billing_quantity
FROM
    SNOWFLAKE.DATA_SHARING_USAGE.MARKETPLACE_PAID_USAGE_DAILY,
    LATERAL FLATTEN(INPUT => pricing_plan:billing_events) be
WHERE
    charge_type = 'MONETIZABLE_BILLING_EVENTS'
    AND PROVIDER_ACCOUNT_NAME = <account_name>
    AND PROVIDER_ORGANIZATION_NAME= <organization_name>;
Copy
+------------------------+---------------------+-------------+---------------+-------+--------------+------------+--------+---------------------+
|  LISTING_DISPLAY_NAME  | LISTING_GLOBAL_NAME | CLASS_NAME  |     CLASS     | UNITS | BILLING_UNIT | UNIT_PRICE | CHARGE | PP_BILLING_QUANTITY |
+------------------------+---------------------+-------------+---------------+-------+--------------+------------+--------+---------------------+
| Snowy Mountain Listing | AAAA0BBB1CC         | Active Rows | ROWS_CONSUMED |  18.6 | ROW          |          1 |   18.6 |                   1 |
+------------------------+---------------------+-------------+---------------+-------+--------------+------------+--------+---------------------+