m2x 2.7.0 → 2.8.0

Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: 6f99957f1081641ba2aa36bcb42ba14d060f870f
4
- data.tar.gz: 12a42074fdd8c1508bde7f1873efb9afeade3d64
3
+ metadata.gz: 2ea07ea414cc4c26575f1aca0d20265043bb9b64
4
+ data.tar.gz: 978b08f9a138f519a2a319c870a1fb9dc4cb52a9
5
5
  SHA512:
6
- metadata.gz: 4cd1e7dfc0385584032cf6380a8af2499b3fb14c245c1f978eba890afe0bf68360fefd7005194bb3d23d638fee1b02a417b4c18da2b13587eb3387b91185fd91
7
- data.tar.gz: fa53b1cd4087a9379ac136e07ab49c721584afc7d287b6d36d4941b6feb51dac0549f9c8241b6f8abbfed8504964ee5a87277ebe8b424c39a85bc0ba4a9379b3
6
+ metadata.gz: 42d87fd2aeb30f4a33e71940e5afe5c3955d77c9c0af7f7c5697fac4ac97f797aeaf6577b845399caf83c9aa7cadbad7b0c76ea984db771de080d2ef7f97986d
7
+ data.tar.gz: ff4e72e6ff9f442e8a5ab981636d45aa106eb278790e8d764e97c801e2bb82208549486800489035b06a719c85c8e035da973d4080aa6daedf6dac0f5b91650a
data/README.md CHANGED
@@ -60,6 +60,13 @@ This provides an interface to your data in M2X
60
60
  job = m2x.job("<JOB-ID>")
61
61
  ```
62
62
 
63
+ - [Integration](lib/m2x/integration.rb)
64
+ ```ruby
65
+ integration = m2x.integration("<INTEGRATION-ID>")
66
+
67
+ integrations = m2x.integrations
68
+ ```
69
+
63
70
  Refer to the documentation on each class for further usage instructions.
64
71
 
65
72
  ## Time
@@ -80,79 +87,19 @@ m2x.time_iso8601
80
87
  => "2015-07-04T00:40:37.504Z"
81
88
  ```
82
89
 
83
- ## Example
90
+ ## Examples
84
91
 
85
- In order to run this example, you will need a `Device ID` and `API Key`. If you don't have any, access your M2X account, create a new [Device](https://m2x.att.com/devices), and copy the `Device ID` and `API Key` values. The following script will send your CPU load average to three different streams named `load_1m`, `load_5m` and `load_15`. Check that there's no need to create a stream in order to write values into it.
92
+ Scripts demonstrating usage of the M2X Ruby Client Library can be found in the [examples](/examples) directory. Each example leverages system environment variables to inject user specific information such as the M2X `API Key` or `Device ID`. Review the example you would like to try first to determine which environment variables are required (hint: search for `ENV.fetch` in the example). Then make sure to set the required environment variable(s) when running the script.
86
93
 
