Apple iCloud服务

更新一个多星期前

该API支持从Apple的iCloud服务中检索各种数据和文件。

届会

在API上为iCloud服务设置会话与登录iCloud帐户一样简单。如果帐户启用了多重身份验证（如2FA或2SV），则此过程可能需要多次尝试创建会话。

为没有2FA / 2SV的帐户创建会话

为未启用2FA / 2SV的帐户创建会话的会话有效负载包含以下参数。

名称	类型	描述
`password`	串	iCloud帐户密码。

使用cURL

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

响应

{
  "id": "<session ID>",
  "resource": "session",
  ...
  "state": "succeeded",
  "error": null,
  ...
}

为具有2FA的帐户创建会话

为启用2FA的帐户创建会话是一个两步过程：

尝试仅使用iCloud帐户密码创建会话。这将触发2FA流程，该流程会将身份验证代码发送到与该帐户关联的iOS和macOS设备。会话创建尝试将失败，并显示error="code-required" 。
使用（1）中收到的iCloud帐户密码和身份验证代码创建会话。如果代码被接受，则会话将成功创建。

步骤1：建立工作阶段

名称	类型	描述
`password`	串	iCloud帐户密码。

使用cURL

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

响应

如果2FA进程按预期方式触发，则会话将无法创建，并显示以下错误： code-required 。

{
  "id": "<session ID>",
  "resource": "session",
  ...
  "state": "failed",
  "error": "code-required",
  ...
}

步骤2：使用代码创建会话

名称	类型	描述
`password`	串	iCloud帐户密码。
`code`	串	验证码。

使用cURL

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": "<authentication code>"
  }
}'

响应

{
  "id": "<session ID>",
  "resource": "session",
  ...
  "state": "succeeded",
  "error": null,
  ...
}

为使用2SV的帐户创建会话

为启用2SV的帐户创建会话的过程分为三个步骤：

尝试使用iCloud帐户密码创建会话。由于需要2SV，因此将失败，并显示error="choice-required"和error_info={"choices": [<2SV enabled devices>]} 。
尝试使用iCloud帐户密码和从error_info["choices"]列表中error_info["choices"]再次创建会话。这次尝试将触发2SV进程，该进程将验证码发送到所选设备。尝试将失败，并显示error="code-required" 。
使用（2）中收到的iCloud帐户密码和身份验证代码创建会话。如果代码被接受，则会话将成功创建。

这将触发2SV进程，该进程将向与该帐户关联的iOS和macOS设备发送身份验证代码。会话创建尝试将失败，并显示error="code-required" 。

步骤1：建立工作阶段

名称	类型	描述
`password`	串	iCloud帐户密码。

使用cURL

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

响应

如果在该帐户上启用了2SV，则会话创建尝试将失败，并显示error choice-required错误。

{
  "id": "<session ID>",
  "resource": "session",
  ...
  "state": "failed",
  "error": "choice-required",
  "error_info": {
    "choices": [
      "********02 - SMS to Phone Number"
    ]
  }
  ...
}

第2步：创建带有选择的会话

名称	类型	描述
`password`	串	iCloud帐户密码。
`choice`	串	所选设备向其发送验证码。

使用cURL

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>",
    "choice": "********02 - SMS to Phone Number"
  }
}'

响应

如果2FA进程按预期方式触发，则会话将无法创建，并显示以下错误： code-required 。

{
  "id": "<session ID>",
  "resource": "session",
  ...
  "state": "failed",
  "error": "code-required",
  ...
}

步骤3：使用代码创建会话

名称	类型	描述
`password`	串	iCloud帐户密码。
`code`	串	验证码。

使用cURL

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": "<authentication code>"
  }
}'

响应

{
  "id": "<session ID>",
  "resource": "session",
  ...
  "state": "succeeded",
  "error": null,
  ...
}

来源类型

识别码	描述
`icloud.account`	主要来源对应于一个iCloud帐户。

民意调查

iCloud服务支持所有轮询有效载荷架构属性。

检索源信息

此轮询类型检索有关目标源的信息。结果以JSON格式发布。

使用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

# The ID of a session we made earlier.
session_id = "<session ID>"

poll = ricloud.Poll.create(
  session=session_id,
  payload={
    "info_types": ["*"]
  }
)

检索数据

此轮询类型从目标会话中检索和处理数据。结果以JSON格式发布。

有关特定数据类型的更多信息，请参见可用数据类型列表。

