Apple iCloud服务

更新

The API supports retrieval of a variety of data and files from Apple's iCloud services.

届会

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

Creating a session for an account without 2FA/2SV

The session payload to create a session for an account without 2FA/2SV enabled contains the following parameters.

name type description
password string The iCloud account password.

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

Response

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

Creating a session for an account with 2FA

Creating a session for a 2FA enabled account is a two step process:

  1. Attempt to create a session using just the iCloud account password. This will trigger the 2FA process, which sends an authentication code to iOS and macOS devices associated with the account. The session creation attempt will fail with error="code-required".
  2. Use the iCloud account password and the authentication code received in (1) to create a session. If the code is accepted, the session will be successfully created.

Step 1: create session

name type description
password string The iCloud account password.

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

Response

If the 2FA process is triggered as expected, the session should fail to be created with the error: code-required.

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

Step 2: create session with code

name type description
password string The iCloud account password.
code string The authentication 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>"
  }
}'

Response

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

Creating a session for an account with 2SV

The process to create a session for a 2SV enabled account has three steps:

  1. Attempt to create a session using the iCloud account password. As 2SV is required, this will fail with error="choice-required" and error_info={"choices": [<2SV enabled devices>]}.
  2. Attempt to create a session again using the iCloud account password and a choice from the error_info["choices"] list. This time, the attempt will trigger the 2SV process which sends an authentication code to the chosen device. The attempt will fail with error="code-required".
  3. Use the iCloud account password and the authentication code received in (2) to create a session. If the code is accepted, the session will be successfully created.

This will trigger the 2SV process, which sends an authentication code to iOS and macOS devices associated with the account. The session creation attempt will fail with error="code-required".

Step 1: create session

name type description
password string The iCloud account password.

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

Response

If 2SV is enabled on the account, the session creation attempt will fail with error choice-required.

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

Step 2: create session with choice

name type description
password string The iCloud account password.
choice string The chosen device to send an authentication code to.

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

Response

If the 2FA process is triggered as expected, the session should fail to be created with the error: code-required.

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

Step 3: create session with code

name type description
password string The iCloud account password.
code string The authentication 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>"
  }
}'

Response

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

来源类型

identifier description
icloud.account primary source Corresponds to an iCloud account.

民意调查

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,
)

检索文件

The files poll payload attribute is used to request the retrieval of binary files from the targeted source.

The IDs will typically be retrieved from a previous poll for data types that include direct file references, like iCloud Photo Library, or that include attachments, like message data types.

使用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 Retrieves iCloud Photo Library assets.
mme_contacts.contacts Retrieves iCloud stored iOS Contacts data.
mme_calendar.events Retrieves iCloud stored iOS Calendar data.
mme_notes.notes 检索iCloud存储的iOS Notes数据。
callkit.calls 检索CallKit已同步的iOS Phone数据。
cloudkit_safari.history 检索iCloud存储的Safari浏览器历史记录数据。
fmip.devices 检索“查找我的iPhone”设备和位置数据。

iCloud Photo Library

Photos, videos and other media

Retrieves information on photos, videos and other media stored in iCloud Photo Library (ICPL).

This module requires that iCloud Photo Library is enabled on the user's iCloud account.

Data type ID icpl.photos
Associated setting Settings > [username] > iCloud > Photos > iCloud Photo Library

Data attributes

名称类型描述
id string An identifier for the data item. Useful for deduplicating data across multiple polls.
filename string The name of the file as it is stored in ICPL.
files list of image, video, audio items Files associated with this ICPL asset. The original file, Live Photos, thumbnails will be included in this list.
date_created datetime When the file was originally created. In the case of photos or videos taken on an iOS device, this will be the date when they were taken. In the case of existing assets imported to ICPL, this will be the original import date.
date_uploaded datetime When the file was last uploaded to ICPL. This will correspond to when the file was first retrievable via the ricloud API.

Data filters

name type description
since datetime Only includes items with a date_uploaded later than the provided value.
until datetime Only includes items with a date_uploaded earlier than the provided value.

Sample data

[
  {
    "id": "4d475a7bba2c604",
    "data_type": "icpl.asset",
    "filename": "IMG_0123.PNG",
    "files": [
      {
        "id": "icpl://ATnrIxddlwbCEjN33NBq8zXQwYgE",
        "data_type": "image",
        "extension": "png",
        "size": 119842,
        "width": 750,
        "height": 1334
      },
      {
        "id": "icpl://AcXwu8/wH8s6lfiGBDEZah6KzQjC",
        "data_type": "image",
        "extension": "jpg",
        "size": 210680,
        "width": 750,
        "height": 1334
      },
      {
        "id": "icpl://AbfMRXQ55H4WfS5YguuUWxir4hq6",
        "data_type": "image",
        "extension": "jpg",
        "size": 71032,
        "width": 310,
        "height": 554
      }
    ],
    "date_created": "2020-01-01T00:00:00.000000Z",
    "date_uploaded": "2020-01-01T00:00:00.000000Z"
  }
]

MobileMe Contacts

Contacts

Retrieves iOS Contacts data stored in iCloud.

Data type ID mme_contacts.contacts
Associated setting Settings > [username] > iCloud > Contacts

Data attributes

The mme_contacts.contact data type inherits most attributes from the base contact data type. The table below outlines additional or differing attributes.

名称类型描述
id string An identifier for the data item. Useful for deduplicating data across multiple polls.
data_type string, always mme_contacts.contact The data type of the item.
uid string A unique identifier that can be used to deduplicate across different sources of iOS Contacts data.
image nested image item, optional Profile image for the contact.

Sample data

[
  {
    "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 Calendar events mme_calendar.events

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

MobileMe Notes 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浏览器历史数据。

Find My and Find My iPhone

Device locations

Retrieve Find My device and location data.

Note that this data type may require multiple polls, with the second coming ~10-30 seconds after the first, in order to return complete data. This is due to how Find My operates: the first poll will trigger Find My to request new data from reachable devices but the data will not be available for another 10-30 seconds.

Data type ID fmip.devices
Associated setting Settings > [username] > Find My

Data attributes

名称类型描述
id string An identifier for the data item. Useful for deduplicating data across multiple polls.
data_type string, always fmip.devices The data type of the item.
name string The user set name for the device.
model_name string Apple's marketing name for the device model.
model_identifier string Apple's identifier for the device model.
product_type string The product category of the device.
location optional nested location The last reported location for the device, if one is available.
battery_status string The current battery status of the device.
battery_level float If known, the percentage battery charge remaining.

Sample data

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

文件类型

identifier description
icpl A file from iCloud Photo Library.
mme_contact_image An mme_contacts.contacts contact profile image.

我们能帮你什么吗?

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

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

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

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

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