Class: Orb::Resources::Events::Backfills

Inherits:
Object
  • Object
show all
Defined in:
lib/orb/resources/events/backfills.rb,
sig/orb/resources/events/backfills.rbs

Overview

The Event resource represents a usage event that has been created for a customer. Events are the core of Orb's usage-based billing model, and are used to calculate the usage charges for a given billing period.

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ Backfills

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Backfills.

Parameters:



189
190
191
 
# File 'lib/orb/resources/events/backfills.rb', line 189

def initialize(client:)
  @client = client
end

Instance Method Details

#close(backfill_id, request_options: {}) ⇒ Orb::Models::Events::BackfillCloseResponse

Closing a backfill makes the updated usage visible in Orb. Upon closing a backfill, Orb will asynchronously reflect the updated usage in invoice amounts and usage graphs. Once all of the updates are complete, the backfill's status will transition to reflected.

Parameters:

Returns:

See Also:



133
134
135
136
137
138
139
140
 
# File 'lib/orb/resources/events/backfills.rb', line 133

def close(backfill_id, params = {})
  @client.request(
    method: :post,
    path: ["events/backfills/%1$s/close", backfill_id],
    model: Orb::Models::Events::BackfillCloseResponse,
    options: params[:request_options]
  )
end

#create(timeframe_end:, timeframe_start:, close_time: nil, customer_id: nil, deprecation_filter: nil, external_customer_id: nil, replace_existing_events: nil, request_options: {}) ⇒ Orb::Models::Events::BackfillCreateResponse

Some parameter documentations has been truncated, see Models::Events::BackfillCreateParams for more details.

Creating the backfill enables adding or replacing past events, even those that are older than the ingestion grace period. Performing a backfill in Orb involves 3 steps:

  1. Create the backfill, specifying its parameters.
  2. Ingest usage events, referencing the backfill (query parameter backfill_id).
  3. Close the backfill, propagating the update in past usage throughout Orb.

Changes from a backfill are not reflected until the backfill is closed, so you won’t need to worry about your customers seeing partially updated usage data. Backfills are also reversible, so you’ll be able to revert a backfill if you’ve made a mistake.

This endpoint will return a backfill object, which contains an id. That id can then be used as the backfill_id query parameter to the event ingestion endpoint to associate ingested events with this backfill. The effects (e.g. updated usage graphs) of this backfill will not take place until the backfill is closed.

If the replace_existing_events is true, existing events in the backfill's timeframe will be replaced with the newly ingested events associated with the backfill. If false, newly ingested events will be added to the existing events.

If a customer_id or external_customer_id is specified, the backfill will only affect events for that customer. If neither is specified, the backfill will affect all customers.

When replace_existing_events is true, this indicates that existing events in the timeframe should no longer be counted towards invoiced usage. In this scenario, the parameter deprecation_filter can be optionally added which enables filtering using computed properties. The expressiveness of computed properties allows you to deprecate existing events based on both a period of time and specific property values.

You may not have multiple backfills in a pending or pending_revert state with overlapping timeframes.

Parameters:

  • timeframe_end (Time) —

    The (exclusive) end of the usage timeframe affected by this backfill. By default

  • timeframe_start (Time) —

    The (inclusive) start of the usage timeframe affected by this backfill. By defau

  • close_time (Time, nil) —

    The time at which no more events will be accepted for this backfill. The backfil

  • customer_id (String, nil) —

    The Orb-generated ID of the customer to which this backfill is scoped. Omitting

  • deprecation_filter (String, nil) —

    A boolean [computed property](/extensibility/advanced-metrics#computed-propertie

  • external_customer_id (String, nil) —

    The external customer ID of the customer to which this backfill is scoped. Omitt

  • replace_existing_events (Boolean) —

    If true, replaces all existing events in the timeframe with the newly ingested e

  • request_options (Orb::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



75
76
77
78
79
80
81
82
83
84
 
# File 'lib/orb/resources/events/backfills.rb', line 75

def create(params)
  parsed, options = Orb::Events::BackfillCreateParams.dump_request(params)
  @client.request(
    method: :post,
    path: "events/backfills",
    body: parsed,
    model: Orb::Models::Events::BackfillCreateResponse,
    options: options
  )
end

#fetch(backfill_id, request_options: {}) ⇒ Orb::Models::Events::BackfillFetchResponse

This endpoint is used to fetch a backfill given an identifier.

Parameters:

Returns:

See Also:



152
153
154
155
156
157
158
159
 
# File 'lib/orb/resources/events/backfills.rb', line 152

def fetch(backfill_id, params = {})
  @client.request(
    method: :get,
    path: ["events/backfills/%1$s", backfill_id],
    model: Orb::Models::Events::BackfillFetchResponse,
    options: params[:request_options]
  )
end

#list(cursor: nil, limit: nil, request_options: {}) ⇒ Orb::Internal::Page<Orb::Models::Events::BackfillListResponse>

Some parameter documentations has been truncated, see Models::Events::BackfillListParams for more details.

This endpoint returns a list of all backfills in a list format.

The list of backfills is ordered starting from the most recently created backfill. The response also includes pagination_metadata, which lets the caller retrieve the next page of results if they exist.

Parameters:

  • cursor (String, nil) —

    Cursor for pagination. This can be populated by the next_cursor value returned

  • limit (Integer) —

    The number of items to fetch. Defaults to 20.

  • request_options (Orb::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



107
108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/orb/resources/events/backfills.rb', line 107

def list(params = {})
  parsed, options = Orb::Events::BackfillListParams.dump_request(params)
  query = Orb::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: "events/backfills",
    query: query,
    page: Orb::Internal::Page,
    model: Orb::Models::Events::BackfillListResponse,
    options: options
  )
end

#revert(backfill_id, request_options: {}) ⇒ Orb::Models::Events::BackfillRevertResponse

Reverting a backfill undoes all the effects of closing the backfill. If the backfill is reflected, the status will transition to pending_revert while the effects of the backfill are undone. Once all effects are undone, the backfill will transition to reverted.

If a backfill is reverted before its closed, no usage will be updated as a result of the backfill and it will immediately transition to reverted.

Parameters:

Returns:

See Also:



177
178
179
180
181
182
183
184
 
# File 'lib/orb/resources/events/backfills.rb', line 177

def revert(backfill_id, params = {})
  @client.request(
    method: :post,
    path: ["events/backfills/%1$s/revert", backfill_id],
    model: Orb::Models::Events::BackfillRevertResponse,
    options: params[:request_options]
  )
end