使用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": {
        "data_types": ["icpl.photos"]
    }
}'

使用* ricloud-py *

import ricloud

# The ID of a session we made earlier.
session_id = "<session ID>"

poll_payload = {
    "data_types": ["icpl.photos"]
}

poll = ricloud.Poll.create(
  session=session_id,
  payload=poll_payload,
)

检索文件

files轮询有效负载属性用于请求从目标源检索二进制文件。

通常会从以前的民意调查中检索ID，以获取包含直接文件引用（例如iCloud照片库）或包含附件（例如消息数据类型）的数据类型。

使用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": {
        "files": [
            "icpl://ATnrIxddlwbCEjN33NBq8zXQwYgE",
            "icpl://AbfMRXQ55H4WfS5YguuUWxir4hq6"
        ]
    }
}'

使用* ricloud-py *

import ricloud

# The ID of a session we made earlier.
session_id = "<session ID>"

poll_payload = {
    'files': [
        'icpl://ATnrIxddlwbCEjN33NBq8zXQwYgE',
        'icpl://AbfMRXQ55H4WfS5YguuUWxir4hq6',
    ]
}

poll = ricloud.Poll.create(
    session=session_id,
    payload=poll_payload,
)

资料类型

iCloud数据类型

识别码	描述
`icpl.photos`	检索iCloud照片库资产。
`mme_contacts.contacts`	检索iCloud存储的iOS联系人数据。
`mme_calendar.events`	检索iCloud存储的iOS日历数据。
`mme_notes.notes`	检索iCloud存储的iOS Notes数据。
`callkit.calls`	检索CallKit已同步的iOS Phone数据。
`cloudkit_safari.history`	检索iCloud存储的Safari浏览器历史记录数据。
`fmip.devices`	检索“查找我的iPhone”设备和位置数据。

iCloud照片库

照片，视频和其他媒体

检索有关iCloud照片库（ICPL）中存储的照片，视频和其他媒体的信息。

此模块要求在用户的iCloud帐户上启用iCloud照片库。


数据类型ID	`icpl.photos`
关联设置	`Settings` > `[username]` > `iCloud` > `Photos` > `iCloud Photo Library`

资料属性

名称	类型	描述
`id`	串	数据项的标识符。对于跨多个轮询重复数据删除很有用。
`filename`	串	存储在ICPL中的文件名。
`files`	`image` ， `video` ， `audio`项目列表	与此ICPL资产关联的文件。原始文件，实时照片，缩略图将包括在此列表中。
`date_created`	约会时间	最初创建文件的时间。对于在iOS设备上拍摄的照片或视频，该日期为拍摄日期。对于现有资产进口到ICPL，这将是原始进口日期。
`date_uploaded`	约会时间	文件上次上传到ICPL的时间。这对应于首次通过ricloud API检索文件的时间。
`local_date_created`	optional datetime	When the asset was originally created, in local time. This attribute is only populated if sufficient metadata is stored with the asset in ICPL, and is currently supported for parsing by the API. The value of this attribute can vary by a few seconds from that of `date_created`, as the two are determined from different sources.

资料筛选器

名称	类型	描述
`since`	约会时间	仅包括`date_uploaded`晚于提供的值的项目。
`until`	约会时间	仅包括`date_uploaded`早于提供的值的项目。

样本数据

[
  {
    "id": "7f1384f5038255f5",
    "data_type": "icpl.asset",
    "filename": "IMG_0002.HEIC",
    "files": [
      {
        "id": "icpl://AWo/lDeN8fEExAUJajRHzVx2j605",
        "data_type": "image",
        "extension": "heic",
        "size": 905818,
        "width": 4032,
        "height": 3024
      },
      {
        "id": "icpl://ASDPdJ/LvFWjsBy4YOOp7B5c+XOi",
        "data_type": "video",
        "extension": "mov",
        "size": 2456163,
        "width": 980,
        "height": 1308
      },
      {
        "id": "icpl://ASAwWOvwrvAUuO71uXcU6mm+nMU4",
        "data_type": "image",
        "extension": "jpg",
        "size": 595624,
        "width": 1536,
        "height": 2048
      },
      {
        "id": "icpl://ATy/qmemCas1jzYWuhR4mQywhpzz",
        "data_type": "image",
        "extension": "jpg",
        "size": 65407,
        "width": 360,
        "height": 480
      }
    ],
    "date_created": "2020-09-18T12:32:17Z",
    "date_uploaded": "2020-09-18T12:41:19Z",
    "local_date_created": "2020-09-18T13:32:17+01:00"
  }
]

