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.



238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
 
# File 'lib/frodo/concerns/api.rb', line 238

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.



91
92
93
94
95
 
# File 'lib/frodo/concerns/api.rb', line 91

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

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

Public: Insert a new record.

entity_set_name - 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.



111
112
113
114
115
116
117
118
119
120
 
# File 'lib/frodo/concerns/api.rb', line 111

def create!(entity_set_name, attrs)
  entity_set = service[entity_set_name]
  url_chunk = entity_set_to_url_chunk(entity_set)
  url = api_post(url_chunk, attrs).headers['odata-entityid']
  id_match = url.match(/\((.+)\)/)
  if id_match.nil?
    raise Frodo::Error.new "entity url not in expected format: #{url.inspect}"
  end
  return id_match[1]
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.



177
178
179
180
181
 
# File 'lib/frodo/concerns/api.rb', line 177

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.



195
196
197
198
199
200
 
# File 'lib/frodo/concerns/api.rb', line 195

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.



209
210
211
212
213
214
215
 
# File 'lib/frodo/concerns/api.rb', line 209

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]



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

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

#metadata_on_init ⇒ Object 



42
43
44
45
 
# File 'lib/frodo/concerns/api.rb', line 42

def metadata_on_init
  # Creating Metadata using a different client than the one that is stored
  Frodo::Client.new(@options).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



64
65
66
67
68
69
70
71
72
73
74
75
76
 
# File 'lib/frodo/concerns/api.rb', line 64

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.



224
225
226
227
228
229
230
231
232
 
# File 'lib/frodo/concerns/api.rb', line 224

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.



135
136
137
138
139
 
# File 'lib/frodo/concerns/api.rb', line 135

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

#update!(entity_set, attrs, additional_headers = {}) ⇒ 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) 


153
154
155
156
157
158
159
160
161
162
163
 
# File 'lib/frodo/concerns/api.rb', line 153

def update!(entity_set, attrs, additional_headers={})
  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 do |req|
    req.headers.merge!(additional_headers)
  end
  true
end