Events: CRUD Event Data

Avatar
SupportTeam

The following endpoints are related to event data on the IoT Platform.

 

Create an event

This is a common endpoint used to create a new event.

Summary

  • Endpoint: /event_create
  • Method: POST
  • Required User Type: None, this works for all users

Body Parameters

  • device_id - string of user you want to create event for
    • Required
    • Type: string
    • Allowed users:
      • Any devices linked to current tenant
      • Tenant basic user
      • User basic user
      • If super admin/user: any user
  • stream - stream to send data to
    • Required
    • Type: string
  • event_data - data to send
    • Required
    • Type: dictionary
  • observed_at - event timestamp
    • Default: Now
    • Type: Date object or ISO-8601 date string

Response

A successful response will return an array containing the event's event_id.

 

Example

Request Body

{
 device_id: 'accounts',
 stream: 'licensee_accounts',
 event_data: {"test": "test1234", "test2": 1}
}

Response Data

["12345678"]

 

Retrieve data by stream

This is a common endpoint used to query data from a stream.

Summary

  • Endpoint: /device_data
  • Method: GET
  • Required User Type: None, this works for all users

URL Parameters

Note: all tags must be written with their stream, ie "raw.device_id", where "raw" is the stream and "device_id" is the tag

  • device_id - string of user you want to query data from
    • Required
    • Allowed users:
      • Any devices linked to current tenant
      • Tenant basic user
      • User basic user
      • If super admin/user: can query from any user
    • You can set more than one device_id
  • stream - stream to query data from
    • Required
  • limit - maximum number of events to query
    • Default: 1000
    • Max: 10000
  • since - query events that occurred no earlier than this time
    • Default: Beginning of time
    • Type:  ISO-8601 date string
  • until - query events that occurred no later than this time
    • Default: Now
    • Type: ISO-8601 date string
  • sort_by - part of event to sort by, typically "observed_at"
    • Default: None
    • Required with use of "sort_direction"
  • sort_direction - either "asc" or "desc"
    • Default: None
    • Required with use of "sort_by"
  • rule - rule to limit included data in response by tag presence or equality
    • Default: None
    • You must surround string tag values with quotes, ie 'name = "test name"'
    • You can set more than one rule
  • xrule - rule to exclude data from response by tag presence or equality
    • Default: None
    • You must surround string tag values with quotes, ie 'name = "test name"'
    • You can set more than one xrule
  • filters - filters to limit included data in response with more complexity than rules

Response

A successful response will return an array of objects.

Each of the objects represents a different user (specified by the "device_id" parameter) and contains a "data" tag which is an array of events matching the query. Each event has "event_id", "observed_at", and "event_data" tags.

 

Example

Request URL

https://portal-example.mediumone.com/device_data?device_id=accounts&stream=licensee_accounts&limit=1

Response Data

