Apple iCloud服务(v2)

更新

ricloud API的icloud服务提供了访问存储在iCloud上的信息的功能,既可以从iOS设备备份中批量生成,也可以从其他来源实时和近实时地访问。自原始版本发布以来,API一直支持访问iCloud。

客户端可能需要使用iCloud服务执行四项核心操作。

  • 身份验证: log-inperform-2fa-challengesubmit-2fa-challenge
  • 设备枚举: list-devices
  • 请求提要: fetch-data
  • 请求原始文件: download-file

使用API中的模拟数据

为了帮助开发与API的集成,可以使用填充了一组丰富数据的模拟帐户。这允许客户端测试许多ricloud API的功能,而无需使用真实的用户数据。

模拟账户名为Jonny Appleseed,可以使用iCloud账户ID john.appleseed@reincubate.com和密码joshua

认证

登录: log-in

登录icloud服务的第一步是登录。

对于请求,我们必须指定:

  • 与...交互的serviceicloud
  • 要执行的actionlog-in
  • 参数account ,代表iCloud帐户ID,例如john.appleseed@reincubate.com
  • 操作所需的操作参数,在本例中只是password
  • 我们还可以指定/account/ endpoint列出的可选操作参数
$ curl \
    -X POST \
    -H "Authorization: Token <TOKEN>"
    -d "service=icloud" \
    -d "action=log-in" \
    -d "account=<ACCOUNT>" \
    -d "password=<PASSWORD>" \
    <TASK_SUBMISSION_ENDPOINT>

asapi端点将以JSON格式回复:

{ "retrieval_protocol": "aschannel",
  "stream": "<STREAM>",
  "success": true,
  "task_id": "<TASK_ID_1>"
}

如果您连接到aschannel端点上的正确stream_endpoint,您将看到与从asapi端点收到的<TASK_ID_1>匹配的结果。

{ "message": "Log-in successful",
  "auth_token": "ABCDEFGABCDEFGABCDEFGABCDEFGABCDEFGABCDEFGABCDEFGABCDEFG",
  "success": true
}

结果将包括一个success参数,如果登录任务成功,该参数将成立,以及用于其他服务操作的消息和Apple身份验证令牌。

登录故障排除

有关错误定义和解决方案,请参阅登录错误响应部分。

2FA和2SV

尝试登录使用2SV或2FA设置的iCloud帐户后,正常登录将失败,并返回类似于下面的错误消息。

{ "message": "This account has Two Step Verification enabled, please select a device to challenge.",
  "data": {
    "trustedDevices": ["********12", "Renate's iPhone - iPhone 6s"],
  },
  "error": "2fa-required"
}

data字典将包含由device_id键入的列表设备。这些是iCloud帐户信任的设备,用于执行下一个身份验证步骤。

用于两步验证(2SV)

在两步验证的情况下,名单trustedDevices将包含一个或多个设备。客户必须选择列出的设备进行质询。

这是通过执行完成perform-2fa-challengechallenge设置为从所选设备的关键trustedDevices

用于双因素身份验证(2FA)

在2FA的情况下,列表trustedDevices将被设定为["Challenge all 2FA devices"]这表明是一个挑战必须发送到连接到该帐户的所有iOS设备。这是通过执行perform-2fa-challenge并将challenge设置为["Challenge all 2FA devices"]

使用perform-2fa-challenge

此方法将在2FA的情况下实时向帐户上的所有设备发送请求,或在2SV的情况下向所选设备发送请求。

$ curl \
    -X POST \
    -H "Authorization: Token <TOKEN>"
    -d "service=icloud" \
    -d "action=perform-2fa-challenge" \
    -d "challenge=<TRUSTED_DEVICE>" \
    <TASK_SUBMISSION_ENDPOINT>

<TRUSTED_DEVICE> must be set to a device_id, or to "Challenge all 2FA devices"

asapi将照常回复:

{ "retrieval_protocol": "aschannel",
  "stream": "<STREAM>",
  "success": true,
  "task_id": "<TASK_ID_X>"
}

检索端点将回复:

{ "message": "Challenge has been submitted.",
  "success": true
}

