Hinzufügen von abrechenbaren Ereignissen zu einem Anwendungspaket¶

Aufrufen der Funktion SYSTEM$CREATE_BILLING_EVENT¶

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

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;
        }
    }
$$;

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 ...
$$;

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.

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 ...
$$;

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.

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 ...
$$;

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.

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 ...
$$;

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.

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
$$;

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.

Ü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.

Überprüfen des Custom Event Billing-Preistarifs¶

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.

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:

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>;

+---------------------+------------------------+----------------------------+--------+
| 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:

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>;

+------------------------+---------------------+-------------+---------------+-------+--------------+------------+--------+---------------------+
|  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 |
+------------------------+---------------------+-------------+---------------+-------+--------------+------------+--------+---------------------+