[{
  "tag": "_full_event_", 
  "device_id": "accounts", 
  "data": [{
      "event_id": "123",
      "observed_at": "2020-01-07T01:06:31.484870+00:00",
      "event_data": {
          "tenant_user": "t_123",
          "amount": 100,
          "faculty_string": "abc123",
          "licensee": "ANIMALS!"
      }]
}]

 

Retrieve data by tag

Instead of querying data by stream, you may want to query by tag instead.

Summary

  • Endpoint: /device_data
  • Method: GET
  • Required User Type: None, this works for all users

URL Parameters

Note: all tags must be written with their stream, ie "raw.device_id", where "raw" is the stream and "device_id" is the tag

  • device_id - string of user you want to query data from
    • Required
    • Allowed users:
      • Any devices linked to current tenant
      • Tenant basic user
      • User basic user
      • If super admin/user: can query from any user
    • You can set more than one device_id
  • tag - list of tags you want to query
    • Required
    • You can set more than one tag
  • limit - maximum number of events to query
    • Default: 1000
    • Max: 10000
  • since - query events that occurred no earlier than this time
    • Default: Beginning of time
    • Type:  ISO-8601 date string
  • until - query events that occurred no later than this time
    • Default: Now
    • Type: ISO-8601 date string
  • sort_by - part of event to sort by, typically "observed_at"
    • Default: None
    • Required with use of "sort_direction"
  • sort_direction - either "asc" or "desc"
    • Default: None
    • Required with use of "sort_by"
  • rule - rule to limit included data in response by tag presence or equality
    • Default: None
    • You must surround string tag values with quotes, ie 'name = "test name"'
    • You can set more than one rule
  • xrule - rule to exclude data from response by tag presence or equality
    • Default: None
    • You must surround string tag values with quotes, ie 'name = "test name"'
    • You can set more than one xrule
  • filters - filters to limit included data in response with more complexity than rules

Response

A successful response will return an array of objects.

Each of the objects represents a combination of a user (specified by the "device_id" parameter) with a tag (specified by the "tag" parameter) and contains a "data" tag which is an array of arrays. Each of those arrays contains the following:

  • Index 0: Timestamp of event containing tag
  • Index 1: Tag's value in that event

 

Example

Request URL

https://portal-example.mediumone.com/device_data?device_id=accounts&tag=licensee_accounts.amount&tag=licensee_accounts.licensee

Response Data

[{
  "tag": "licensee_accounts.amount", 
  "device_id": "accounts", 
  "data": [
    ["2020-01-07T01:06:31.484870+00:00", 100],
    ["2020-01-07T00:06:31.484870+00:00", 1]
  ]
 },
 {
  "tag": "licensee_accounts.licensee", 
  "device_id": "accounts", 
  "data": [
    ["2020-01-07T01:06:31.484870+00:00", "ANIMAL"],
    ["2020-01-07T00:08:32.484870+00:00", "?"]
  ]
 }
]

Retrieve data with a large query

The above 2 queries have a request size limit since the parameters are in the URL. If you have a large query, you can use this endpoint instead and get the same result.

Summary

  • Endpoint: /device_data_post
  • Method: POST
  • Required User Type: None, this works for all users

Body Parameters

Note: all tags must be written with their stream, ie "raw.device_id", where "raw" is the stream and "device_id" is the tag

  • device_id - list of strings of each user you want to query data from
    • Required
    • Type: list of strings
    • Allowed users:
      • Any devices linked to current tenant
      • Tenant basic user
      • User basic user
      • If super admin/user: can query from any user
    • Notice that this must be a list - it cannot just be a string
  • tag - tag you want to query
    • Required if retrieving data by tag
    • Type: list of strings
  • stream - stream to query data from
    • Required if retrieving data by stream
    • Type: string
  • limit - maximum number of events to query
    • Default: 1000
    • Max: 10000
    • Type: int
  • since - query events that occurred no earlier than this time
    • Default: Beginning of time
    • Type:  ISO-8601 date string
  • until - query events that occurred no later than this time
    • Default: Now
    • Type: ISO-8601 date string
  • sort_by - part of event to sort by, typically "observed_at"
    • Default: None
    • Type: string
    • Required with use of "sort_direction"
  • sort_direction - either "asc" or "desc"
    • Default: None
    • Type: string
    • Required with use of "sort_by"
  • rule - rules to limit included data in response by tag presence or equality
    • Default: None
    • Type: list of strings
    • You must surround string tag values with quotes, ie 'name = "test name"'
  • xrule - rules to exclude data from response by tag presence or equality
    • Default: None
    • Type: list of strings
    • You must surround string tag values with quotes, ie 'name = "test name"'
  • filters - filters to limit included data in response with more complexity than rules

Response

The response will be the same response as "Retrieve data by tag" or "Retrieve data by stream", depending on which argument you provided (tag vs stream)

 

Example

Request URL

https://portal-example.mediumone.com/device_data_post

Request Body

{
    "device_id": ["accounts"],
    "tag": ["licensee_accounts.amount", "licensee_accounts.licensee"]
}

Response Data

[{
  "tag": "licensee_accounts.amount", 
  "device_id": "accounts", 
  "data": [
    ["2020-01-07T01:06:31.484870+00:00", 100],
    ["2020-01-07T00:06:31.484870+00:00", 1]
  ]
 },
 {
  "tag": "licensee_accounts.licensee", 
  "device_id": "accounts", 
  "data": [
    ["2020-01-07T01:06:31.484870+00:00", "ANIMAL"],
    ["2020-01-07T00:08:32.484870+00:00", "?"]
  ]
 }
]

 

Update an event

This is a common endpoint used to update an event's data.

Note: If you update an event that contains a tag's last value, the last value will not be updated. Last values can only be updated by event creation.

Summary

  • Endpoint: /event_update
  • Method: POST
  • Required User Type: None, this works for all users

Body Parameters

  • device_id - string of user you want to update event for
    • Required
    • Type: string
    • Allowed users:
      • Any devices linked to current tenant
      • Tenant basic user
      • User basic user
      • If super admin/user: any user
  • stream - stream to send data to
    • Required
    • Type: string
  • event_data - data to send
    • Required
    • Type: dictionary
  • event_id - event_id associated with event
    • Required
    • Type: string
  • observed_at - event timestamp
    • Default: Now
    • Type: Date object or ISO-8601 date string

Response

A successful response will return an empty 200 OK response.

 

Example

Request Body

{
 device_id: 'accounts',
 stream: 'licensee_accounts',
 event_data: {"test": "test14", "test2": 1},
 event_id: "12345678"
}

Response Data

 

 

Delete an event

Deleting events is currently not possible. See How do I delete events? for recommended strategies.