MobileMe联系人

联络人

检索存储在iCloud中的iOS联系人数据。


数据类型ID	`mme_contacts.contacts`
关联设置	`Settings` > `[username]` > `iCloud` > `Contacts`

资料属性

mme_contacts.contact数据类型从基本contact数据类型继承大多数属性。下表概述了其他或不同的属性。

名称	类型	描述
`id`	串	数据项的标识符。对于跨多个轮询重复数据删除很有用。
`data_type`	字符串，始终为`mme_contacts.contact`	项目的数据类型。
`uid`	串	唯一标识符，可用于在iOS联系人数据的不同来源之间进行重复数据删除。
`image`	嵌套`image`项目，可选	联系人的个人资料图片。

样本数据

[
  {
    "id": "2cf6a837304d6614",
    "data_type": "mme_contacts.contact",
    "uid": "NzNlNjkxYjctOTBmYi00MTYxLWI5YzYtZTk0ZDlhZjljMmE5",
    "first_name": "John",
    "middle_name": "'Gala'",
    "last_name": "Appleseed",
    "prefix": "Mr.",
    "suffix": "Jr.",
    "nickname": "John'o",
    "records": [
      {
        "type": "Phone",
        "name": "MAIN",
        "value": "1-800-MY-APPLE"
      },
      {
        "type": "Phone",
        "name": "UK",
        "value": "0800 039 1010"
      },
      {
        "type": "URL",
        "name": "HOMEPAGE",
        "value": "http://www.apple.com"
      },
      {
        "type": "URL",
        "name": "HOMEPAGE",
        "value": "http://www.apple.com/uk/"
      },
      {
        "City": "Cupertino",
        "State": "CA",
        "ZIP": "95014",
        "name": "WORK",
        "CountryCode": "US",
        "Country": "United States",
        "Street": "1 Infinite Loop",
        "type": "Address",
        "SubLocality": null,
        "Municipality": null
      }
    ],
    "organisation": "Apple Inc.",
    "department": "Marketing",
    "jobtitle": "VP Coring",
    "birthday": "1976-04-01",
    "image": {
      "id": "mme_contact_image://2cf6a837304d6614",
      "data_type": "image",
      "extension": "jpg"
    }
  }
]

MobileMe日历事件`mme_calendar.events`

检索iCloud存储的iOS日历数据。

MobileMe Notes注释`mme_notes.notes`

检索iCloud存储的iOS Notes数据。

呼叫工具

来自CallKit callkit.calls 调用

检索与CallKit服务同步的呼叫日志。

错误

callkit-uninitialised

表示尚未为此帐户设置CallKit服务。通过以下步骤，iCloud帐户所有者可以使用与iCloud帐户关联的iOS设备来解决此错误：-确保该设备已连接到Wi-Fi。 -导航至Settings > [username] > iCloud 。 -关闭iCloud驱动器，等待30到60秒，以使更改生效。 -之前的更改完成后，请打开iCloud Drive。这应该触发初始化。

如果执行此过程后错误仍然存在，请与支持部门联系。

callkit-sync-disabled

在这种情况下，CallKit服务已初始化，但设备开始将呼叫历史同步到iCloud所需的条件尚未满足。 API将通过iCloud远程解决此问题，但与iCloud帐户关联的设备可能无法重新评估其同步状态，因为这是缓存的。

iCloud帐户所有者可以通过以下步骤触发设备以重新检查通话记录同步条件：

导航到Settings > [username] > iCloud 。
关闭iCloud驱动器，等待30到60秒，以使更改生效。
之前的更改完成后，请打开iCloud Drive。这应该触发初始化。

故障排除

最近的通话记录未在投票结果中返回。

这通常是由于设备没有与iCloud同步其最新的呼叫历史记录。 CallKit服务是内部iOS服务，无法在设置中打开或关闭或触发手动同步。这可能使调试缺失数据变得困难，因为它不清楚设备有什么或没有同步到iCloud。

对于没有太多数据要同步的帐户（少于~3次调用），这个问题更常见，这通常是测试帐户的情况。

建议：

