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

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

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:



183
184
185
 
# File 'lib/orb/resources/events/backfills.rb', line 183

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:



127
128
129
130
131
132
133
134
 
# File 'lib/orb/resources/events/backfills.rb', line 127

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](ingest) usage events, referencing the backfill (query parameter ‘backfill_id`).

  3. [Close](close-backfill) 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 `filter` can be optionally added which enables filtering using [computed properties](/extensibility/advanced-metrics#computed-properties). The expressiveness of computed properties allows you to deprecate existing events based on both a period of time and specific property values.

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:



69
70
71
72
73
74
75
76
77
78
 
# File 'lib/orb/resources/events/backfills.rb', line 69

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:



146
147
148
149
150
151
152
153
 
# File 'lib/orb/resources/events/backfills.rb', line 146

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`](/api-reference/pagination), which lets the caller retrieve the next page of results if they exist. More information about pagination can be found in the [Pagination-metadata schema](pagination).

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:



102
103
104
105
106
107
108
109
110
111
112
 
# File 'lib/orb/resources/events/backfills.rb', line 102

def list(params = {})
  parsed, options = Orb::Events::BackfillListParams.dump_request(params)
  @client.request(
    method: :get,
    path: "events/backfills",
    query: parsed,
    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:



171
172
173
174
175
176
177
178
 
# File 'lib/orb/resources/events/backfills.rb', line 171

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