民意调查
轮询资源包含有关特定数据请求的信息。创建轮询后，它将触发创建一个或多个任务以完成请求。
属性
| 名称 | 类型 | 描述 |
|---|---|---|
id | 民意调查 ID | 资源标识符。 |
resource | 字符串，始终poll | 资源类型说明符。 |
organisation | 组织ID | 与该资源关联的组织。 |
key | 钥匙ID | 与该资源关联的密钥。 |
user | 用户身份 | 与该资源关联的用户。 |
source | 源ID | 民意调查所针对的来源。这可以是会话源的子源。 |
session | 会话ID | 民意调查正在使用的会话。 |
subscription | 可选订阅 ID | 关联的订阅对象 ID（如果适用）。 |
tasks_pending | 任务 ID 列表 | 与正在等待处理的轮询关联的任务。 |
tasks_processing | 任务 ID 列表 | 与正在处理的轮询相关的任务。 |
tasks_succeeded | 任务 ID 列表 | 与已成功的轮询关联的任务。 |
tasks_failed | 任务 ID 列表 | 与失败的轮询相关的任务。 |
tasks_suspended | 任务 ID 列表 | 与暂停的轮询相关的任务。 |
results | 包含结果对象的列表对象 | 由轮询任务生成的结果对象列表。 |
errors | 包含错误对象的列表对象 | 由轮询任务生成的错误对象列表。 |
state | 细绳 | 其中之一： pending 、 processing 、 completed 。 |
date_created | 约会时间 | 创建资源的时间。 |
date_started | 可选日期时间 | 民意调查何时开始处理。 |
date_completed | 可选日期时间 | 民意调查处理完成时。 |
任务
轮询资源的最重要作用是反映其相关任务的进度，并允许最终用户在这些结果可用后立即开始从中获取结果。因此，轮询资源公开了与任务相关的属性，其中，根据任务的状态对相关任务进行了分类。
结果
轮询中运行的任务发布的任何结果都将显示在轮询的results属性中。这样可以在调查完成之前消耗结果。
错误
在轮询中运行的任务引起的任何错误将显示在轮询的errors属性中。
状态
轮询状态仅反映轮询是等待初始化（ pending ），正在进行（ processing ）还是所有任务已完成执行（ completed ）。
除了通过其关联任务之外，轮询不会反映任何错误状态。
有效载荷
轮询有效负载指示应检索哪些类型的信息，数据类型和文件。轮询有效载荷属性架构如下所述。
| 名称 | 类型 | 描述 |
|---|---|---|
info_types | info_type对象列表 | 指定应检索哪些信息类型。支持通配符* 。 |
data_types | data_type对象列表 | 指定应检索哪些数据类型。 |
files | file ID 列表。 | 指定要检索的文件。 |
filters | 嵌套filters对象 | 指定对检索到的数据应用哪些过滤器。 |
skip_files | 布尔值 | 如果设置为 true，投票将跳过查找和发布附件文件，其中包括来自照片或视频源的任何资产。 |
例如，用于检索iCloud帐户源上所有类型的信息的轮询有效载荷将是：
{
"info_types": ["*"]
}
要从iCloud备份或重新孵化中继源中检索各种消息传递数据，但仅从特定日期开始：
{
"data_types": ["ios_messages.messages", "whatsapp.messages", "viber.messages"],
"filters": {
"since": "2019-09-15T22:04:12Z",
"until": "2021-06-02T12:00:00Z"
}
}
要检索iCloud照片库结果中引用的图像的文件数据，请执行以下操作：
{
"files": ["icpl://xyz123", "icpl://abc321"]
}
不同的属性也可以同时使用：
{
"info_types": ["*"],
"data_types": ["ios_phone.calls"]
}
过滤器
过滤器允许客户端减少返回的数据量，仅返回可能感兴趣的数据。例如，您可以将 SMS 数据的轮询过滤为仅最后一个月的数据。
| 名称 | 类型 | 描述 |
|---|---|---|
since | 可选日期时间 | 仅过滤在此日期时间之后创建的数据。 |
until | 可选日期时间 | 仅过滤在此日期时间之前创建的数据。 |
phone_numbers | 可选数组 | 仅过滤与此列表中的电话号码相关的数据。 |
exclude_phone_numbers | 可选数组 | 仅过滤与此列表中的电话号码不相关的数据。 |
email_addresses | 可选数组 | 仅过滤与此列表中的电子邮件地址相关的数据。 |
exclude_email_addresses | 可选数组 | 仅过滤与此列表中的电子邮件地址不相关的数据。 |
订阅轮询负载中的过滤器
当使用订阅生成定期轮询时，轮询有效负载中设置的任何过滤器将仅在订阅的初始轮询中使用。此后，API 将执行以下操作：
- 忽略
until任何值，以避免简单地重复重新轮询相同的间隔 - 如果设置了
until，则下一次轮询将从该时间点开始获取数据 - 如果未设置
until，则下一次轮询将从初始轮询向前获取数据（即API 将正常轮询）
数据级过滤器
数据级过滤器（例如phone_numbers和email_addresses ）有助于将处理的数据减少到仅与您相关的项目。这些过滤器会删除与过滤器列表中的值之一匹配的另一项不匹配或不相关的任何数据项。以下面的有效负载为例：
{
"data_types": ["ios_messages.messages"],
"filters": {
"phone_numbers": ["0123456789"],
"email_addresses": ["test@example.com"]
}
}
这将从 iOS 消息中返回与涉及指定电话号码或电子邮件地址的对话相关的任何消息，包括任何群组对话。指定多个要过滤的值会很有帮助，因为许多联系人同时拥有电话号码和电子邮件识别的帐户，例如“消息”的 iCloud 帐户。
基于排除的过滤器（例如exclude_phone_numbers和exclude_email_addresses ）的作用相反：它们会移除与指定值相关的任何数据。如果同时提供了基于包含和排除的过滤器，并且某个项目同时符合这两种过滤器，则基于排除的过滤器生效。例如，一个群组对话中，如果一个联系人的电子邮件地址被包含在过滤器中，而另一个联系人的电话号码被排除在外，那么该联系人的数据将被过滤掉。
创建POST /polls
针对特定会话创建针对数据的轮询。
仅当将会话的主要来源的子来源作为目标时，才应使用source参数。例如，如果从rirelay.source检索数据，则source参数应为该源的ID。
| 名称 | 类型 | 描述 |
|---|---|---|
key | 可选，钥匙 ID | （可选）覆盖用于此轮询的密钥。当让用户试用新功能时，这非常有用。 |
source | 可选，源 ID | （可选）以会话链接源的子源为目标。 |
session | 会话ID | 用于验证数据检索的会话。 |
subscription | 订阅号 | 用于执行轮询的订阅。如果提供了这一点，则可以省略source和session 。 |
payload | 嵌套轮询负载 | 用于指定轮询的轮询负载 |
使用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": ["*"]
}
}'
使用ricloud-py
import ricloud
poll_payload = {
'info_types': ['*'],
}
poll = ricloud.Poll.create(
session='<session ID or ricloud.Session instance>',
payload=poll_payload,
)
样品回复
{
"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
}
简历POST /polls/{poll ID}/resume
Resume a poll by re-dispatching any suspended tasks and retrying failed file tasks. This can be used to trigger re-evaluation of requested files from Relay app instances, or for re-attempting file tasks which may have failed due to a transient issue.
| 名称 | 类型 | 描述 |
|---|---|---|
skip_missing |
optional boolean, default false |
If set to true, the poll will continue processing until all available data and file results have been published, skipping any that are missing. |
retry_files |
optional boolean, default true |
If set to true, any failed file publishing tasks will be retried. |
使用cURL
curl https://ricloud-api.reincubate.com/polls/<poll ID>/resume \
-X POST \
-H 'Authorization: Token <your key_token>' \
-H 'Content-Type: application/json' \
-d '{}'
继续讨论具体选项：
curl https://ricloud-api.reincubate.com/polls/<poll ID>/resume \
-X POST \
-H 'Authorization: Token <your key_token>' \
-H 'Content-Type: application/json' \
-d '{
"skip_missing": true,
"retry_files": false
}'
检索GET /polls/{poll ID}
使用cURL
curl https://ricloud-api.reincubate.com/polls/<poll ID> \
-H 'Authorization: Token <your key_token>'
使用ricloud-py
import ricloud
poll = ricloud.Poll.retrieve(<poll ID>)
列出GET /polls
| 名称 | 类型 | 描述 |
|---|---|---|
key | 钥匙ID | 按关联键过滤。这是用户当时使用的密钥。 |
user | 用户身份 | 按关联用户过滤。 |
source | 源ID | 按目标源过滤。 |
session | 会话ID | 按目标会话过滤。 |
subscription | 订阅号 | 按关联的订阅进行过滤。 |
state | 细绳 | 按会话状态过滤。 |
date_created | 日期时间过滤器 | 按资源创建时间进行过滤。 |
date_started | 日期时间过滤器 | 按投票开始时间过滤。 |
date_completed | 日期时间过滤器 | 按投票结束时间进行筛选。 |
使用cURL
curl https://ricloud-api.reincubate.com/polls \
-H 'Authorization: Token <your key_token>'
使用ricloud-py
import ricloud
polls = ricloud.Poll.list()
变更日志
2026-03-06
- 添加
POST /polls/{poll ID}/resume端点，用于恢复已暂停的任务和重试失败的文件任务。默认情况下，失败的文件任务会进行重试。
2024-12-09
- 通过
exclude_phone_numbers和exclude_emails轮询有效负载参数，添加排除与特定联系人电子邮件地址和电话号码相关的数据的支持。
2023-11-28
- 通过
phone_numbers和emails轮询有效负载参数添加使用联系人电子邮件地址和电话号码过滤数据的支持。
2022-07-08
- 添加了对轮询有效负载中的
until过滤器的支持，以进行 SMS 提取。这补充了since过滤器，允许客户端指定要从中检索数据的确切日期时间范围。
2020-05-05
-
errors属性已添加到轮询对象。这是一个嵌套列表对象，其中包含与轮询相关的错误对象。
2020-02-20
- Major ：轮询对象的
results属性现在是嵌套列表对象，而不是简单的列表属性。当民意调查发布大量结果时，可以对结果进行分页。
2019-10-16
- 将
subscription属性添加到轮询对象，以指示轮询是否由订阅触发。
2019-06-01
- 轮询对象
payload属性现在可以由多种操作类型组成。这意味着可以使用有效负载中的任何或所有info-types，data-types和files来创建轮询。 - Major不建议使用poll对象的
type属性，而建议使用可组合的poll有效负载。