一旦将挑战发送到用户的设备,必须使用submit-2fa-challenge将双因素代码中继回API。在下面的请求中, <CODE>是最终用户提供的数字代码,表示传输到设备以进行2FA / 2SV登录的代码。

$ curl \
    -X POST \
    -H "Authorization: Token <TOKEN>"
    -d "service=icloud" \
    -d "action=submit-2fa-challenge" \
    -d "code=<CODE>" \
    <TASK_SUBMISSION_ENDPOINT>

asapi将照常回复:

{ "retrieval_protocol": "aschannel",
  "stream": "<STREAM>",
  "success": true,
  "task_id": "<TASK_ID_X>"
}

检索端点将使用正常的登录消息进行回复:

{ "message": "Log-in successful",
  "auth_token": "ABCDEFGABCDEFGABCDEFGABCDEFGABCDEFGABCDEFGABCDEFGABCDEFG",
  "success": true
}

使用身份验证令牌刷新帐户登录名

ricloud提供身份验证令牌,用于刷新登录,而无需使用完整的iCloud凭据。令牌化机制的用户不需要持久保存任何用户凭证。

为此,客户端必须使用登录期间检索到的auth_token字段。必须将其发送到refresh-session服务操作端点。

$ curl \
    -X POST \
    -H "Authorization: Token <TOKEN>"
    -d "service=icloud" \
    -d "action=refresh-session" \
    -d "auth_token=<ICLOUD_AUTH_TOKEN>" \
    <TASK_SUBMISSION_ENDPOINT>

完成此操作后,可以对服务执行任何服务操作。

设备枚举

枚举设备: list-devices

一个登录到帐户,客户端可以枚举与iCloud帐户关联的设备和设备备份。这是通过对iCloud服务执行list-devices操作来完成的。

这与其他任何服务操作的完成方式相同。以下是此操作的curl请求示例。下面的<ACCOUNT>参数可以使用帐户ID填写,例如john.appleseed@reincubate.com

$ curl \
    -X POST \
    -H "Authorization: Token <TOKEN>"
    -d "service=icloud" \
    -d "action=list-devices" \
    -d "account=<ACCOUNT>" \
    <TASK_SUBMISSION_ENDPOINT>

asapi端点将以JSON格式回复:

{ "retrieval_protocol": "aschannel",
  "stream": "<STREAM>",
  "success": true,
  "task_id": "<TASK_ID_2>"
}

您的结果将很快显示在检索端点上。以下是一个示例响应:

{ "auth_token": "ABCDEFGABCDEFGABCDEFGABCDEFGABCDEFGABCDEFGABCDEFGABCDEFG",
  "devices": {
    "<DEVICE_ID_1>": {
      "ios_version": "10.0",
      "colour": "1",
      "device_name": "Johnny's iP7 iOS10 Black",
      "latest-backup": "2016-09-16 14:08:13.000000",
      "model": "D101AP",
      "serial": "ABC123AAAAAA",
      "name": "iPhone 7"
    },
    "<DEVICE_ID_2>": {
      "ios_version": "9.1",
      "colour": "#e1e4e3",
      "device_name": "Johnny's iPad",
      "latest-backup": "2016-11-16 16:36:33.000000",
      "model": "J98aAP",
      "serial": "ABC123BBBBBB",
      "name": "iPad Pro"
    },
    "<DEVICE_ID_3>": {
      "ios_version": "9.2.1",
      "colour": "#3b3b3c",
      "device_name": "Johnny's other iPhone",
      "latest-backup": "2016-06-16 16:00:49.000000",
      "model": "N49AP",
      "serial": "DFVDASDDSVAS",
      "name": "iPhone 5c"
    },
    "<DEVICE_ID_4>": {
      "ios_version": "9.0.2",
      "colour": "#e1e4e3",
      "device_name": "Johnny's white iPhone",
      "latest-backup": "2016-02-25 15:37:38.000000",
      "model": "N61AP",
      "serial": "HYTWGFHGHDSF",
      "name": "iPhone 6"
    }
  }
}

