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

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

Direct Known Subclasses

Internal::People

Constant Summary collapse

DELAY_STATUS_CHECK = 
5

Constants included from Common::Client::TimeOut

Common::Client::TimeOut::MIN_SIZE, Common::Client::TimeOut::MIN_THROUGHPUT

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.



20
21
22
 
# File 'lib/ecoportal/api/v1/people.rb', line 20

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:



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

def batch(job_mode: true, &block)
  return job(&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.



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

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.



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

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:



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
78
79
80
 
# File 'lib/ecoportal/api/v1/people.rb', line 34

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.



97
98
99
100
101
102
103
104
 
# File 'lib/ecoportal/api/v1/people.rb', line 97

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.



89
90
91
 
# File 'lib/ecoportal/api/v1/people.rb', line 89

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

#job {|operation| ... } ⇒ Ecoportal::API::Common::Response

Returns the results of the batch job.

Yields:

  • (operation)

Returns:



163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
 
# File 'lib/ecoportal/api/v1/people.rb', line 163

def job
  operation = Common::BatchOperation.new(
    "/people",
    person_class,
    logger: client.logger
  )

  yield operation

  total   = operation.count
  timeout = timeout_for(total)

  job_id  = create_job(operation)
  status  = wait_for_job_completion(job_id, timeout: timeout, total: total)

  # @todo
  # if total == status.progress
  if status&.complete?(total)
    job_result(job_id, operation)
  else
    msg  = "Job '#{job_id}' not complete (size: #{total}).\n"
    msg << "  Probably timeout after #{timeout} seconds.\n"
    msg << "  Current status: #{status}"

    raise API::Errors::TimeOut, msg
  end
end

#new ⇒ Person

Creates a new Person object.

Returns:

  • (Person) —

    new empty person object of the current version.



193
194
195
 
# File 'lib/ecoportal/api/v1/people.rb', line 193

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.



109
110
111
112
113
 
# File 'lib/ecoportal/api/v1/people.rb', line 109

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.



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

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