Polls

A poll resource contains information on a specific request for data. Once a poll is created, it will trigger the creation of one or more tasks in order to complete the request.
Attributes
name | type | description |
---|---|---|
id |
poll ID | Resource identifier. |
resource |
string, always poll |
Resource type specifier. |
organisation |
organisation ID | The organisation associated with this resource. |
key |
key ID | The key associated with this resource. |
user |
user ID | The user associated with this resource. |
source |
source ID | The source the poll is targeting. This can be a child source of the session's source. |
session |
session ID | The session the poll is using. |
subscription |
optional subscription ID | The associated subscription object ID, if applicable. |
tasks_pending |
list of task IDs | The tasks associated with the poll that are awaiting processing. |
tasks_processing |
list of task IDs | The tasks associated with the poll that are being processed. |
tasks_succeeded |
list of task IDs | The tasks associated with the poll that have succeeded. |
tasks_failed |
list of task IDs | The tasks associated with the poll that have failed. |
tasks_suspended |
list of task IDs | The tasks associated with the poll that are suspended. |
results |
list object containing result objects | List of result objects generated by the poll's tasks. |
errors |
list object containing error objects | List of error objects generated by the poll's tasks. |
state |
string | One of: pending , processing , completed . |
date_created |
datetime | When the resource was created. |
date_started |
optional datetime | When processing of the poll began. |
date_completed |
optional datetime | When processing of the poll finished. |
Tasks
The most important role of the poll resource is to reflect the progress of its associated tasks and allow the end-user to start fetching results from these as soon as they become available. Therefore, the poll resource exposes task related attributes wherein associated tasks are categorised by their state.
Results
Any results published by tasks running within the poll are surfaced in the poll's results
attribute. This allows for consumption of results before the poll has completed.
Errors
Any errors raised by tasks running within the poll will appear in the poll's errors
attribute.
States
The state of a poll reflects only whether the poll is awaiting initialisation (pending
), is in progress (processing
), or all tasks have finished execution (completed
).
A poll does not reflect any error states other than through its associated tasks.
Payload
The poll payload indicates which types of information, data types, and files it should work to retrieve. The poll payload attribute schema is described below.
name | type | description |
---|---|---|
info_types |
list of info_type objects |
Specifies which info types should be retrieved. Supports wildcard * . |
data_types |
list of data_type objects |
Specifies which data types should be retrieved. |
files |
list of file IDs. |
Specifies which files to retrieve. |
filters |
nested filters object |
Specifies which filters to apply to retrieved data. |
For example, the poll payload to retrieve all types of information on an iCloud account source would be:
{ "info_types": ["*"] }
To retrieved a variety of messaging data from an iCloud backup or Reincubate Relay source, but only from a certain date:
{ "data_types": ["ios_messages.messages", "whatsapp.messages", "viber.messages"], "filters": { "since": "2019-09-15T22:04:12Z" } }
To retrieve file data for images referenced in an iCloud Photo Library result:
{ "files": ["icpl://xyz123", "icpl://abc321"] }
The different attributes can also be used simultaneously:
{ "info_types": ["*"], "data_types": ["ios_phone.calls"] }
Create POST /polls
Create a poll for data against a specific session.
The source
parameter should only be used when targeting a child source of the session's primary source. For example, if retrieving data from a rirelay.source
the source
parameter should be the ID of that source.
name | type | description |
---|---|---|
key |
optional, key ID | Optionally override the key used for this poll. This is useful when letting users trial new functionality. |
source |
optional, source ID | Optionally target a child source of the session-linked source. |
session |
session ID | The session to be used to authenticate data retrieval. |
subscription |
subscription ID | The subscription to use to perform the poll. If this is provided, source and session can be omitted. |
payload |
nested poll payload | The poll payload used to specify poll |
Using cURL
curl https://ricloud-api.reincubate.com/polls \ -X POST \ -H 'Authorization: Token <your key_token>' \ -H 'Content-Type: application/json' \ -d '{ "session": "<session ID>", "payload": { "info_types": ["*"] } }'
Using ricloud-py
import ricloud poll_payload = { 'info_types': ['*'], } poll = ricloud.Poll.create( session='<session ID or ricloud.Session instance>', payload=poll_payload, )
Sample response
{ "id": "54554389-5f1a-4ccf-9bb8-024a031cf948", "resource": "poll", "organisation": 1, "key": 1, "user": 1, "source": 1, "session": "f5a7a7ef-ff21-47fe-9aa6-7ebd08123623", "subscription": null, "tasks_pending": [], "tasks_processing": [], "tasks_succeeded": [], "tasks_failed": [], "tasks_suspended": [], "results": { "data": [], "has_more": false, "total_count": 0, "url": "/polls/54554389-5f1a-4ccf-9bb8-024a031cf948/results" }, "errors": { "data": [], "has_more": false, "total_count": 0, "url": "/polls/54554389-5f1a-4ccf-9bb8-024a031cf948/errors" }, "state": "pending", "date_created": "2020-02-20T11:59:14.694337Z", "date_started": null, "date_completed": null }
Retrieve GET /polls/{poll ID}
Using cURL
curl https://ricloud-api.reincubate.com/polls/<poll ID> \ -H 'Authorization: Token <your key_token>'
Using ricloud-py
import ricloud poll = ricloud.Poll.retrieve(<poll ID>)
List GET /polls
name | type | description |
---|---|---|
key |
key ID | Filter by associated key. This is the key used by the user at the time. |
user |
user ID | Filter by associated user. |
source |
source ID | Filter by the target source. |
session |
session ID | Filter by the target session. |
subscription |
subscription ID | Filter by the associated subscription. |
state |
string | Filter by session state. |
date_created |
datetime filter | Filter by when the resource was created. |
date_started |
datetime filter | Filter by when the poll started. |
date_completed |
datetime filter | Filter by when the poll was finished. |
Using cURL
curl https://ricloud-api.reincubate.com/polls \ -H 'Authorization: Token <your key_token>'
Using ricloud-py
import ricloud polls = ricloud.Poll.list()
Changelog
2020-05-05
- The
errors
attribute was added to the poll object. This is a nested list object containing error objects associated with the poll.
2020-02-20
- Major: The
results
attribute of the poll object is now a nested list object, rather than a simple list attribute. This makes it possible to paginate results when a poll publishes a large number of results.
2019-10-16
- Adds the
subscription
attribute to the poll object to indicate whether the poll was triggered by a subscription.
2019-06-01
- The poll object
payload
attribute can now be composed of multiple operation types. This means a poll can be created with any or all ofinfo-types
,data-types
andfiles
in the payload. - Major The
type
attribute on the poll object is deprecated in favour of composable poll payloads.