此响应包含指定帐户的iCloud会话的auth_token ,以及devices部分中与该帐户关联的设备列表。每个设备条目都包含以下键:

  • ios_version :设备的iOS版本
  • colour :设备的颜色为十六进制代码
  • device_name :用户设置的设备名称
  • latest-backup :设备上次备份到iCloud的日期
  • model :设备的型号
  • serial :设备的序列号
  • name :Apple公布的设备产品名称

请求Feed

检索Feed数据: fetch-data

fetch-data操作用于从API访问JSON数据的提要。它需要以下参数:

  • device :从或从中检索数据的设备
  • data :请求的Feed模块的CSV

可选参数是:

  • since :结果应该对应的时间段

下面是一个fetch-data动作示例。

$ curl \
    -X POST \
    -H "Authorization: Token <TOKEN>" \
    -d "service=icloud" \
    -d "action=fetch-data" \
    -d "account=<ACCOUNT>" \
    -d "device=<DEVICE_ID>" \
    -d "data=<FEED_MODULES>" \
    <TASK_SUBMISSION_ENDPOINT>

<FEED_MODULES> can be any of the feed modules listed in feed modules.

例如,使用上述命令中<FEED_MODULES>中的值sms ,可以在备份中访问SMS,MMS和iMessage。使用命令中的<FEED_MODULES>中的值sms,whatsapp_messages,snapchat_messages ,我们可以访问SMS,MMS和iMessages,WhatsApp消息和Snapchat消息,所有这些都在相同的JSON结果中。

asapi将回应:

{ "retrieval_protocol": "aschannel",
  "stream": "<STREAM>",
  "success": true,
  "task_id": "<TASK_ID_3>"
}

不久之后,结果将出现在具有相同task_id的结果端点上:

{ "sms": [
    { "group_handles": [
        "+441234567890",
        "renate@reincubate.com"
      ],
      "attachments": [],
      "deleted": false,
      "text": "Welcome to Vodafone!",
      "conversation_id": "vodafone",
      "from_me": false,
      "date": "2015-10-28 09:18:17.000000",
      "handle": "vodafone",
      "type": "SMS",
      "id": 6
    }
  ]
}

其他Feed模块提供可用于访问其他形式内容的信息。例如,对于给定设备,使用“photos”作为<FEED_MODULES>fetch-data操作将如下所示:

$ curl \
    -X POST \
    -H "Authorization: Token <TOKEN>" \
    -d "service=icloud" \
    -d "action=fetch-data" \
    -d "account=<ACCOUNT>" \
    -d "device=<DEVICE_ID>" \
    -d "data=photos" \
    <TASK_SUBMISSION_ENDPOINT>

将导致asapi回应:

{ "retrieval_protocol": "aschannel",
  "stream": "<STREAM>",
  "success": true,
  "task_id": "<TASK_ID_4>"
}

以下结果将显示在相应的端点上:

{ "photos": [{
    "file_path": "Media/DCIM/100APPLE/IMG_0001.PNG",
    "last_modified": "2016-10-05 10:24:03.000000",
    "file_id": "c8ada38b9acf7368c6347be1c353dc68ed2c7741",
    "filename": "IMG_0001.PNG"
  }, {
    "file_path": "Media/DCIM/100APPLE/IMG_0002.MOV",
    "last_modified": "2016-10-11 09:39:25.000000",
    "file_id": "5c3e35cc01689340a34d13d34a0591e2ed450e63",
    "filename": "IMG_0002.MOV"
  }]
}

JSON Feed格式

JSON提要旨在尽可能简单地解析。 Feed将返回单个响应中请求的所有数据类型。

模块标志中指定的每个feed模块在返回的顶级JSON字典中都有自己的密钥。

{
    "first_module_name": "Module's data",
    "second_module_name": "Module's data",
    "etc.": "etc."
}

请求原始文件

检索原始文件: download-file

download-file操作可直接从iCloud下载文件或邮件附件。所需的参数是目标<DEVICE_ID><FILE_ID>

某些Feed模块(包括file_list和photo模块)包含对可供下载的文件或附件的引用。它们包含用于标识和下载文件的<FILE_ID> ,以及一些额外的元数据,例如filenamefile_pathsizetype 。有关更多详细信息 ,请参阅信息提取器

命令

