Les sondages

Une ressource d'interrogation contient des informations sur une demande spécifique de données. Une fois qu'un sondage est créé, il déclenchera la création d'une ou plusieurs tâches afin de compléter la demande.
Les attributs
Nom | taper | la 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. |
Tâches
Le rôle le plus important de la ressource de sondage est de refléter la progression des tâches associées et de permettre à l'utilisateur final de commencer à extraire les résultats de ces tâches dès qu'ils sont disponibles. Par conséquent, la ressource d'interrogation expose les attributs liés aux tâches dans lesquels les tâches associées sont classées en fonction de leur état.
Résultats
Tous les résultats publiés par des tâches exécutées dans le sondage sont indiqués dans l'attribut results
du sondage. Cela permet de consommer les résultats avant la fin du sondage.
les erreurs
Toutes les erreurs soulevées par les tâches exécutées dans le sondage apparaîtront dans l'attribut d' errors
du sondage.
États
L'état d'une interrogation indique uniquement si l'interrogation est en attente d'initialisation (en pending
), en cours de processing
( processing
) ou si toutes les tâches ont été exécutées ( completed
).
Une interrogation ne reflète aucun état d'erreur autre que par ses tâches associées.
Charge utile
La charge utile d'interrogation indique les types d'informations, les types de données et les fichiers à récupérer. Le schéma d'attribut d'interrogation de la charge utile est décrit ci-dessous.
Nom | taper | la 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. |
Par exemple, le payload d'interrogation permettant de récupérer tous les types d'informations sur une source de compte iCloud serait:
{ "info_types": ["*"] }
Pour récupérer diverses données de messagerie à partir d'une source de sauvegarde iCloud ou Reincubate Relay, mais uniquement à partir d'une date donnée:
{ "data_types": ["ios_messages.messages", "whatsapp.messages", "viber.messages"], "filters": { "since": "2019-09-15T22:04:12Z", "until": "2021-06-02T12:00:00Z" } }
Pour récupérer les données de fichier pour les images référencées dans un résultat iCloud Photo Library:
{ "files": ["icpl://xyz123", "icpl://abc321"] }
Les différents attributs peuvent également être utilisés simultanément:
{ "info_types": ["*"], "data_types": ["ios_phone.calls"] }
Filters
Filters allow the client to reduce the amount of data returned to only that which is likely to be of interest. For example, you might filter a poll for SMS data to only the last month of data.
name | type | description |
---|---|---|
since |
optional datetime | Filter to only data that was created after this datetime. |
until |
optional datetime | Filter to only data that was created before this datetime. |
Filters in subscription poll payloads
When using subscriptions to generate regular polls, any filters set in the poll payload will only be used on the initial poll of the subscription. Thereafter, the API will do the following:
- Any value for
until
is ignored as to avoid simply re-polling the same interval repeatedly - If
until
was set, the next poll will fetch data from that point in time forward - If
until
was not set, the next poll will fetch data from the time of the initial poll forward (i.e. the API will poll progressively as normal)
Créer un POST /polls
Créez un sondage pour les données d'une session spécifique.
Le paramètre source
ne doit être utilisé que lorsque vous ciblez une source enfant de la source principale de la session. Par exemple, si la récupération de données à partir d'un rirelay.source
le paramètre source
doit être l'ID de cette source.
Nom | taper | la 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 |
Utiliser 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": ["*"] } }'
Utiliser ricloud-py
import ricloud poll_payload = { 'info_types': ['*'], } poll = ricloud.Poll.create( session='<session ID or ricloud.Session instance>', payload=poll_payload, )
Exemple de réponse
{ "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 }
Récupérer GET /polls/{poll ID}
Utiliser cURL
curl https://ricloud-api.reincubate.com/polls/<poll ID> \ -H 'Authorization: Token <your key_token>'
Utiliser ricloud-py
import ricloud poll = ricloud.Poll.retrieve(<poll ID>)
Liste GET /polls
Nom | taper | la 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. |
Utiliser cURL
curl https://ricloud-api.reincubate.com/polls \ -H 'Authorization: Token <your key_token>'
Utiliser ricloud-py
import ricloud polls = ricloud.Poll.list()
Changelog
2022-07-08
- Support for the
until
filter in poll payloads was added for SMS extraction. This complements thesince
filter to allow clients to specify an exact datetime range to retrieve data from.
2020-05-05
- L'attribut d'
errors
été ajouté à l'objet d'interrogation. Il s'agit d'un objet de liste imbriqué contenant des objets d'erreur associés au sondage.
2020-02-20
- Major : l'attribut
results
de l'objet poll est désormais un objet liste imbriqué, plutôt qu'un simple attribut list. Cela permet de paginer les résultats lorsqu'un sondage publie un grand nombre de résultats.
2019-10-16
- Ajoute l'attribut d'
subscription
à l'objet d'interrogation pour indiquer si l'interrogation a été déclenchée par un abonnement.
2019-06-01
- L'attribut de
payload
objet d'interrogation peut désormais être composé de plusieurs types d'opérations. Cela signifie qu'un sondage peut être créé avec tout ou partie desinfo-types
d'info-types
data-types
et desfiles
dans la charge utile. - Majeur L'attribut
type
sur l'objet d'interrogation est déconseillé au profit des charges utiles d'interrogation composables.