Class: Ecoportal::API::V1::People

Inherits:
Object
  • Object
show all
Extended by:
Common::BaseClass
Includes:
Common::DocHelpers, Enumerable
Defined in:
lib/ecoportal/api/v1/people.rb

Direct Known Subclasses

Internal::People

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Common::BaseClass

class_resolver, redef_without_warning, resolve_class

Methods included from Common::DocHelpers

#get_body, #get_id

Constructor Details

#initialize(client) ⇒ People

Returns an instance object ready to make people api requests.

Parameters:

  • client (Common::Client) —

    a Common::Client object that holds the configuration of the api connection.



17
18
19
 
# File 'lib/ecoportal/api/v1/people.rb', line 17

def initialize(client)
  @client = client
end

Instance Attribute Details

#client ⇒ Common::Client (readonly)

a Common::Client object that holds the configuration of the api connection.

Returns:



6
7
8
 
# File 'lib/ecoportal/api/v1/people.rb', line 6

def client
  @client
end

Instance Method Details

#batch(job_mode: true) {|batch_op| ... } ⇒ Ecoportal::API::Common::Response

Creates a BatchOperation and yields it to the given bock.

Parameters:

  • job_mode (Boolean) (defaults to: true) —

    whether or not it should use batch jobs

Yields:

  • (batch_op) —

    adds multiple api requests for the current batch.

Yield Parameters:

  • batch_op (BatchOperation)

Returns:



144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
 
# File 'lib/ecoportal/api/v1/people.rb', line 144

def batch(job_mode: true, &block)
  return job.batch(&block) if job_mode

  operation = Common::BatchOperation.new(
    '/people',
    person_class,
    logger: client.logger
  )

  yield operation

  # The batch operation is responsible for logging the output
  client.post('/people/batch', data: operation.as_json).tap do |response|
    operation.process_response(response)
  end
end

#create(doc) ⇒ Response

Requests to create a person via api.

Parameters:

  • doc (Person, Hash) —

    data that at least contains an id (internal or external) of the target person.

Returns:

  • (Response) —

    an object with the api response.



116
117
118
119
120
 
# File 'lib/ecoportal/api/v1/people.rb', line 116

def create(doc)
  body = get_body(doc)

  client.post('/people', data: body)
end

#delete(doc) ⇒ Response

Requests to completelly remove from an organization an existing person via api.

Parameters:

  • doc (Person, Hash) —

    data that at least contains an id (internal or external) of the target person.

Returns:

  • (Response) —

    an object with the api response.



134
135
136
137
 
# File 'lib/ecoportal/api/v1/people.rb', line 134

def delete(doc)
  id = get_id(doc)
  client.delete("/people/#{CGI.escape(id)}")
end

#each(params: {}, silent: false) {|person| ... } ⇒ Object

Note:
  • it ignores the key cursor_id: of params:.
  • each is called by to_a

Iterates all the people of the organization.

Parameters:

  • params (Hash) (defaults to: {})
  • silent (Boolean) (defaults to: false) —

    false to show percentage of progress.

Options Hash (params:):

  • :per_page (String) —

    the number of people you get per request.

  • :q (String) —

    some text to search. Omit this parameter to target all the people.

Yields:

  • (person) —

    does some stuff with the person.

Yield Parameters:



31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/ecoportal/api/v1/people.rb', line 31

def each(params: {}, silent: false) # rubocop:disable Metrics/AbcSize
  return to_enum(:each, params: params, silent: silent) unless block_given?

  cursor_id = nil
  results   = 0

  puts "\n" unless silent

  loop do
    params.update(cursor_id: cursor_id) if cursor_id

    body     = nil
    response = nil
    count    = 5

    loop do
      response = client.get('/people', params: params)
      body     = response && body_data(response.body)
      break if response.success? || count <= 0

      puts "Request failed - Status #{response.status}: #{body}"
      count -= 1

      sleep(0.5)
    end

    raise "Request failed - Status #{response.status}: #{body}" unless response.success?

    unless silent || (total = body['total_results'])&.zero?
      results += body['results'].length
      percent  = results * 100 / total

      msg      = 'People GET'
      msg     << " (search=#{params[:q]})" if params.key?(:q)

      print "#{msg}: #{percent.round}% (of #{total}): #{results}\r"
      $stdout.flush
    end

    body['results'].each do |person|
      yield person_class.new(person)
    end

    break unless (cursor_id = body['cursor_id'])
  end
  self
end

#get(doc) ⇒ Person

Note:

if the request has success? the returned object.result gives an object with that Person.

Gets a person via api.

Parameters:

  • doc (String, Hash, Person) —

    data containing an id (internal or external) of the target person.

Returns:

  • (Person) —

    the person with id (internal or external) contained in doc.



94
95
96
97
98
99
100
101
 
# File 'lib/ecoportal/api/v1/people.rb', line 94

def get(doc)
  id       = get_id(doc)
  response = client.get("/people/#{CGI.escape(id)}")
  body     = body_data(response.body)
  return person_class.new(body) if response.success?

  raise "Could not get person #{id} - Error #{response.status}: #{body}"
end

#get_all(params: {}, silent: false) ⇒ Array<Person>

Note:

it ignores the key :cursor_id in params:.

Gets all the people via api requests.

Parameters:

  • params (Hash) (defaults to: {})
  • silent (Boolean) (defaults to: false) —

    false to show percentage of progress.

Options Hash (params:):

  • :per_page (Integer) —

    the number of people you get per request.

  • :q (String) —

    some text to search.

Returns:

  • (Array<Person>) —

    the array of people got via api.



86
87
88
 
# File 'lib/ecoportal/api/v1/people.rb', line 86

def get_all(params: {}, silent: false)
  each(params: params, silent: silent).to_a
end

#job(preserve_stats: true) ⇒ Ecoportal::API::V1::Job

Returns:



162
163
164
165
166
 
# File 'lib/ecoportal/api/v1/people.rb', line 162

def job(preserve_stats: true)
  return @last_job = Job.new(client, person_class: person_class) unless preserve_stats && @last_job

  @last_job = @last_job.new
end

#new ⇒ Person

Creates a new Person object.

Returns:

  • (Person) —

    new empty person object of the current version.



170
171
172
 
# File 'lib/ecoportal/api/v1/people.rb', line 170

def new
  person_class.new
end

#update(doc) ⇒ Response

Requests an update of a person via api.

Parameters:

  • doc (Person, Hash) —

    data that at least contains an id (internal or external) of the target person.

Returns:

  • (Response) —

    an object with the api response.



106
107
108
109
110
111
 
# File 'lib/ecoportal/api/v1/people.rb', line 106

def update(doc)
  body = get_body(doc)
  id   = get_id(doc)

  client.patch("/people/#{CGI.escape(id)}", data: body)
end

#upsert(doc) ⇒ Response

Requests to update an existing person or if it does not exist, to create it, via api.

Parameters:

  • doc (Person, Hash) —

    data that at least contains an id (internal or external) of the target person.

Returns:

  • (Response) —

    an object with the api response.



125
126
127
128
129
 
# File 'lib/ecoportal/api/v1/people.rb', line 125

def upsert(doc)
  body = get_body(doc)
  id   = get_id(doc)
  client.post("/people/#{CGI.escape(id)}", data: body)
end