$ curl \
    -X POST \
    -H "Authorization: Token <TOKEN>" \
    -d "service=icloud" \
    -d "action=download-file" \
    -d "account=<ACCOUNT>" \
    -d "device=<DEVICE_ID>" \
    -d "file=<FILE_ID>" \
    <TASK_SUBMISSION_ENDPOINT>

asapi将回复:

{ "retrieval_protocol": "aschannel",
  "stream": "<STREAM>",
  "success": true,
  "task_id": "<TASK_ID_5>"
}

结果将在具有相同task_id的端点上出现后不久。

排除错误响应

一般错误回复

下表显示了任何操作可能引发的错误代码。

响应摘要
task-failed 未知的失败
deactivated-account 帐户已停用
deactivated-device 设备已停用
client-account-disabled API令牌已禁用
account-locked 帐户被锁定
account-credentials-blocked 帐户已锁定并受到保护
push-api-timeout 内部超时
icloud-unauthorised Apple会话超时
service-inactive-error 苹果服务没有初始化

未知的失败

登录任务失败,原因未知。如果使用此代码导致任务失败,客户应联系支持团队

帐户已停用

这表示已使用帐户停用管理命令停用该帐户。除非发送手动激活命令,否则无法访问它。

设备已停用

这表示已使用设备停用管理命令停用设备。除非发送手动激活命令,否则无法访问它。

API令牌已禁用

用于访问API的令牌已被禁用,请与支持团队联系。

内部超时

如果API会话在执行其他服务操作时到期,客户端将收到错误代码: push-api-timeout并且必须再次登录。

{ "message": "Unable to recover the session. Please re-login and try again",
  "error": "push-api-timeout"
}

iCloud未经授权

如果与Apple的会话之前已过期或在操作期间失效,则必须中止该操作,并且必须通过重新通过新log-in任务重新进行身份验证来重新建立会话。在这种情况下,使用refresh-session将不起作用,因为用于此调用的令牌与Apple现在已过期的会话相关联。

在某些情况下,会话可能会部分过期。例如, list-devices仍然返回有效的,最新的设备列表,但是fetch-dataicloud-unauthorised失败。在这种情况下,会话可以继续用于可访问的数据,但必须使用log-in任务进行完全刷新才能获得更多数据。

服务无效错误

如果API尝试初始化服务但收到Apple的响应,表明它尚未在用户的帐户上取消激活,则会返回此响应。请检查要查询的数据类型的相应设置,并确保它已激活并初始化。

登录错误响应

下表显示了除上述常规代码外, log-insubmit-2fa-challenge操作可能引发的错误代码。

响应摘要
unable-to-login 凭据不正确
2fa-required 需要2FA
invalid-2fa-code 无效的2FA代码
too-many-2fa-requests 2FA限速
account-locked 帐户被锁定
account-credentials-blocked 帐户已锁定并受到保护
terms-of-service-update-client 不接受服务条款
session-creation-error 会话初始化期间可恢复的错误
session-corrupt-error 会话初始化期间出现不可恢复的错误

凭据不正确

为帐户指定的凭据不正确,无法进行身份验证。

需要2FA

登录使用双因素身份验证(2FA)或两步验证(2SV)的帐户需要一些额外的步骤。请参阅下面的“2FA和2SV”部分。

无效的2FA代码

为响应2FA质询,发送了无效或其他错误的2FA代码。

2FA限速

最近为该帐户发送了太多2FA请求:它已受到速率限制。 30分钟后重试。

帐户被锁定

iCloud帐户已被Apple锁定。如果在短时间内再次尝试访问该帐户,则将返回account-credentials-blocked错误。

帐户已锁定并受到保护

iCloud帐户已被Apple锁定, ricloud已通过account-locked通知客户。此消息被替换为表示该服务未将请求转发给Apple。

不接受服务条款

在接受最新的iCloud条款和条件之前,iCloud帐户已被禁用。用户可以在他们的设备上或登录icloud.com接受这些。

会话创建错误

iCloud后端在会话初始化期间响应错误,但重试可能会解决问题并成功。

会话损坏错误

iCloud后端在会话初始化期间响应错误,重试不会导致不同的结果。请联系支持人员(最好使用帐户凭据),以便调查此边缘案例。

我们能帮你什么吗?

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

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

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

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

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