开始

更新

要开始使用ricloud v3 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": [],
    "storage_config_default": null,
    "webhook_configs": [],
    "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帐户。

设置会话

会话表示对源的访问。对于iCloud帐户来源,API将需要登录帐户以创建自身与Apple的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": "1",
    "type": "icloud.account",
    "identifier": "<iCloud account username>"
  },
  "payload": {
    "password": "<iCloud account password>"
  }
}'

响应将包含会话资源,当API经历与第三方服务建立通信的过程时,该资源最初将处于pending状态。在这种情况下,我们可以访问iCloud。

{
  "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属性的值以获取有关error的更多详细信息。

如果您的帐户启用了2FA,则遇到的错误很可能是code-required并且系统会在您的某个设备上提示您使用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": "1",
    "type": "icloud.account",
    "identifier": "<iCloud account username>"
  },
  "payload": {
    "password": "<iCloud account password>"
    "code": "<2FA code>"
  }
}'

如果发生其他错误,请查看错误部分以获取更多详细信息。

状态变为active ,会话就可以用于从源检索数据和文件。但是,正如我们之前看到的那样,您的组织尚未配置为接收任何此类数据,从而使我们进入下一步。

检索数据和文件

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

创建数据轮询

从iCloud中检索的最简单的数据集是一些基本的帐户信息。所需要的只是活动会话的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",
  "type": "data",
  "payload": {
    "data_types": ["callkit.calls"],
  }
}'

请注意,在上面的调用中我们指定了callkit.calls数据类型,但是您的密钥可能具有不同数据类型的权限,或者您可能对检索不同类型的数据感兴趣,只需根据需要进行替换即可。

这将返回一个民意调查资源。在后台,API还创建了一个任务,该任务将执行检索此信息所需的实际工作(还创建了一个任务以更早地设置我们的会话)。可以在tasks属性下看到任务的ID。

{
  "id": "f1447e76-59f1-486b-942f-6b90e3570c63",
  "resource": "poll",
  "organisation": "1",
  "key": "1",
  "user": "1",
  "source": "1",
  "session": "ed855b07-f72b-4983-ac1d-980fafee8a0b",
  "type": "data",
  "tasks_pending": [],
  "tasks_processing": ["6bdb82ad-28bf-4aad-ab2c-b4952a7aa3eb"],
  "tasks_completed": [],
  "results": [],
  "state": "processing",
  "date_created": "2018-11-22T14:20:52.211618Z",
  "date_started": "2018-11-22T14:20:52.731838Z",
  "date_completed": null
}

另请注意results属性,此时此属性为空。这是我们将开始查看从任务发布的数据的ID。

现在,我们要等到处理完成并且轮询的状态设置为succeeded

检索结果信息

通过查看轮询的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",
  "type": "data",
  "tasks_pending": [],
  "tasks_processing": [],
  "tasks_completed": ["6bdb82ad-28bf-4aad-ab2c-b4952a7aa3eb"],
  "results": [
    {
      "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
    }
  ],
  "state": "processing",
  "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功能会由于外部触发器(如asrelay实例查找新数据或由于计划的轮询)而自动触发。在这些情况下,API需要一种方法来告诉您的系统已发生更改或已发布您应了解的新数据。

为此,API使用webhook通知。在API可以开始发送这些内容之前,在您开始使用asrelay服务或预定轮询之前,您的组织需要配置有效的webhook配置。有关详细信息,请参阅webhook配置指南。

我们能帮你什么吗?

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

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

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

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

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

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

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