确保设备具有多个要同步的通话记录记录。我们的测试表明，只有几个通话记录的设备不会触发iCloud同步过程。
等待设备执行定期同步。最多可能需要12个小时，具体取决于设备的使用方式，连接状态和充电状态。
将设备插入电源。在这种状态下，设备更有可能触发同步。
以前的通话记录不会在民意调查结果中返回。

CallKit服务用于在设备之间同步呼叫历史记录，而不是无限期地存储这些记录。通常，呼叫历史记录可以从CallKit中检索大约3个月，但根据iCloud中的内部清理过程，这可能会因帐户而异。

CloudKit

来自iCloud的浏览器历史记录 cloudkit_safari.history

检索存储在iCloud同步服务中的Safari浏览器历史数据。

查找我和查找我的iPhone

设备位置

检索“查找我的设备”和位置数据。

请注意，此数据类型可能需要多次轮询，第二次轮询大约在第一次轮询之后10-30秒，以便返回完整的数据。这是由于“查找我”的操作方式所致：第一次轮询将触发“查找我”以从可访问的设备中请求新数据，但该数据将在另外10到30秒钟内不可用。


数据类型ID	`fmip.devices`
关联设置	`Settings` > `[username]` > `Find My`

资料属性

名称	类型	描述
`id`	串	数据项的标识符。对于跨多个轮询重复数据删除很有用。
`data_type`	字符串，始终为`fmip.devices`	项目的数据类型。
`name`	串	设备的用户设置名称。
`model_name`	串	苹果设备型号的市场名称。
`model_identifier`	串	苹果设备型号的标识符。
`product_type`	串	设备的产品类别。
`location`	可选的嵌套`location`	设备上次报告的位置（如果有）。
`battery_status`	串	设备的当前电池状态。
`battery_level`	浮动	如果知道，则剩余电量百分比。

样本数据

[
  {
    "id": "e7694d7a0d2ab6cf",
    "data_type": "fmip.device",
    "name": "John's iMac",
    "model_name": "iMac with Retina 5K display",
    "model_identifier": "iMac15,1",
    "product_type": "iMac",
    "location": null,
    "battery_status": "Unknown",
    "battery_level": 0.0
  },
  {
    "id": "4d86a6181808d152",
    "data_type": "fmip.device",
    "name": "John's iPhone 11",
    "model_name": "iPhone 11",
    "model_identifier": "iPhone6,2",
    "product_type": "iPhone",
    "location": {
      "data_type": "location",
      "latitude": 51.507452392689146,
      "longitude": -0.07398372304584414,
      "altitude": 0.0,
      "horizontal_accuracy": 65.0,
      "vertical_accuracy": 0.0,
      "positioning_type": "Wifi",
      "date_created": "2020-01-01T00:00:00.000000Z"
    },
    "battery_status": "Unknown",
    "battery_level": 0.0
  }
]

文件类型

识别码	描述
`icpl`	来自iCloud照片库的文件。
`mme_contact_image`	`mme_contacts.contacts`联系人个人资料图像。

Apple iCloud服务

届会

为没有2FA / 2SV的帐户创建会话

为具有2FA的帐户创建会话

步骤1：建立工作阶段

步骤2：使用代码创建会话

为使用2SV的帐户创建会话

步骤1：建立工作阶段

第2步：创建带有选择的会话

步骤3：使用代码创建会话

来源类型

民意调查

检索源信息

检索数据

检索文件

资料类型

iCloud照片库

照片，视频和其他媒体

MobileMe联系人

联络人

MobileMe日历事件`mme_calendar.events`

MobileMe Notes注释`mme_notes.notes`

呼叫工具

CloudKit

查找我和查找我的iPhone

设备位置

文件类型

我们能帮你什么吗？

重新孵化时事通讯

届会

为没有2FA / 2SV的帐户创建会话

为具有2FA的帐户创建会话

步骤1：建立工作阶段

步骤2：使用代码创建会话

为使用2SV的帐户创建会话

步骤1：建立工作阶段

第2步：创建带有选择的会话

步骤3：使用代码创建会话

来源类型

民意调查

检索源信息

检索数据

检索文件

资料类型

iCloud照片库

照片，视频和其他媒体

MobileMe联系人

联络人

MobileMe日历事件mme_calendar.events

MobileMe Notes注释mme_notes.notes

呼叫工具

CloudKit

查找我和查找我的iPhone

设备位置

文件类型

我们能帮你什么吗？

MobileMe日历事件`mme_calendar.events`

MobileMe Notes注释`mme_notes.notes`