开始
要开始使用ricloud API，您首先需要取得联系以设置您的组织。完成此操作后，您应该拥有初始的key_token ，它将授予您对API的访问权限。
本节中的API调用是使用cURL执行的，但这些调用可以很容易地用来自ricloud-py的等效调用替换。
查看您的组织
首先，我们将快速了解您的组织。
curl 'https://ricloud-api.reincubate.com/organisation' \ -H 'Authorization: Token <your key_token>'
您应该看到类似于下面的响应。如果您收到HTTP 401响应，请检查您在Authorization标头中提供的key_token值。
{ "id": 1, "resource": "organisation", "name": "Getting started", "slug": "getting-started", "permissions": { "id": 1, "resource": "organisation_permissions", "identifier": "default", "scopes": { "source_type:icloud.*": [], "task_type:*": [], "data_type:icloud.account.info": [], }, "date_created": "2018-11-22T12:59:57.168354Z" }, "storage_configs": { "data": [], "has_more": false, "total_count": 0, "url": "/configs/storage" }, "storage_config_default": null, "webhook_configs": { "data": [], "has_more": false, "total_count": 0, "url": "/configs/webhook" }, "webhook_config_default": null, "state": "unconfigured", "date_created": "2018-11-22T12:59:57.016467Z" }
在这里，您可以看到有关您组织的一些信息：
-
permissions显示组织的基本权限。 -
storage_configs和storage_config_default为空，因为我们尚未设置任何内容。 -
webhook_configs同样的原因，webhook_configs和webhook_config_default也是空的。 -
state是unconfigured，这反映了缺乏有效的存储配置。
我们稍后将回到配置步骤，因为这不会阻止您通过API访问服务。
现在我们已确认您的组织已启动并运行，我们尝试访问iCloud帐户。
设置会话
会话代表对源的访问。在这种情况下，我们的来源将是一个iCloud帐户，创建会话将有效地“登录”该帐户。然后，会话将负责跟踪API和iCloud系统之间的连接，以备将来使用。
创建用户
在设置会话之前，需要创建用户以定义哪个最终用户想要访问源。这有助于API的会话管理和数据安全性。
curl 'https://ricloud-api.reincubate.com/users' \ -X POST \ -H 'Authorization: Token <your key_token>' \ -H 'Content-Type: application/json' \ -d '{ "identifier": "<some identifier for the user your system will recognise>" }'
响应将包含下次调用所需的用户ID。
{ "id": "1", "resource": "user", "organisation": "1", "key": "1", "identifier": "<your user identifier>", "state": "active", "date_created": "2018-11-22T13:49:37.215516Z" }
创建会话
curl 'https://ricloud-api.reincubate.com/sessions' \ -X POST \ -H 'Authorization: Token <your key_token>' \ -H 'Content-Type: application/json' \ -d '{ "source": { "user": "<user ID from previous request>", "type": "icloud.account", "identifier": "<iCloud account username>" }, "payload": { "password": "<iCloud account password>" } }'
响应将包含一个会话资源，该会话资源最初将处于pending状态，而API会经历与第三方服务建立通信的过程。
{ "id": "ed855b07-f72b-4983-ac1d-980fafee8a0b", "resource": "session", "organisation": "1", "user": "1", "source": "1", "state": "pending", "error": null, "date_created": "2018-11-22T13:50:12.628776Z", "date_expired": null }
您可以通过检索调用检查会话的状态。
curl 'https://ricloud-api.reincubate.com/sessions/ed855b07-f72b-4983-ac1d-980fafee8a0b' \ -H 'Authorization: Token <your key_token>'
如果状态变为failed ，则初始化过程中出现了问题。检查error属性的值以获取更多详细信息。如果您的帐户启用了2FA，并且密码正确无误，则遇到的错误很可能需要code-required 。在连接到该帐户的一台iOS设备上，系统将提示您输入2FA代码。只需再次从步骤（1）进行调用，但是这次在有效负载中包含2FA代码。
curl 'https://ricloud-api.reincubate.com/sessions' \ -X POST \ -H 'Authorization: Token <your key_token>' \ -H 'Content-Type: application/json' \ -d '{ "source": { "user": "<user ID from previous request>", "type": "icloud.account", "identifier": "<iCloud account username>" }, "payload": { "password": "<iCloud account password>", "code": "<2FA code>" } }'
如果发生其他错误，请检查“ 错误”部分以获取更多信息。
状态变为active ，即可使用会话从源中检索数据和文件。
但是，如前所述，您的组织尚未配置为接收任何此类数据。
检索数据和文件
在API可以开始从源获取数据之前，它需要知道它应该将数据发布到何处。 API目前支持发布到Google云端存储和Amazon S3（AWS）存储分区，这些存储分区需要通过属于您组织的存储配置进行配置。按照存储配置设置文档中列出的步骤获取您自己准备好与API一起使用的存储桶。
有了存储配置后，您可以尝试再次检索组织。 state现在应该是active ，而不是unconfigured 。
创建数据轮询
要创建民意测验，我们需要提供的是活动会话的ID以及要检索的数据或文件的一些详细信息。
curl https://ricloud-api.reincubate.com/polls \ -X POST \ -H 'Authorization: Token <your key_token>' \ -H 'Content-Type: application/json' \ -d '{ "session": "ed855b07-f72b-4983-ac1d-980fafee8a0b", "payload": { "data_types": ["icpl.photos"], } }'
请注意，在上面的调用中，我们请求icpl.photos数据类型。您可能对检索其他类型的数据感兴趣，或者可能没有此数据类型的权限。根据需要替换此值。
这将返回一个轮询资源， state为pending或processing 。在后台，API还创建了一个任务，该任务将完成检索此信息所需的实际工作（还创建了一个任务来建立我们的会话）。
{ "id": "f1447e76-59f1-486b-942f-6b90e3570c63", "resource": "poll", "organisation": "1", "key": "1", "user": "1", "source": "1", "session": "ed855b07-f72b-4983-ac1d-980fafee8a0b", "tasks_pending": [], "tasks_processing": ["6bdb82ad-28bf-4aad-ab2c-b4952a7aa3eb"], "tasks_completed": [], "results": { "data": [], "has_more": false, "total_count": 0, "url": "/polls/f1447e76-59f1-486b-942f-6b90e3570c63/results" }, "errors": { "data": [], "has_more": false, "total_count": 0, "url": "/polls/f1447e76-59f1-486b-942f-6b90e3570c63/errors" }, "state": "processing", "date_created": "2018-11-22T14:20:52.211618Z", "date_started": "2018-11-22T14:20:52.731838Z", "date_completed": null }
请注意results属性，该属性此时为空。在此处，我们将看到针对此民意测验发布的任何数据或文件的引用。结果会在可用时发布，因此可以在整个民意调查完成之前对其进行检索。
将所有请求的数据和文件发布到您的存储后，民意调查的状态将更改为completed 。
检索结果信息
这可以通过查看民意调查的results属性来完成。
curl 'https://ricloud-api.reincubate.com/polls/f1447e76-59f1-486b-942f-6b90e3570c63' \ -H 'Authorization: Token <your key_token>'
响应将包含我们需要的信息。
{ "id": "f1447e76-59f1-486b-942f-6b90e3570c63", "resource": "poll", "organisation": "1", "key": "1", "user": "1", "source": "1", "session": "ed855b07-f72b-4983-ac1d-980fafee8a0b", "tasks_pending": [], "tasks_processing": [], "tasks_completed": ["6bdb82ad-28bf-4aad-ab2c-b4952a7aa3eb"], "results": { "data": [ { "id": "754cfef0-7576-44c0-acfe-8b0d8d0dd32f", "resource": "result", "task": "6bdb82ad-28bf-4aad-ab2c-b4952a7aa3eb", "identifier": "data:info.account", "url": "<your storage config url>", "checksum": "2668324d21a20301ce71c28bc5e621d4", "size": 12345, "state": "available", "date_created": "2018-11-22T14:20:53.506542Z", "date_consumed": null, "date_deleted": null } ], "has_more": false, "total_count": 0, "url": "/polls/f1447e76-59f1-486b-942f-6b90e3570c63/results" }, "errors": { "data": [], "has_more": false, "total_count": 0, "url": "/polls/f1447e76-59f1-486b-942f-6b90e3570c63/errors" }, "state": "completed", "date_created": "2018-11-22T14:20:52.211618Z", "date_started": "2018-11-22T14:20:52.731838Z", "date_completed": "2018-11-22T14:20:53.548372Z" }
结果的url属性将指向存储在存储桶中的文件。
接收webhook事件
某些API功能会自动触发，这是由于外部触发（例如Reincubate Relay应用程序找到新数据）或订阅引起的。在这些情况下，API需要一种方法来告诉您的系统已发生更改或已经发布了您应注意的新数据。
为此，API使用了Webhook通知。在API开始发送这些消息之前，以及在您开始使用Reincubate Relay服务或订阅之前，您的组织需要使用有效的webhook配置进行配置。有关更多详细信息，请遵循Webhook配置指南。