87
- In order to execute this script, run:
94
+ For example, in order to run the [m2x-uptime](/examples/m2x-uptime.rb) script, you will need a `Device ID` and `API Key`. If you have yet to create an M2X Device, access your M2X account, create a new [Device](https://m2x.att.com/devices), and copy the `Device ID` and `API Key` values. The script will send your CPU load average to three different streams named `load_1m`, `load_5m` and `load_15`. In order to execute this script, run:
88
95
 
89
96
  ```bash
90
- API_KEY=<YOUR-API-KEY> DEVICE=<YOUR-DEVICE-ID> ./m2x-uptime.rb
97
+ $ API_KEY=<YOUR-API-KEY> DEVICE=<YOUR-DEVICE-ID> ruby ./m2x-uptime.rb
91
98
  ```
92
99
 
93
- ```ruby
94
- #! /usr/bin/env ruby
95
-
96
- #
97
- # See https://github.com/attm2x/m2x-ruby#example for instructions
98
- #
99
-
100
- require "time"
101
- require "m2x"
102
-
103
- API_KEY = ENV.fetch("API_KEY")
104
- DEVICE = ENV.fetch("DEVICE")
105
-
106
- puts "M2X::Client/#{M2X::Client::VERSION} example"
107
-
108
- @run = true
109
-
110
- stop = Proc.new { @run = false }
111
-
112
- trap(:INT, &stop)
113
- trap(:TERM, &stop)
114
-
115
- # Match `uptime` load averages output for both Linux and OSX
116
- UPTIME_RE = /(\d+\.\d+),? (\d+\.\d+),? (\d+\.\d+)$/
117
-
118
- def load_avg
119
- `uptime`.match(UPTIME_RE).captures
120
- end
121
-
122
- m2x = M2X::Client.new(API_KEY)
123
-
124
- # Get the device
125
- device = m2x.device(DEVICE)
126
-
127
- # Create the streams if they don't exist
128
- device.create_stream("load_1m")
129
- device.create_stream("load_5m")
130
- device.create_stream("load_15m")
131
-
132
- while @run
133
- load_1m, load_5m, load_15m = load_avg
134
-
135
- # Write the different values into AT&T M2X
136
- now = Time.now.iso8601
137
-
138
- values = {
139
- load_1m: [ { value: load_1m, timestamp: now } ],
140
- load_5m: [ { value: load_5m, timestamp: now } ],
141
- load_15m: [ { value: load_15m, timestamp: now } ]
142
- }
143
-
144
- res = device.post_updates(values: values)
145
-
146
- abort res.json["message"] unless res.success?
147
-
148
- sleep 1
149
- end
150
-
151
- puts
152
-
153
- ```
100
+ ## Tutorials
154
101
 
155
- You can find this script in [`examples/m2x-uptime.rb`](examples/m2x-uptime.rb).
102
+ Please refer to the [M2X Ruby Client Tutorials](TUTORIAL.md) for additional hands on examples.
156
103
 
157
104
  ## Versioning
158
105
 
data/lib/m2x.rb CHANGED
@@ -8,6 +8,7 @@ require_relative "m2x/collection"
8
8
  require_relative "m2x/command"
9
9
  require_relative "m2x/device"
10
10
  require_relative "m2x/distribution"
11
+ require_relative "m2x/integration"
11
12
  require_relative "m2x/job"
12
13
  require_relative "m2x/key"
13
14
  require_relative "m2x/stream"
@@ -9,7 +9,6 @@ require "openssl"
9
9
  #
10
10
  # m2x = M2X::Client.new("<YOUR-API-KEY>")
11
11
  # m2x.get("/some_path")
12
- #
13
12
  class M2X::Client
14
13
  DEFAULT_API_BASE = "https://api-m2x.att.com".freeze
15
14
  DEFAULT_API_VERSION = "v2".freeze
@@ -33,6 +32,8 @@ class M2X::Client
33
32
  #
34
33
  # The response to this endpoint is an object in which each of its attributes
35
34
  # represents an M2X subsystem and its current status.
35
+ #
36
+ # @return {Response} the API Status
36
37
  def status
37
38
  get("/status")
38
39
  end
@@ -46,20 +47,22 @@ class M2X::Client
46
47
  end
47
48
 
48
49
  # Creates a new collection on M2X with the specified parameters
50
+ #
51
+ # See {M2X::Client::Collection.create!} for more details
49
52
  def create_collection(params)
50
53
  M2X::Client::Collection.create!(self, params)
51
54
  end
52
55
 
53
56
  # Retrieve the list of collections accessible by the authenticated API key
54
57
  #
55
- # See M2X::Client::Collection.list for more details
58
+ # See {M2X::Client::Collection.list} for more details
56
59
  def collections(params={})
57
60
  M2X::Client::Collection.list(self, params)
58
61
  end
59
62
 
60
63
  # List Sent Commands
61
64
  #
62
- # See M2X::Client::Command.list for more details
65
+ # See {M2X::Client::Command.list} for more details
63
66
  def commands(params={})
64
67
  M2X::Client::Command.list(self, params)
65
68
  end
@@ -73,6 +76,8 @@ class M2X::Client
73
76
  end
74
77
 
75
78
  # Send command
79
+ #
80
+ # See {M2X::Client::Command.send!} for more details
76
81
  def send_command(params)
77
82
  M2X::Client::Command.send!(self, params)
78
83
  end
@@ -86,13 +91,15 @@ class M2X::Client
86
91
  end
87
92
 
88
93
  # Creates a new device on M2X with the specified parameters
94
+ #
95
+ # See {M2X::Client::Device.create!} for more details
89
96
  def create_device(params)
90
97
  M2X::Client::Device.create!(self, params)
91
98
  end
92
99
 
93
100
  # Retrieve the list of devices accessible by the authenticated API key
94
101
  #
95
- # See M2X::Client::Device.list for more details
102
+ # See {M2X::Client::Device.list} for more details
96
103
  def devices(params={})
97
104
  M2X::Client::Device.list(self, params)
98
105
  end
@@ -100,7 +107,7 @@ class M2X::Client
100
107
  # Retrieve the list of devices accessible by the authenticated API key that
101
108
  # meet the search criteria.
102
109
  #
103
- # See M2X::Client::Device.search for more details
110
+ # See {M2X::Client::Device.search} for more details
104
111
  def search_devices(params={})
105
112
  M2X::Client::Device.list(self, params)
106
113
  end
@@ -112,7 +119,7 @@ class M2X::Client
112
119
  # locations, streams list, and view each Devices' stream metadata and its
113
120
  # values.
114
121
  #
115
- # See M2X::Client::Device.catalog for more details
122
+ # See {M2X::Client::Device.catalog} for more details
116
123
  def device_catalog(params={})
117
124
  M2X::Client::Device.catalog(self, params)
118
125
  end
@@ -127,6 +134,8 @@ class M2X::Client
127
134
  end
128
135
 
129
136
  # Creates a new device distribution on M2X with the specified parameters
137
+ #
138
+ # See {M2X::Client::Distribution.create!} for more details.
130
139
  def create_distribution(params)
131
140
  M2X::Client::Distribution.create!(self, params)
132
141
  end
@@ -134,7 +143,7 @@ class M2X::Client
134
143
  # Retrieve list of device distributions accessible by the authenticated
135
144
  # API key.
136
145
  #
137
- # See M2X::Client::Distribution.list for more details
146
+ # See {M2X::Client::Distribution.list} for more details
138
147
  def distributions(params={})
139
148
  M2X::Client::Distribution.list(self, params)
140
149
  end
@@ -161,30 +170,65 @@ class M2X::Client
161
170
  # Note that, according to the parameters sent, you can create a
162
171
  # Master API Key or a Device/Stream API Key.
163
172
  #
164
- # See M2X::Client::Key.create! for more details
173
+ # See {M2X::Client::Key.create!} for more details
165
174
  def create_key(params)
166
175
  M2X::Client::Key.create!(self, params)
167
176
  end
168
177
 
169
178
  # Retrieve list of keys associated with the user account.
170
179
  #
171
- # See M2X::Client::Key.list for more details
180
+ # See {M2X::Client::Key.list} for more details
172
181
  def keys
173
182
  M2X::Client::Key.list(self)
174
183
  end
175
184
 
185
+ # Obtain an Integration from M2X
186
+ #
187
+ # This method instantiates an instance of Integration and calls
188
+ # `Integration#view` method, returning the integration instance with all its
189
+ # attributes initialized
190
+ def integration(id)
191
+ M2X::Client::Integration.new(self, "id" => id).tap(&:view)
192
+ end
193
+
194
+ # Creates a new integration on M2X with the specified parameters
195
+ #
196
+ # See {M2X::Client::Integration.create!} for more details
197
+ def create_integration(params)
198
+ M2X::Client::Integration.create!(self, params)
199
+ end
200
+
201
+ # Retrieve list of integrations associated with the user account.
202
+ #
203
+ # See {M2X::Client::Integration.list} for more details
204
+ def integrations
205
+ M2X::Client::Integration.list(self)
206
+ end
207
+
208
+ # Method for {https://m2x.att.com/developer/documentation/v2/time Time} API
209
+ #
210
+ # @return (Response) text/plain response of the server time in all three formats
176
211
  def time
177
212
  get("/time").json
178
213
  end
179
214
 
215
+ # Method for {https://m2x.att.com/developer/documentation/v2/time Time} API
216
+ #
217
+ # @return (Response) text/plain response of the server time in seconds
180
218
  def time_seconds
181
219
  get("/time/seconds").raw
182
220
  end
183
221
 
222
+ # Method for {https://m2x.att.com/developer/documentation/v2/time Time} API
223
+ #
224
+ # @return (Response) text/plain response of the server time in millis
184
225
  def time_millis
185
226
  get("/time/millis").raw
186
227
  end
187
228
 
229
+ # Method for {https://m2x.att.com/developer/documentation/v2/time Time} API
230
+ #
231
+ # @return (Response) text/plain response of the server time in ISO 8601 Format
188
232
  def time_iso8601
189
233
  get("/time/iso8601").raw
190
234
  end
@@ -1,26 +1,33 @@
1
1
  require_relative "./resource"
2
2
  require_relative "./metadata"
3
3
 
4
- # Wrapper for AT&T M2X Collections API
5
- # https://m2x.att.com/developer/documentation/v2/collections
4
+ # Wrapper for {https://m2x.att.com/developer/documentation/v2/collections M2X Collections} API
6
5
  class M2X::Client::Collection < M2X::Client::Resource
7
6
  include M2X::Client::Metadata
8
7
 
9
8
  PATH = "/collections"
10
9
 
11
10
  class << self
12
- # Retrieve the list of collections accessible by the authenticated API key
13
11
  #
14
- # https://m2x.att.com/developer/documentation/v2/collections#List-collections
12
+ # Method for {https://m2x.att.com/developer/documentation/v2/collections#List-collections List Collections} endpoint.
13
+ #
14
+ # @param {Client} client Client API
15
+ # @param params Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
16
+ # @return (Array) List of {Collection} objects
17
+ #
15
18
  def list(client, params={})
16
19
  res = client.get(PATH, params)
17
20
 
18
21
  res.json["collections"].map{ |atts| new(client, atts) } if res.success?
19
22
  end
20
23
 
21
- # Create a new collection
22
24
  #
23
- # https://m2x.att.com/developer/documentation/v2/collections#Create-Collection
25
+ # Method for {https://m2x.att.com/developer/documentation/v2/collections#Create-Collection Create Collection} endpoint.
26
+ #
27
+ # @param {Client} client Client API
28
+ # @param params Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
29
+ # @return {Collection} The newly created Collection.
30
+ #
24
31
  def create!(client, params)
25
32
  res = client.post(PATH, nil, params, "Content-Type" => "application/json")
26
33
 
@@ -33,22 +40,33 @@ class M2X::Client::Collection < M2X::Client::Resource
33
40
  @path ||= "#{ PATH }/#{ URI.encode(@attributes.fetch("id")) }"
34
41
  end
35
42
 
43
+ #
44
+ # Method for {https://m2x.att.com/developer/documentation/v2/collections#List-Devices-from-an-existing-Collection List Devices from an existing collection} endpoint.
45
+ #
46
+ # @return (Array) List of Device objects
47
+ #
36
48
  def devices
37
49
  res = @client.get("#{path}/devices")
38
50
 
39
51
  res.json["devices"].map{ |atts| M2X::Client::Device.new(@client, atts) } if res.success?
40
52
  end
41
53
 
42
- # Add device to collection
43
54
  #
44
- # https://m2x.att.com/developer/documentation/v2/collections#Add-device-to-collection
55
+ # Method for {https://m2x.att.com/developer/documentation/v2/collections#Add-device-to-collection Add a device to the collection} endpoint.
56
+ #
57
+ # @param (String) device_id ID of the Device being added to Collection
58
+ # @return {Response} The API response, see M2X API docs for details
59
+ #
45
60
  def add_device(device_id)
46
61
  @client.put("#{ path }/devices/#{ device_id }")
47
62
  end
48
63
 
49
- # Remove device from collection
50
64
  #
51
- # https://m2x.att.com/developer/documentation/v2/collections#Remove-device-from-collection
65
+ # Method for {https://m2x.att.com/developer/documentation/v2/collections#Remove-device-from-collection Remove a device from the collection} endpoint.
66
+ #
67
+ # @param (String) device_id ID of the Device being removed from Collection
68
+ # @return {Response} The API response, see M2X API docs for details
69
+ #
52
70
  def remove_device(device_id)
53
71
  @client.delete("#{ path }/devices/#{ device_id }")
54
72
  end
@@ -1,5 +1,4 @@
1
- # Wrapper for AT&T M2X Commands API
2
- # https://m2x.att.com/developer/documentation/v2/commands
1
+ # Wrapper for {https://m2x.att.com/developer/documentation/v2/commands M2X Commands} API
3
2
  class M2X::Client::Command
4
3
  extend Forwardable
5
4
 
@@ -18,12 +17,13 @@ class M2X::Client::Command
18
17
  @path ||= "#{ PATH }/#{ URI.encode(@attributes.fetch("id")) }"
19
18
  end
20
19
 
21
- # View Command Details
22
20
  #
21
+ # Method for {https://m2x.att.com/developer/documentation/v2/commands#View-Command-Details View Command Details} endpoint.
23
22
  # Get details of a sent command including the delivery information for all
24
23
  # devices that were targetted by the command at the time it was sent.
25
24
  #
26
- # https://m2x.att.com/developer/documentation/v2/commands#View-Command-Details
25
+ # @return {Command} The retrieved Command
26
+ #
27
27
  def view
28
28
  res = @client.get(path)
29
29
 
@@ -35,25 +35,31 @@ class M2X::Client::Command
35
35
  end
36
36
 
37
37
  class << self
38
- # List Sent Commands
39
38
  #
39
+ # Method for {https://m2x.att.com/developer/documentation/v2/commands#List-Sent-Commands List Sent Commands} endpoint.
40
40
  # Retrieve the list of recent commands sent by the current user
41
41
  # (as given by the API key).
42
42
  #
43
- # https://m2x.att.com/developer/documentation/v2/commands#List-Sent-Commands
43
+ # @param {Client} client Client API
44
+ # @param params Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
45
+ # @return (Array) List of {Command} objects
46
+ #
44
47
  def list(client, params={})
45
48
  res = client.get(PATH, params)
46
49
 
47
50
  res.json["commands"].map { |atts| new(client, atts) } if res.success?
48
51
  end
49
52
 
50
- # Send Command
51
53
  #
54
+ # Method for {https://m2x.att.com/developer/documentation/v2/commands#Send-Command Send Command} endpoint.
52
55
  # Send a command with the given name to the given target devices.
53
56
  # The name should be a custom string defined by the user and understood by
54
57
  # the device.
55
58
  #
56
- # https://m2x.att.com/developer/documentation/v2/commands#Send-Command
59
+ # @param {Client} client Client API
60
+ # @param params Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
61
+ # @return {Command} The Command that was just sent.
62
+ #
57
63
  def send!(client, params)
58
64
  client.post(PATH, nil, params, "Content-Type" => "application/json")
59
65
  end
@@ -1,58 +1,72 @@
1
1
  require_relative "./resource"
2
2
  require_relative "./metadata"
3
3
 
4
- # Wrapper for AT&T M2X Device API
5
- # https://m2x.att.com/developer/documentation/v2/device
4
+ # Wrapper for {https://m2x.att.com/developer/documentation/v2/device M2X Device} API
6
5
  class M2X::Client::Device < M2X::Client::Resource
7
6
  include M2X::Client::Metadata
8
7
 
9
8
  PATH = "/devices"
10
9
 
11
10
  class << self
12
- # Retrieve the list of devices accessible by the authenticated API key
13
11
  #
14
- # https://m2x.att.com/developer/documentation/v2/device#List-Devices
12
+ # Method for {https://m2x.att.com/developer/documentation/v2/device#List-Devices List Devices} endpoint.
13
+ # @param {Client} client Client API
14
+ # @param params Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
15
+ # @return (Array) List of {Device} objects
16
+ #
15
17
  def list(client, params={})
16
18
  res = client.get(PATH, params)
17
19
 
18
20
  res.json["devices"].map{ |atts| new(client, atts) } if res.success?
19
21
  end
20
22
 
21
- # Retrieve the list of devices accessible by the authenticated API key that
22
- # meet the search criteria.
23
23
  #
24
- # https://m2x.att.com/developer/documentation/v2/device#Search-Devices
24
+ # Method for {https://m2x.att.com/developer/documentation/v2/device#Search-Devices Search Devices} endpoint.
25
+ #
26
+ # @param {Client} client Client API
27
+ # @param params Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
28
+ # @return (Array) List of {Device} objects.
29
+ #
25
30
  def search(client, params={})
26
31
  res = client.get("#{PATH}/search", params)
27
32
 
28
33
  res.json["devices"].map{ |atts| new(client, atts) } if res.success?
29
34
  end
30
35
 
31
- # Search the catalog of public Devices.
32
36
  #
37
+ # Method for {https://m2x.att.com/developer/documentation/v2/device#List-Search-Public-Devices-Catalog List Search Public Devices Catalog} endpoint.
33
38
  # This allows unauthenticated users to search Devices from other users
34
39
  # that have been marked as public, allowing them to read public Device
35
40
  # metadata, locations, streams list, and view each Devices' stream metadata
36
41
  # and its values.
37
42
  #
38
- # https://m2x.att.com/developer/documentation/v2/device#List-Search-Public-Devices-Catalog
43
+ # @param {Client} client Client API
44
+ # @param params Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
45
+ # @return (Array) List of {Device} objects.
46
+ #
39
47
  def catalog(client, params={})
40
48
  res = client.get("#{PATH}/catalog", params)
41
49
 
42
50
  res.json["devices"].map{ |atts| new(client, atts) } if res.success?
43
51
  end
44
52
 
45
- # List Device Tags
46
- # Retrieve the list of device tags for the authenticated user.
47
53
  #
48
- # https://m2x.att.com/developer/documentation/v2/device#List-Device-Tags
54
+ # Method for {https://m2x.att.com/developer/documentation/v2/device#List-Device-Tags List Device Tags} endpoint.
55
+ #
56
+ # @param {Client} client Client API
57
+ # @return (Array) Device Tags associated with the account
58
+ #
49
59
  def tags(client)
50
60
  client.get("#{PATH}/tags")
51
61
  end
52
62
 
53
- # Create a new device
54
63
  #
55
- # https://m2x.att.com/developer/documentation/v2/device#Create-Device
64
+ # Method for {https://m2x.att.com/developer/documentation/v2/device#Create-Device Create Device} endpoint.
65
+ #
66
+ # @param {Client} client Client API
67
+ # @param params Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
68
+ # @return {Device} newly created device.
69
+ #
56
70
  def create!(client, params)
57
71
  res = client.post(PATH, nil, params, "Content-Type" => "application/json")
58
72
 
@@ -64,153 +78,142 @@ class M2X::Client::Device < M2X::Client::Resource
64
78
  @path ||= "#{ PATH }/#{ URI.encode(@attributes.fetch("id")) }"
65
79
  end
66
80
 
67
- # View Request Log
81
+ #
82
+ # Method for {https://m2x.att.com/developer/documentation/v2/device#View-Request-Log View Request Log} endpoint.
68
83
  # Retrieve list of HTTP requests received lately by the specified device
69
84
  # (up to 100 entries).
70
85
  #
71
- # https://m2x.att.com/developer/documentation/v2/device#View-Request-Log
86
+ # @return (Array) Most recent API requests made against this Device
87
+ #
72
88
  def log
73
89
  @client.get("#{path}/log")
74
90
  end
75
91
 
76
- # Get location details of an existing Device.
77
92
  #
93
+ # Method for {https://m2x.att.com/developer/documentation/v2/device#Read-Device-Location Read Device Location} endpoint.
78
94
  # Note that this method can return an empty value (response status
79
95
  # of 204) if the device has no location defined.
80
96
  #
81
- # https://m2x.att.com/developer/documentation/v2/device#Read-Device-Location
97
+ # @return {Response} Most recently logged location of the Device, see M2X API docs for details
98
+ #
82
99
  def location
83
100
  @client.get("#{path}/location")
84
101
  end
85
102
 
86
- # Read Device Location History
87
103
  #
88
- # Get location history details of an existing Device. Returns the 30 most
89
- # recently logged locations by default.
90
- # https://m2x.att.com/developer/documentation/v2/device#Read-Device-Location-History
104
+ # Method for {https://m2x.att.com/developer/documentation/v2/device#Read-Device-Location-History Read Device Location History} endpoint.
105
+ # Returns the 30 most recently logged locations by default.
106
+ #
107
+ # @param params Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
108
+ # @return (Array) Location history of the Device
109
+ #
91
110
  def location_history(params = {})
92
111
  @client.get("#{path}/location/waypoints", params)
93
112
  end
94
113
 
95
- # Update the current location of the specified device.
96
114
  #
97
- # https://m2x.att.com/developer/documentation/v2/device#Update-Device-Location
115
+ # Method for {https://m2x.att.com/developer/documentation/v2/device#Update-Device-Location Update Device Location} endpoint.
116
+ #
117
+ # @param params Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
118
+ # @return {Response} The API response, see M2X API docs for details.
119
+ #
98
120
  def update_location(params)
99
121
  @client.put("#{path}/location", nil, params, "Content-Type" => "application/json")
100
122
  end
101
123
 
102
- # Delete waypoints in a device's location history by a date range
124
+ #
125
+ # Method for {https://m2x.att.com/developer/documentation/v2/device#Delete-Location-History Delete Location History} endpoint.
103
126
  # The `start` and `stop` parameters should be ISO8601 timestamps
104
127
  #
105
- # https://m2x.att.com/developer/documentation/v2/device#Delete-Location-History
128
+ # @param (String) start from time to delete the location history
129
+ # @param (String) stop end time to delete the location history
130
+ # @return {Response} The API response, see M2X API docs for details.
131
+ #
106
132
  def delete_locations!(start, stop)
107
133
  params = { from: start, end: stop }
108
134
 
109
135
  @client.delete("#{path}/location/waypoints", nil, params, "Content-Type" => "application/json")
110
136
  end
111
137
 
112
- # Post Device Updates (Multiple Values to Multiple Streams)
113
- #
114
- # This method allows posting multiple values to multiple streams
115
- # belonging to a device and optionally, the device location.
116
138
  #
139
+ # Method for {https://m2x.att.com/developer/documentation/v2/device#Post-Device-Updates--Multiple-Values-to-Multiple-Streams- Post Device Updates (Multiple Values to Multiple Streams)} endpoint.
117
140
  # All the streams should be created before posting values using this method.
118
141
  #
119
- # The `values` parameter contains an object with one attribute per each stream to be updated.
120
- # The value of each one of these attributes is an array of timestamped values.
142
+ # @param params Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
143
+ # @return {Response} the API response, see M2X API docs for details
121
144
  #
122
- # {
123
- # temperature: [
124
- # { "timestamp": <Time in ISO8601>, "value": x },
125
- # { "timestamp": <Time in ISO8601>, "value": y },
126
- # ],
127
- # humidity: [
128
- # { "timestamp": <Time in ISO8601>, "value": x },
129
- # { "timestamp": <Time in ISO8601>, "value": y },
130
- # ]
131
- #
132
- # }
133
- #
134
- # The optional location attribute can contain location information that will
135
- # be used to update the current location of the specified device
136
- #
137
- # https://m2x.att.com/developer/documentation/v2/device#Post-Device-Updates--Multiple-Values-to-Multiple-Streams-
138
145
  def post_updates(params)
139
146
  @client.post("#{path}/updates", nil, params, "Content-Type" => "application/json")
140
147
  end
141
148
 
142
- # Post Device Update (Single Value to Multiple Streams)
143
- #
144
- # This method allows posting a single value to multiple streams
145
- # belonging to a device and optionally, the device's location.
146
149
  #
150
+ # Method for {https://m2x.att.com/developer/documentation/v2/device#Post-Device-Update--Single-Values-to-Multiple-Streams- Post Device Update (Single Value to Multiple Streams)} endpoint.
147
151
  # All the streams should be created before posting values using this method.
148
152
  #
149
- # The `params` parameter accepts a Hash which can contain the following keys:
150
- # - values: A Hash in which the keys are the stream names and the values
151
- # hold the stream values.
152
- # - location: (optional) A hash with the current location of the specified
153
- # device.
154
- # - timestamp: (optional) The timestamp for all the passed values and
155
- # location. If ommited, the M2X server's time will be used.
156
- #
157
- # {
158
- # values: {
159
- # temperature: 30,
160
- # humidity: 80
161
- # },
162
- # location: {
163
- # name: "Storage Room",
164
- # latitude: -37.9788423562422,
165
- # longitude: -57.5478776916862,
166
- # elevation: 5
167
- # }
168
- # }
169
- #
170
- # https://m2x.att.com/developer/documentation/v2/device#Post-Device-Update--Single-Values-to-Multiple-Streams-
153
+ # @param params Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
154
+ # @return {Response} the API response, see M2X API docs for details
155
+ #
171
156
  def post_update(params)
172
157
  @client.post("#{path}/update", nil, params, "Content-Type" => "application/json")
173
158
  end
174
159
 
175
- # List Values from all Data Streams of a Device
176
160
  #
177
- # https://m2x.att.com/developer/documentation/v2/device#List-Values-from-all-Data-Streams-of-a-Device
161
+ # Method for {https://m2x.att.com/developer/documentation/v2/device#List-Values-from-all-Data-Streams-of-a-Device List Values from all Data Streams} endpoint.
162
+ #
163
+ # @param params Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
164
+ # @return (Array) List of values from all the streams.
165
+ #
178
166
  def values(params = {})
179
167
  @client.get("#{path}/values", params)
180
168
  end
181
169
 
182
- # Export Values from all Data Streams of a Device
183
170
  #
184
- # https://m2x.att.com/developer/documentation/v2/device#Export-Values-from-all-Data-Streams-of-a-Device
171
+ # Method for {https://m2x.att.com/developer/documentation/v2/device#Export-Values-from-all-Data-Streams-of-a-Device Export Values from all Data Streams of a Device} endpoint.
172
+ #
173
+ # @param params Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
174
+ # @return {Response} the API response, see M2X API docs for details
175
+ #
185
176
  def values_export(params = {})
186
177
  @client.get("#{path}/values/export.csv", params)
187
178
  end
188
179
 
189
- # Search Values from all Data Streams of a Device
190
180
  #
191
- # https://m2x.att.com/developer/documentation/v2/device#Search-Values-from-all-Data-Streams-of-a-Device
181
+ # Method for {https://m2x.att.com/developer/documentation/v2/device#Search-Values-from-all-Data-Streams-of-a-Device Search Values from all Data Streams of a Device} endpoint.
182
+ #
183
+ # @param params Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
184
+ # @return (Array) List of values matching the search criteria.
185
+ #
192
186
  def values_search(params)
193
187
  @client.get("#{path}/values/search", nil, params, "Content-Type" => "application/json")
194
188
  end
195
189
 
196
- # Retrieve list of data streams associated with the device.
197
190
  #
198
- # https://m2x.att.com/developer/documentation/v2/device#List-Data-Streams
191
+ # Method for {https://m2x.att.com/developer/documentation/v2/device#List-Data-Streams List Data Streams} endpoint.
192
+ #
193
+ # @return (Array) List of {Stream} objects.
194
+ #
199
195
  def streams
200
196
  ::M2X::Client::Stream.list(@client, self)
201
197
  end
202
198
 
203
- # Get details of a specific data Stream associated with the device
204
199
  #
205
- # https://m2x.att.com/developer/documentation/v2/device#View-Data-Stream
200
+ # Method for {https://m2x.att.com/developer/documentation/v2/device#View-Data-Stream View Data Stream} endpoint.
201
+ #
202
+ # @param (String) name name of the stream to be fetched
203
+ # @return {Stream} The matching stream
204
+ #
206
205
  def stream(name)
207
206
  ::M2X::Client::Stream.fetch(@client, self, name)
208
207
  end
209
208
 
210
- # Update a data stream associated with the Device
209
+ #
210
+ # Method for {https://m2x.att.com/developer/documentation/v2/device#Create-Update-Data-Stream Create Update Data Stream} endpoint.
211
211
  # (if a stream with this name does not exist it gets created).
212
212
  #
213
- # https://m2x.att.com/developer/documentation/v2/device#Create-Update-Data-Stream
213
+ # @param (String) name Name of the stream to be updated
214
+ # @param params Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
215
+ # @return {Stream} The Stream being updated
216
+ #
214
217
  def update_stream(name, params={})
215
218
  stream = ::M2X::Client::Stream.new(@client, self, "name" => name)
216
219
 
@@ -218,51 +221,70 @@ class M2X::Client::Device < M2X::Client::Resource
218
221
  end
219
222
  alias_method :create_stream, :update_stream
220
223
 
221
- # Returns a list of API keys associated with the device
224
+ #
225
+ # Method for {https://m2x.att.com/developer/documentation/v2/keys#List-Keys List Keys} endpoint.
226
+ #
227
+ # @return (Array) List of {Key} objects.
228
+ #
222
229
  def keys
223
230
  ::M2X::Client::Key.list(@client, params.merge(device: self["id"]))
224
231
  end
225
232
 
226
- # Creates a new API key associated to the device
227
233
  #
228
- # If a parameter named `stream` is supplied with a stream name, it
229
- # will create an API key associated with that stream only.
234
+ # Method for {https://m2x.att.com/developer/documentation/v2/keys#Create-Key Create Key} endpoint.
235
+ # Note that, according to the parameters sent, you can create a
236
+ # Master API Key or a Device/Stream API Key.
237
+ #
238
+ # @param params Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
239
+ # @return {Key} The newly created Key.
240
+ #
230
241
  def create_key(params)
231
242
  ::M2X::Client::Key.create!(@client, params.merge(device: self["id"]))
232
243
  end
233
244
 
234
- # Device's List of Received Commands
235
245
  #
236
- # Retrieve the list of recent commands sent to the current device (as given by the API key).
246
+ # Method for {https://m2x.att.com/developer/documentation/v2/commands#Device-s-List-of-Received-Commands Device's List of Recieved Commands} endpoint.
247
+ #
248
+ # @param params Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
249
+ # @return (Array) List of {Command} objects.
237
250
  #
238
- # https://m2x.att.com/developer/documentation/v2/commands#Device-s-List-of-Received-Commands
239
251
  def commands(params = {})
240
252
  res = @client.get("#{path}/commands", params)
241
253
 
242
254
  res.json["commands"].map { |atts| M2X::Client::Command.new(@client, atts) } if res.success?
243
255
  end
244
256
 
245
- # Device's View of Command Details
246
257
  #
258
+ # Method for {https://m2x.att.com/developer/documentation/v2/commands#Device-s-View-of-Command-Details Device's View of Command Details} endpoint.
247
259
  # Get details of a received command including the delivery information for this device.
248
260
  #
249
- # https://m2x.att.com/developer/documentation/v2/commands#Device-s-View-of-Command-Details
261
+ # @param (String) id Command ID to get
262
+ # @return {Command} object retrieved
263
+ #
250
264
  def command(id)
251
265
  res = @client.get("#{path}/commands/#{id}")
252
266
 
253
267
  M2X::Client::Command.new(@client, res.json) if res.success?
254
268
  end
255
269
 
256
- # Process a command
257
270
  #
258
- # https://m2x.att.com/developer/documentation/v2/commands#Device-Marks-a-Command-as-Processed
271
+ # Method for {https://m2x.att.com/developer/documentation/v2/commands#Device-Marks-a-Command-as-Processed Process Command} endpoint.
272
+ #
273
+ # @param (String) id Command ID to process
274
+ # @param params Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
275
+ # @return {Response} The API response, see M2X API docs for details
276
+ #
259
277
  def process_command(id, params = {})
260
278
  @client.post("#{path}/commands/#{id}/process", nil, params)
261
279
  end
262
280
 
263
- # Reject a command
264
281
  #
265
- # https://m2x.att.com/developer/documentation/v2/commands#Device-Marks-a-Command-as-Rejected
282
+ # Method for {https://m2x.att.com/developer/documentation/v2/commands#Device-Marks-a-Command-as-Rejected Reject Command} endpoint.
283
+ #
284
+ # @param (String) id Command ID to process
285
+ # @param params Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
286
+ # @return {Response} The API response, see M2X API docs for details
287
+ #
266
288
  def reject_command(id, params = {})
267
289
  @client.post("#{path}/commands/#{id}/reject", nil, params)
268
290
  end
@@ -1,18 +1,22 @@
1
1
  require_relative "./resource"
2
2
  require_relative "./metadata"
3
3
 
4
- # Wrapper for AT&T M2X Distribution API
5
- # https://m2x.att.com/developer/documentation/v2/distribution
4
+ # Wrapper for {https://m2x.att.com/developer/documentation/v2/distribution M2X Distribution} API
6
5
  class M2X::Client::Distribution < M2X::Client::Resource
7
6
  include M2X::Client::Metadata
8
7
 
9
8
  PATH = "/distributions"
10
9
 
11
10
  class << self
11
+ #
12
+ # Method for {https://m2x.att.com/developer/documentation/v2/distribution#List-Distributions List Distributions} endpoint.
12
13
  # Retrieve list of device distributions accessible by the authenticated
13
14
  # API key.
14
15
  #
15
- # https://m2x.att.com/developer/documentation/v2/distribution#List-Distributions
16
+ # @param {Client} client Client API
17
+ # @param params Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
18
+ # @return (Array) List of {Distribution} objects
19
+ #
16
20
  def list(client, params={})
17
21
  res = client.get(PATH, params)
18
22
 
@@ -20,9 +24,13 @@ class M2X::Client::Distribution < M2X::Client::Resource
20
24
  end
21
25
  alias_method :search, :list
22
26
 
23
- # Create a new device distribution
24
27
  #
25
- # https://m2x.att.com/developer/documentation/v2/distribution#Create-Distribution
28
+ # Method for {https://m2x.att.com/developer/documentation/v2/distribution#Create-Distribution Create Distribution} endpoint.
29
+ #
30
+ # @param {Client} client Client API
31
+ # @param params Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
32
+ # @return {Distribution} The newly created Distribution.
33
+ #
26
34
  def create!(client, params)
27
35
  res = client.post(PATH, nil, params, "Content-Type" => "application/json")
28
36
 
@@ -34,21 +42,24 @@ class M2X::Client::Distribution < M2X::Client::Resource
34
42
  @path ||= "#{ PATH }/#{ URI.encode(@attributes.fetch("id")) }"
35
43
  end
36
44
 
37
- # Retrieve list of devices added to the specified distribution.
38
45
  #
39
- # https://m2x.att.com/developer/documentation/v2/distribution#List-Devices-from-an-existing-Distribution
46
+ # Method for {https://m2x.att.com/developer/documentation/v2/distribution#List-Devices-from-an-existing-Distribution List Devices from an existing Distribution} endpoint.
47
+ #
48
+ # @param params Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
49
+ # @return (Array) List of Device objects
50
+ #
40
51
  def devices(params={})
41
52
  res = @client.get("#{path}/devices", params)
42
53
 
43
54
  res.json["devices"].map{ |atts| ::M2X::Client::Device.new(@client, atts) } if res.success?
44
55
  end
45
56
 
46
- # Add a new device to an existing distribution
47
57
  #
48
- # Accepts a `serial` parameter, that must be a unique identifier
49
- # within this distribution.
58
+ # Method for {https://m2x.att.com/developer/documentation/v2/distribution#Add-Device-to-an-existing-Distribution Add Device to an existing Distribution} endpoint.
59
+ #
60
+ # @param (String) serial The unique (account-wide) serial for the DistributionDevice being added
61
+ # @return {Device} The newly created DistributionDevice
50
62
  #
51
- # https://m2x.att.com/developer/documentation/v2/distribution#Add-Device-to-an-existing-Distribution
52
63
  def add_device(serial)
53
64
  res = @client.post("#{path}/devices", nil, { serial: serial }, "Content-Type" => "application/json")
54
65
 
@@ -0,0 +1,55 @@
1
+ # Wrapper for {https://m2x.att.com/developer/documentation/v2/integrations M2X Integrations} API
2
+ class M2X::Client::Integration < M2X::Client::Resource
3
+ PATH = "/integrations"
4
+
5
+ class << self
6
+ #
7
+ # Method for {https://m2x.att.com/developer/documentation/v2/integrations#List-Integrations List Integrations} endpoint.
8
+ # @param {Client} client Client API
9
+ # @param params Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
10
+ # @return (Array) List of {Integration} objects
11
+ #
12
+ def list(client, params={})
13
+ res = client.get(PATH, params)
14
+
15
+ res.json["integrations"].map{ |atts| new(client, atts) } if res.success?
16
+ end
17
+
18
+ #
19
+ # Method for {https://m2x.att.com/developer/documentation/v2/integrations#Create-Integration Create Integration} endpoint.
20
+ #
21
+ # @param {Client} client Client API
22
+ # @param params Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
23
+ # @return {Device} newly created device.
24
+ #
25
+ def create!(client, params)
26
+ res = client.post(PATH, nil, params, "Content-Type" => "application/json")
27
+
28
+ new(client, res.json) if res.success?
29
+ end
30
+ end
31
+
32
+ def path
33
+ @path ||= "#{ PATH }/#{ URI.encode(@attributes.fetch("id")) }"
34
+ end
35
+
36
+ # Method for {https://m2x.att.com/developer/documentation/v2/integrations#Update-Integration-Status Update Integration Status} endpoint.
37
+ #
38
+ # @param (String) id Command ID to process
39
+ # @param params Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
40
+ # @return {Response} The API response, see M2X API docs for details
41
+ #
42
+ def update_status(params = {})
43
+ @client.put("#{path}/status", nil, params)
44
+ end
45
+
46
+ # Method for {https://m2x.att.com/developer/documentation/v2/integrations#View-Integration-Status-Details View Integration Status Details} endpoint.
47
+ #
48
+ # @param (String) id Command ID to process
49
+ # @param params Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
50
+ # @return {Response} The API response, see M2X API docs for details
51
+ #
52
+ def view_status
53
+ @client.get("#{path}/status")
54
+ end
55
+ end
@@ -1,7 +1,6 @@
1
1
  require_relative "./resource"
2
2
 
3
- # Wrapper for AT&T M2X Job API
4
- # https://m2x.att.com/developer/documentation/v2/jobs
3
+ # Wrapper for {https://m2x.att.com/developer/documentation/v2/jobs M2X Job} API.
5
4
  class M2X::Client::Job < M2X::Client::Resource
6
5
 
7
6
  PATH = "/jobs"
@@ -1,27 +1,33 @@
1
1
  require_relative "./resource"
2
2
 
3
- # Wrapper for AT&T M2X Keys API
4
- # https://m2x.att.com/developer/documentation/v2/keys
3
+ # Wrapper for {https://m2x.att.com/developer/documentation/v2/keys M2X Keys} API
5
4
  class M2X::Client::Key < M2X::Client::Resource
6
5
 
7
6
  PATH = "/keys"
8
7
 
9
8
  class << self
10
- # Retrieve list of keys associated with the user account.
11
9
  #
12
- # https://m2x.att.com/developer/documentation/v2/keys#List-Keys
10
+ # Method for {https://m2x.att.com/developer/documentation/v2/keys#List-Keys List Keys} endpoint.
11
+ #
12
+ # @param {Client} client Client API
13
+ # @param params Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
14
+ # @return (Array) List of {Key} objects.
15
+ #
13
16
  def list(client, params={})
14
17
  res = client.get(PATH, params)
15
18
 
16
19
  res.json["keys"].map{ |atts| new(client, atts) } if res.success?
17
20
  end
18
21
 
19
- # Create a new API Key
20
22
  #
23
+ # Method for {https://m2x.att.com/developer/documentation/v2/keys#Create-Key Create Key} endpoint.
21
24
  # Note that, according to the parameters sent, you can create a
22
25
  # Master API Key or a Device/Stream API Key.
23
26
  #
24
- # https://m2x.att.com/developer/documentation/v2/keys#Create-Key
27
+ # @param {Client} client Client API
28
+ # @param params Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
29
+ # @return {Key} The newly created Key.
30
+ #
25
31
  def create!(client, params={})
26
32
  res = client.post(PATH, nil, params, "Content-Type" => "application/json")
27
33
 
@@ -33,13 +39,14 @@ class M2X::Client::Key < M2X::Client::Resource
33
39
  @path ||= "#{ PATH }/#{ URI.encode(@attributes.fetch("key")) }"
34
40
  end
35
41
 
36
- # Regenerate an API Key token
37
42
  #
43
+ # Method for {https://m2x.att.com/developer/documentation/v2/keys#Regenerate-Key Regenerate Key} endpoint.
38
44
  # Note that if you regenerate the key that you're using for
39
45
  # authentication then you would need to change your scripts to
40
46
  # start using the new key token for all subsequent requests.
41
47
  #
42
- # https://m2x.att.com/developer/documentation/v2/keys#Regenerate-Key
48
+ # @return {Key} The regenerated key.
49
+ #
43
50
  def regenerate
44
51
  res = @client.post("#{path}/regenerate", nil, {})
45
52
 
@@ -1,37 +1,52 @@
1
1
  module M2X::Client::Metadata
2
2
 
3
- # Read an object's metadata
4
3
  #
5
- # https://m2x.att.com/developer/documentation/v2/device#Read-Device-Metadata
6
- # https://m2x.att.com/developer/documentation/v2/distribution#Read-Distribution-Metadata
7
- # https://m2x.att.com/developer/documentation/v2/collections#Read-Collection-Metadata
4
+ # Method for
5
+ # {https://m2x.att.com/developer/documentation/v2/device#Read-Device-Metadata Read Device Metadata},
6
+ # {https://m2x.att.com/developer/documentation/v2/distribution#Read-Distribution-Metadata Read Distribution Metadata},
7
+ # {https://m2x.att.com/developer/documentation/v2/collections#Read-Collection-Metadata Read Collection Metadata} endpoints.
8
+ # @return {Response} The API response, see M2X API docs for details
9
+ #
8
10
  def read_metadata
9
11
  @client.get(metadata_path)
10
12
  end
11
13
 
12
- # Read a single field of an object's metadata
13
14
  #
14
- # https://m2x.att.com/developer/documentation/v2/device#Read-Device-Metadata-Field
15
- # https://m2x.att.com/developer/documentation/v2/distribution#Read-Distribution-Metadata-Field
16
- # https://m2x.att.com/developer/documentation/v2/collections#Read-Collection-Metadata-Field
15
+ # Method for
16
+ # {https://m2x.att.com/developer/documentation/v2/device#Read-Device-Metadata-Field Read Device Metadata Field},
17
+ # {https://m2x.att.com/developer/documentation/v2/distribution#Read-Distribution-Metadata-Field Read Distribution Metadata Field},
18
+ # {https://m2x.att.com/developer/documentation/v2/collections#Read-Collection-Metadata-Field Read Collection Metadata Field} endpoints.
19
+ #
20
+ # @param (String) field_name The metada field to be read
21
+ # @return {Response} The API response, see M2X API docs for details
22
+ #
17
23
  def read_metadata_field(field_name)
18
24
  @client.get("#{metadata_path}/#{field_name}")
19
25
  end
20
26
 
21
- # Update an object's metadata
22
27
  #
23
- # https://m2x.att.com/developer/documentation/v2/device#Update-Device-Metadata
24
- # https://m2x.att.com/developer/documentation/v2/distribution#Update-Distribution-Metadata
25
- # https://m2x.att.com/developer/documentation/v2/collections#Update-Collection-Metadata
28
+ # Method for
29
+ # {https://m2x.att.com/developer/documentation/v2/device#Update-Device-Metadata Update Device Metadata},
30
+ # {https://m2x.att.com/developer/documentation/v2/distribution#Update-Distribution-Metadata Update Distribution Metadata},
31
+ # {https://m2x.att.com/developer/documentation/v2/collections#Update-Collection-Metadata Update Collection Metadata} endpoints.
32
+ #
33
+ # @param params Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
34
+ # @return {Response} The API response, see M2X API docs for details
35
+ #
26
36
  def update_metadata(params)
27
37
  @client.put(metadata_path, nil, params, "Content-Type" => "application/json")
28
38
  end
29
39
 
30
- # Update a single field of an object's metadata
31
40
  #
32
- # https://m2x.att.com/developer/documentation/v2/device#Update-Device-Metadata-Field
33
- # https://m2x.att.com/developer/documentation/v2/distribution#Update-Distribution-Metadata-Field
34
- # https://m2x.att.com/developer/documentation/v2/collections#Update-Collection-Metadata-Field
41
+ # Method for
42
+ # {https://m2x.att.com/developer/documentation/v2/device#Update-Device-Metadata-Field Update Device Metadata Field},
43
+ # {https://m2x.att.com/developer/documentation/v2/distribution#Update-Distribution-Metadata-Field Update Distribution Metadata Field},
44
+ # {https://m2x.att.com/developer/documentation/v2/collections#Update-Collection-Metadata-Field Update Collection Metadata Field} endpoints.
45
+ #
46
+ # @param (String) field_name The metadata field to be updated
47
+ # @param (String) value The value to be updated
48
+ # @return {Response} The API response, see M2X API docs for details
49
+ #
35
50
  def update_metadata_field(field_name, value)
36
51
  @client.put("#{metadata_path}/#{field_name}", nil, { value: value }, "Content-Type" => "application/json")
37
52
  end
@@ -1,22 +1,30 @@
1
1
  require_relative "./resource"
2
2
 
3
- # Wrapper for AT&T M2X Data Streams API
4
- # https://m2x.att.com/developer/documentation/v2/device
3
+ # Wrapper for {https://m2x.att.com/developer/documentation/v2/device M2X Data Streams} API.
5
4
  class M2X::Client::Stream < M2X::Client::Resource
6
5
 
7
6
  class << self
8
- # Get details of a specific data Stream associated with a device
9
7
  #
10
- # https://m2x.att.com/developer/documentation/v2/device#View-Data-Stream
8
+ # Method for {https://m2x.att.com/developer/documentation/v2/device#View-Data-Stream View Data Streams} endpoint.
9
+ #
10
+ # @param {Client} client Client API
11
+ # @param (String) device device to fetch
12
+ # @param (String) name of the stream to be fetched
13
+ # @return {Stream} fetched stream
14
+ #
11
15
  def fetch(client, device, name)
12
16
  res = client.get("#{device.path}/streams/#{URI.encode(name)}")
13
17
 
14
18
  new(client, device, res.json) if res.success?
15
19
  end
16
20
 
17
- # Retrieve list of data streams associated with a device.
18
21
  #
19
- # https://m2x.att.com/developer/documentation/v2/device#List-Data-Streams
22
+ # Method for {https://m2x.att.com/developer/documentation/v2/device#List-Data-Streams List Data Streams} endpoint.
23
+ #
24
+ # @param {Client} client Client API
25
+ # @param (String) device device to get its data streams
26
+ # @return (Array) List of {Stream} objects
27
+ #
20
28
  def list(client, device)
21
29
  res = client.get("#{device.path}/streams")
22
30
 
@@ -34,48 +42,60 @@ class M2X::Client::Stream < M2X::Client::Resource
34
42
  @path ||= "#{@device.path}/streams/#{ URI.encode(@attributes.fetch("name")) }"
35
43
  end
36
44
 
37
- # Update stream properties
38
- # (if the stream does not exist it gets created).
39
45
  #
40
- # https://m2x.att.com/developer/documentation/v2/device#Create-Update-Data-Stream
46
+ # Method for {https://m2x.att.com/developer/documentation/v2/device#Create-Update-Data-Stream Create Update Data Stream} endpoint.
47
+ #
48
+ # @param params Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
49
+ # @return {Stream} The newly created stream
50
+ #
41
51
  def update!(params)
42
- res = @client.put(path, {}, params, "Content-Type" => "application/json")
43
-
44
- @attributes = res.json if res.status == 201
52
+ @client.put(path, {}, params, "Content-Type" => "application/json").tap do |res|
53
+ @attributes = res.json if res.status == 201
54
+ end
45
55
  end
46
56
 
47
- # List values from the stream, sorted in reverse chronological order
48
- # (most recent values first).
49
57
  #
50
- # https://m2x.att.com/developer/documentation/v2/device#List-Data-Stream-Values
58
+ # Method for {https://m2x.att.com/developer/documentation/v2/device#List-Data-Stream-Values List Data Stream Values} endpoint.
59
+ #
60
+ # @param params Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
61
+ # @return (Array) List of values from the stream
62
+ #
51
63
  def values(params={})
52
64
  @client.get("#{path}/values", params)
53
65
  end
54
66
 
55
- # Sample values from the stream, sorted in reverse chronological order
56
- # (most recent values first).
57
67
  #
68
+ # Method for {https://m2x.att.com/developer/documentation/v2/device#Data-Stream-Sampling Data Stream Sampling} endpoint.
58
69
  # This method only works for numeric streams
59
70
  #
60
- # https://m2x.att.com/developer/documentation/v2/device#Data-Stream-Sampling
71
+ # @param params Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
72
+ # @return (Array) List of sample values from the stream
73
+ #
61
74
  def sampling(params)
62
75
  @client.get("#{path}/sampling", params)
63
76
  end
64
77
 
65
- # Return count, min, max, average and standard deviation stats for the
66
- # values of the stream.
67
78
  #
79
+ # Method for {https://m2x.att.com/developer/documentation/v2/device#Data-Stream-Stats Data Stream Stats} endpoint.
80
+ # Returns the count, min, max, average and standard deviation stats for the
81
+ # values of the stream.
68
82
  # This method only works for numeric streams
69
83
  #
70
- # https://m2x.att.com/developer/documentation/v2/device#Data-Stream-Stats
84
+ # @param params Query parameters passed as keyword arguments. View M2X API Docs for listing of available parameters.
85
+ # @return (Array) Stats of the stream
86
+ #
71
87
  def stats(params={})
72
88
  @client.get("#{path}/stats", params)
73
89
  end
74
90
 
75
- # Update the current value of the stream. The timestamp
76
- # is optional. If omitted, the current server time will be used
77
91
  #
78
- # https://m2x.att.com/developer/documentation/v2/device#Update-Data-Stream-Value
92
+ # Method for {https://m2x.att.com/developer/documentation/v2/device#Update-Data-Stream-Value Update Data Stream Value} endpoint.
93
+ # The timestamp is optional. If omitted, the current server time will be used
94
+ #
95
+ # @param (String) value Value to be updated
96
+ # @param (String) timestamp Current Timestamp
97
+ # @return void
98
+ #
79
99
  def update_value(value, timestamp=nil)
80
100
  params = { value: value }
81
101
 
@@ -84,27 +104,33 @@ class M2X::Client::Stream < M2X::Client::Resource
84
104
  @client.put("#{path}/value", nil, params, "Content-Type" => "application/json")
85
105
  end
86
106
 
87
- # Post multiple values to the stream
88
107
  #
108
+ # Method for {https://m2x.att.com/developer/documentation/v2/device#Post-Data-Stream-Values Post Data Stream Values} endpoint.
109
+ # Post multiple values to the stream
89
110
  # The `values` parameter is an array with the following format:
90
- #
91
111
  # [
92
112
  # { "timestamp": <Time in ISO8601>, "value": x },
93
113
  # { "timestamp": <Time in ISO8601>, "value": y },
94
114
  # [ ... ]
95
115
  # ]
96
116
  #
97
- # https://m2x.att.com/developer/documentation/v2/device#Post-Data-Stream-Values
117
+ # @param values The values being posted, formatted according to the API docs
118
+ # @return {Response} The API response, see M2X API docs for details
119
+ #
98
120
  def post_values(values)
99
121
  params = { values: values }
100
122
 
101
123
  @client.post("#{path}/values", nil, params, "Content-Type" => "application/json")
102
124
  end
103
125
 
104
- # Delete values in a stream by a date range
126
+ #
127
+ # Method for {https://m2x.com/developer/documentation/v2/device#Delete-Data-Stream-Values Delete Data Stream Values} endpoint.
105
128
  # The `start` and `stop` parameters should be ISO8601 timestamps
106
129
  #
107
- # https://m2x.com/developer/documentation/v2/device#Delete-Data-Stream-Values
130
+ # @param (String) start from time to delete the data
131
+ # @param (String) stop end time to delete the data
132
+ # @return {Response} The API response, see M2X API docs for details
133
+ #
108
134
  def delete_values!(start, stop)
109
135
  params = { from: start, end: stop }
110
136
 
@@ -1,5 +1,5 @@
1
1
  module M2X
2
2
  class Client
3
- VERSION = "2.7.0"
3
+ VERSION = "2.8.0"
4
4
  end
5
5
  end
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: m2x
3
3
  version: !ruby/object:Gem::Version
4
- version: 2.7.0
4
+ version: 2.8.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Leandro López
@@ -10,7 +10,7 @@ authors:
10
10
  autorequire:
11
11
  bindir: bin
12
12
  cert_chain: []
13
- date: 2016-07-25 00:00:00.000000000 Z
13
+ date: 2017-10-18 00:00:00.000000000 Z
14
14
  dependencies: []
15
15
  description: AT&T’s M2X is a cloud-based fully managed data storage service for network
16
16
  connected machine-to-machine (M2M) devices. From trucks and turbines to vending
@@ -33,6 +33,7 @@ files:
33
33
  - lib/m2x/command.rb
34
34
  - lib/m2x/device.rb
35
35
  - lib/m2x/distribution.rb
36
+ - lib/m2x/integration.rb
36
37
  - lib/m2x/job.rb
37
38
  - lib/m2x/key.rb
38
39
  - lib/m2x/metadata.rb
@@ -61,7 +62,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
61
62
  version: '0'
62
63
  requirements: []
63
64
  rubyforge_project:
64
- rubygems_version: 2.5.1
65
+ rubygems_version: 2.6.11
65
66
  signing_key:
66
67
  specification_version: 4
67
68
  summary: Ruby client for AT&T M2X