开始

更新

To start using the ricloud API, you first need to get in touch to setup your organisation. Once this is completed, you should have your initial key_token which will grant you access to the 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_configsstorage_config_default为空,因为我们尚未设置任何内容。
  • webhook_configs同样的原因, webhook_configswebhook_config_default也是空的。
  • stateunconfigured ,这反映了缺乏有效的存储配置。

我们稍后将回到配置步骤,因为这不会阻止您通过API访问服务。

现在我们已确认您的组织已启动并运行,我们尝试访问iCloud帐户。

设置会话

A session represents access to a source. In this case, our source will be an iCloud account and creating a session will effectively "login" to the account. The session will then take care of keeping track of the connection between the API and iCloud's system for future requests.

创建用户

在设置会话之前,需要创建用户以定义哪个最终用户想要访问源。这有助于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>"
  }
}'

The response will contain a session resource, which will initially be in the pending state while the API goes through the process of setting up communications with the third-party service.

{
  "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>'

If the state becomes failed, something went wrong during the initialisation process. Check the value of the error attribute for more details. If 2FA is enabled on your account -- and you got your password correct -- the error encountered is likely to be code-required. You will have been prompted with a 2FA code on one of your iOS devices connected to the account. Simply make the call from step (1) again, but this time including the 2FA code in the payload.

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>"
  }
}'

If another error occurred, please check the errors section for more information.

Once the state becomes active the session is ready for use to retrieve data and files from the source.

However, as we saw earlier, your organisation is not yet configured to receive any of this data.

检索数据和文件

在API可以开始从源获取数据之前,它需要知道它应该将数据发布到何处。 API目前支持发布到Google云端存储Amazon S3(AWS)存储分区,这些存储分区需要通过属于您组织的存储配置进行配置。按照存储配置设置文档中列出的步骤获取您自己准备好与API一起使用的存储桶。

Once you have a storage config, you can try retrieving your organisation again. The state should now be active, rather than unconfigured.

创建数据轮询

To create a poll, all we need to provide is the ID of an active session and some details on the data or files we want retrieved.

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"],
  }
}'

Note that in the call above we request the icpl.photos data type. You might be interested in retrieving a different type of data, or might not have permissions for this data type in particular. Substitute this value as necessary.

This will return a poll resource, with state in pending or processing. In the background, the API has also created a task which will do the actual work required to retrieve this information (a task was also created to set up our session earlier).

{
  "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
}

Note the results attribute, which is empty at this point. This is where we will see references appear for any data or files published from this poll. Results are published as they become available, so they can be retrieved before the whole poll has completed.

Once all requested data and files have been published to your storage, the poll's state will change to completed.

检索结果信息

This is done by looking at the results attribute of the poll.

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事件

Certain API functionality is triggered automatically, either as a result of external triggers such as a Reincubate Relay app finding new data or due to a subscription. In these cases, the API needs a way to tell your system that changes have happened or that new data has been published which you should be aware of.

To do this, the API makes use of webhook notifications. Before the API can start sending these, and before you can start using the Reincubate Relay service or subscriptions, your organisation needs to be configured with a valid webhook config. Follow the guide on webhook configuration for more details.

我们能帮你什么吗?

我们的支持团队在这里提供帮助!

我们的办公时间是格林威治标准时间周一至周五上午9点至下午5点。 时间目前是 4:37 PM的 GMT。

我们力争在一个工作日内答复所有垂询。

转到支持部分 › 联系企业团队 ›
我们的支持团队非常棒

我们可以改进这篇文章吗?

我们喜欢听取用户的意见:为什么不给我们发电子邮件,发表评论或发推文 @reincubate?

© 2008 - 2020 Reincubate Ltd. 保留所有权利。 在英格兰和威尔士注册 #5189175, VAT GB151788978. Reincubate®是注册商标。 隐私政策 & 条款. 我们推荐多因素认证。 在伦敦建立了爱情。