Class: BrightData::Snapshot

Inherits:
Object
  • Object
show all
Defined in:
lib/brightdata/snapshot.rb

Overview

Represents a Bright Data Dataset job returned by every ‘.trigger` call.

Examples:

Wait for results

snapshot = client.linkedin.profiles.trigger(urls: ["https://www.linkedin.com/in/example/"])
result = snapshot.wait
result.success? # => true

Constant Summary collapse

STATUSES =

Returns statuses recognized by Bright Data snapshot progress.

Returns:

  • (Array<Symbol>) —

    statuses recognized by Bright Data snapshot progress

%i[starting running ready failed].freeze
TRIGGER_RESPONSE_KEY =

Returns trigger response key containing the snapshot ID.

Returns:

  • (Symbol) —

    trigger response key containing the snapshot ID

:snapshot_id
PROGRESS_PATH_TEMPLATE =

Returns progress endpoint template.

Returns:

  • (String) —

    progress endpoint template

"/datasets/v3/progress/%s"
RESULTS_PATH_TEMPLATE =

Returns results endpoint template.

Returns:

  • (String) —

    results endpoint template

"/datasets/v3/snapshot/%s"
DEFAULT_TIMEOUT =

Returns default wait timeout in seconds.

Returns:

  • (Integer) —

    default wait timeout in seconds

300
DEFAULT_POLL_INTERVAL =

Returns default poll interval in seconds.

Returns:

  • (Integer) —

    default poll interval in seconds

5

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(id:, http:, result_parser: ->(raw) { raw }) ⇒ Snapshot

Returns a new instance of Snapshot.

Parameters:

  • id (String) —

    snapshot ID from ‘/datasets/v3/trigger`

  • http (BrightData::HTTP) —

    HTTP wrapper

  • result_parser (#call) (defaults to: ->(raw) { raw }) —

    callable mapping raw result arrays to typed results



38
39
40
41
42
43
 
# File 'lib/brightdata/snapshot.rb', line 38

def initialize(id:, http:, result_parser: ->(raw) { raw })
  @id = id
  @http = http
  @result_parser = result_parser
  @status = :starting
end

Instance Attribute Details

#id ⇒ String (readonly)

Returns snapshot ID.

Returns:

  • (String) —

    snapshot ID



30
31
32
 
# File 'lib/brightdata/snapshot.rb', line 30

def id
  @id
end

#status ⇒ Symbol (readonly)

Returns latest known status.

Returns:

  • (Symbol) —

    latest known status



33
34
35
 
# File 'lib/brightdata/snapshot.rb', line 33

def status
  @status
end

Instance Method Details

#failed? ⇒ Boolean

Returns true when the latest status is failed.

Returns:

  • (Boolean) —

    true when the latest status is failed



62
 
# File 'lib/brightdata/snapshot.rb', line 62

def failed? = @status == :failed

#progress ⇒ Symbol

Poll progress once.

Returns:

  • (Symbol) —

    current snapshot status

Raises:



49
50
51
52
53
54
55
56
 
# File 'lib/brightdata/snapshot.rb', line 49

def progress
  @last_progress = @http.get(path: format(PROGRESS_PATH_TEMPLATE, @id))
  raw = @last_progress.fetch(:status)
  sym = raw.to_sym
  raise Error, "Unknown snapshot status from API: #{raw.inspect}" unless STATUSES.include?(sym)

  @status = sym
end

#ready? ⇒ Boolean

Returns true when the latest status is ready.

Returns:

  • (Boolean) —

    true when the latest status is ready



59
 
# File 'lib/brightdata/snapshot.rb', line 59

def ready? = @status == :ready

#results ⇒ Array

Fetch raw snapshot results.

Returns:

  • (Array) —

    raw JSON result array



82
83
84
 
# File 'lib/brightdata/snapshot.rb', line 82

def results
  @http.get(path: format(RESULTS_PATH_TEMPLATE, @id), query: { format: "json" })
end

#wait(timeout: DEFAULT_TIMEOUT, poll_interval: DEFAULT_POLL_INTERVAL) ⇒ SimpleResult::Success, SimpleResult::Failure

Block until the snapshot reaches a terminal status or timeout elapses.

Parameters:

  • timeout (Numeric) (defaults to: DEFAULT_TIMEOUT) —

    seconds to wait before raising

  • poll_interval (Numeric) (defaults to: DEFAULT_POLL_INTERVAL) —

    seconds between progress polls

Returns:

  • (SimpleResult::Success) —

    success result containing parsed results

  • (SimpleResult::Failure) —

    failure result containing the progress payload

Raises:



71
72
73
74
75
76
77
 
# File 'lib/brightdata/snapshot.rb', line 71

def wait(timeout: DEFAULT_TIMEOUT, poll_interval: DEFAULT_POLL_INTERVAL)
  deadline = monotonic_now + timeout
  loop do
    result = poll_once(timeout:, deadline:, poll_interval:)
    return result if result
  end
end