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.



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

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
 
# File 'lib/frodo/concerns/api.rb', line 111

def create!(entity_set_name, attrs)
  url = api_post(entity_set_name, 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.



174
175
176
177
178
 
# File 'lib/frodo/concerns/api.rb', line 174

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.



192
193
194
195
196
197
 
# File 'lib/frodo/concerns/api.rb', line 192

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.



206
207
208
209
210
211
212
 
# File 'lib/frodo/concerns/api.rb', line 206

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 if @options[:with_metadata]
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.



221
222
223
224
225
226
227
228
229
 
# File 'lib/frodo/concerns/api.rb', line 221

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.



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

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

#update!(entity_set_name, primary_key, 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) 


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

def update!(entity_set_name, primary_key, attrs, additional_headers={})
  raise ArgumentError, 'ID field missing from provided attributes' unless attrs.has_key?(primary_key)

  url_chunk = "#{entity_set_name}(#{attrs[primary_key]})"
  api_patch url_chunk, attrs do |req|
    req.headers.merge!(additional_headers)
  end
  true
end