Como adicionar eventos faturáveis a um aplicativo¶

Chamada da função SYSTEM$CREATE_BILLING_EVENT¶

O exemplo a seguir mostra como criar uma função wrapper em um procedimento armazenado para chamar a função do sistema SYSTEM$CREATE_BILLING_EVENT.

Este exemplo cria um procedimento armazenado JavaScript chamado custom_event_billing no banco de dados db_1 e esquema public. O procedimento armazenado cria uma função auxiliar chamada createBillingEvent que recebe argumentos que correspondem aos parâmetros digitados esperados pela função do sistema SYSTEM$CREATE_BILLING_EVENT.

Para obter mais detalhes sobre os parâmetros e os tipos necessários, consulte 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
    */

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

Os exemplos neste tópico chamam essa função auxiliar.

Exemplo: cobrança baseada em chamadas para um procedimento armazenado¶

O exemplo a seguir mostra como criar um procedimento armazenado para emitir um evento faturável quando um consumidor chama esse procedimento armazenado em um aplicativo.

Adicione este código de exemplo ao seu script de configuração no mesmo procedimento armazenado que define a função auxiliar:

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

Este código de exemplo cria um procedimento armazenado que chama a função createBillingEvent para emitir um evento faturável com o nome da classe PROCEDURE_CALL e uma cobrança básica de 1.0.

Exemplo: faturamento baseado em linhas consumidas por um aplicativo¶

O exemplo a seguir mostra como criar um procedimento armazenado para emitir um evento faturável com base no número de linhas consumidas em uma tabela na conta do consumidor.

Adicione este código de exemplo ao seu script de configuração no mesmo procedimento armazenado que define a função auxiliar:

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

Este código de exemplo cria um procedimento armazenado que chama o createBillingEvent função para emitir um evento faturável com o nome da classe ROWS_CONSUMED e uma cobrança base calculada de 2.5 multiplicado pelo número de linhas no db_1.public.t1 tabela na conta do consumidor.

Exemplo: cobrança com base no número de linhas ingeridas¶

O exemplo a seguir mostra como criar um procedimento armazenado para emitir um evento faturável com base no número de linhas ingeridas em uma tabela.

Adicione este código de exemplo ao seu script de configuração no mesmo procedimento armazenado que define a função auxiliar:

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

Este código de exemplo cria um procedimento armazenado que chama a função createBillingEvent para emitir um evento faturável com o nome da classe ROWS_CHANGED e uma cobrança base calculada de 2.5 multiplicado pelo número de linhas ingeridas na tabela db_1.target_table.

Faturamento baseado em linhas ativas mensais¶

As linhas ativas mensais são o número de linhas inseridas ou atualizadas pela primeira vez em um mês de calendário. Alguns provedores usam essa métrica para cobrar apenas dos consumidores por linhas exclusivas atualizadas em um mês. Você pode modificar este exemplo para contar usuários exclusivos ou identificar um local de carregamento de dados exclusivo para determinar uma cobrança básica.

O exemplo a seguir mostra como criar um procedimento armazenado para emitir um evento faturável com base no número de linhas ativas mensais. Adicione este código de exemplo ao seu script de configuração no mesmo procedimento armazenado que define a função auxiliar:

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

Este código de exemplo cria um procedimento armazenado que determina o número de linhas ativas mensais usando uma consulta de mesclagem para identificar linhas exclusivas. O exemplo então calcula a cobrança base usando o valor da variável monthlyActiveRows e o billing_quantity. A cobrança básica é então passada para a função createBillingEvent.

Em seu script de configuração, adicione este procedimento armazenado após o procedimento armazenado que chama a função do sistema SYSTEM$CREATE_BILLING_EVENT.

Exemplo do Snowpark Python: cobrança baseada em linhas consumidas¶

Se você deseja escrever seu procedimento armazenado no Snowpark Python para faturar com base nas linhas consumidas pelo seu aplicativo, use o seguinte exemplo:

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

Este código de exemplo cria um procedimento armazenado que define um método auxiliar que chama o SYSTEM$CREATE_BILLING_EVENT função do sistema, bem como um método que chama esse método auxiliar, createBillingEvent, para emitir um evento faturável com o nome da classe ROWS_CONSUMED e uma taxa básica calculada multiplicando um preço de 2.5 US dólares pelo número de linhas no db_1.public.t1 tabela na conta do consumidor.

Validação se os procedimentos armazenados podem emitir eventos faturáveis¶

Enquanto estiver conectado à conta do consumidor com a qual você compartilhou seu aplicativo, chame os procedimentos armazenados que você adicionou ao seu aplicativo.

Por exemplo, para testar o procedimento armazenado criado para cobrança baseada em linhas ativas mensais, faça o seguinte:

1. Entre na conta do consumidor em Snowsight.

2. Abra uma planilha e defina o contexto para db_1.public.

3. Execute a seguinte instrução SQL:

   CALL merge_procedure()
   

   Copy

   Se o procedimento armazenado retornar Success, seu código está funcionando.

Validação do plano de preços do Custom Event Billing¶

Para validar a experiência do consumidor de seu aplicativo e confirmar que sua listagem e aplicativo estão configurados corretamente, você pode consultar a exibição MARKETPLACE_PAID_USAGE_DAILY no esquema DATA_SHARING_USAGE do banco de dados SNOWFLAKE compartilhado.

Para confirmar se os eventos faturáveis foram gerados com êxito por seu aplicativo e listagem, execute a seguinte instrução SQL na conta do consumidor com a qual você compartilhou seu aplicativo:

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

Para ver todos os detalhes associados ao plano de preços da listagem e validar se o plano corresponde às cobranças do aplicativo, execute a seguinte instrução SQL na conta do consumidor com a qual você compartilhou seu aplicativo:

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