Module: Frodo::Concerns::API

Extended by:
Verbs
Included in:
AbstractClient
Defined in:
lib/frodo/concerns/api.rb

Instance Method Summary collapse

Methods included from Verbs

define_api_verb, define_verb, define_verbs

Instance Method Details

#count(query) ⇒ Object

Public: Count the entity set or for the query passed

entity_set or query - A String or a Frodo::Query. If String is passed,

all entities for the set are counted.



228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
 
# File 'lib/frodo/concerns/api.rb', line 228

def count(query)
  url_chunk = if query.is_a?(Frodo::Query)
                query.include_count
                query.to_s
              else
                service[query].query.count
              end

  body = api_get(url_chunk).body

  if query.is_a?(Frodo::Query)
    body['@odata.count']
  else
    # Some servers (*cough* Microsoft *cough*) seem to return
    # extraneous characters in the response.
    # I found out that the _\xef\xbb\xbf  contains probably invisible junk characters
    # called the Unicode BOM (short name for: byte order mark).
    body.scan(/\d+/).first.to_i
  end
end

#create(*args) ⇒ Object Also known as: insert

Public: Insert a new record.

entity_set - The set the entity belongs to attrs - Hash of attributes to set on the new record.

Examples

# Add a new lead
client.create('leads', {"firstname" =>'Bob'})
# => '073ca9c8-2a41-e911-a81d-000d3a1d5a0b'

Returns the primary key value of the newly created entity. Returns false if something bad happens.



87
88
89
90
91
 
# File 'lib/frodo/concerns/api.rb', line 87

def create(*args)
  create!(*args)
rescue *exceptions
  false
end

#create!(entity_set, attrs) ⇒ Object Also known as: insert!

Public: Insert a new record.

entity_set - The set the entity belongs to attrs - Hash of attributes to set on the new record.

Examples

# Add a new lead
client.create!('leads', {"firstname" =>'Bob'})
# => '073ca9c8-2a41-e911-a81d-000d3a1d5a0b'

Returns the primary key value of the newly created entity. Raises exceptions if an error is returned from Dynamics.



107
108
109
110
111
112
 
# File 'lib/frodo/concerns/api.rb', line 107

def create!(entity_set, attrs)
  entity = service[entity_set].new_entity(attrs)
  url_chunk = to_url_chunk(entity)
  url = api_post(url_chunk, attrs).headers['odata-entityid']
  id = url.match(/\(.+\)/)[0]
end

#destroy(*args) ⇒ Object

Public: Delete a record.

entity_set - The set the entity belongs to id - The Dynamics primary key ID of the record.

Examples

# Delete the lead with id  "073ca9c8-2a41-e911-a81d-000d3a1d5a0b"
client.destroy('leads',  "073ca9c8-2a41-e911-a81d-000d3a1d5a0b")

Returns true if the entity was successfully deleted. Returns false if an error is returned from Dynamics.



167
168
169
170
171
 
# File 'lib/frodo/concerns/api.rb', line 167

def destroy(*args)
  destroy!(*args)
rescue *exceptions
  false
end

#destroy!(entity_set, id) ⇒ Object

Public: Delete a record.

entity_set - The set the entity belongs to id - The Dynamics primary key ID of the record.

Examples

# Delete the lead with id  "073ca9c8-2a41-e911-a81d-000d3a1d5a0b"
client.destroy!('leads',  "073ca9c8-2a41-e911-a81d-000d3a1d5a0b")

Returns true of the entity was successfully deleted. Raises an exception if an error is returned from Dynamics.



185
186
187
188
189
190
 
# File 'lib/frodo/concerns/api.rb', line 185

def destroy!(entity_set, id)
  query = service[entity_set].query
  url_chunk = query.find(id).to_s
  api_delete url_chunk
  true
end

#find(entity_set, id) ⇒ Object

Public: Finds a single record and returns all fields.

entity_set - The set the entity belongs to id - The id of the record. If field is specified, id should be the id

of the external field.

Returns the Entity record.



199
200
201
202
203
204
205
 
# File 'lib/frodo/concerns/api.rb', line 199

def find(entity_set, id)
  query = service[entity_set].query
  url_chunk = query.find(id)

  body = api_get(url_chunk).body
  build_entity(entity_set, body)
end

#metadata ⇒ Object

Public: Return the metadata XML schema for the service

Returns [String]



39
40
41
 
# File 'lib/frodo/concerns/api.rb', line 39

def metadata
  api_get("$metadata").body
end

#query(query) ⇒ Object

Public: Execute a query and returns the result.

Query can be the url_chunk per the OData V4 spec or a Frodo::Query. The latter being preferred

Examples

# Find the names of all Accounts
client.query("leads?$filter=firstname eq 'yo'")

or

query = client.service['leads'].query
query.where("firstname eq 'yo'")
client.query(query)

Returns a list of Frodo::Entity



60
61
62
63
64
65
66
67
68
69
70
71
72
 
# File 'lib/frodo/concerns/api.rb', line 60

def query(query)
  url_chunk, entity_set = if query.is_a?(Frodo::Query)
                [query.to_s, query.entity_set.name]
              else
                [query]
              end

  body = api_get(url_chunk).body

  # if manual query as a string we detect the set on the response
  entity_set = body['@odata.context'].split('#')[-1] if entity_set.nil?
  build_entity(entity_set, body)
end

#select(entity_set, id, fields) ⇒ Object

Public: Finds a single record and returns select fields.

entity_set - The set the entity belongs to id - The id of the record. If field is specified, id should be the id

of the external field.

fields - A String array denoting the fields to select. If nil or empty array

is passed, all fields are selected.



214
215
216
217
218
219
220
221
222
 
# File 'lib/frodo/concerns/api.rb', line 214

def select(entity_set, id, fields)
  query = service[entity_set].query

  fields.each{|field| query.select(field)}
  url_chunk = query.find(id)

  body = api_get(url_chunk).body
  build_entity(entity_set, body)
end

#update(*args) ⇒ Object

Public: Update a record.

entity_set - The set the entity belongs to attrs - Hash of attributes to set on the record.

Examples

# Update the lead with id '073ca9c8-2a41-e911-a81d-000d3a1d5a0b'
client.update('leads', "leadid": '073ca9c8-2a41-e911-a81d-000d3a1d5a0b', Name: 'Whizbang Corp')

Returns true if the entity was successfully updated. Returns false if there was an error.



127
128
129
130
131
 
# File 'lib/frodo/concerns/api.rb', line 127

def update(*args)
  update!(*args)
rescue *exceptions
  false
end

#update!(entity_set, attrs) ⇒ Object

Public: Update a record.

entity_set - The set the entity belongs to attrs - Hash of attributes to set on the record.

Examples

# Update the leads with id '073ca9c8-2a41-e911-a81d-000d3a1d5a0b'
client.update!('leads', 'leadid' => '073ca9c8-2a41-e911-a81d-000d3a1d5a0b', "firstname" => 'Whizbang Corp')

Returns true if the entity was successfully updated. Raises an exception if an error is returned from Dynamics.

Raises:

  • (ArgumentError) 


145
146
147
148
149
150
151
152
153
 
# File 'lib/frodo/concerns/api.rb', line 145

def update!(entity_set, attrs)
  entity = service[entity_set].new_entity(attrs)
  url_chunk = to_url_chunk(entity)

  raise ArgumentError, 'ID field missing from provided attributes' if entity.is_new?

  api_patch url_chunk, attrs
  true
end