Сервис Apple iCloud (версия 2)

обновленный

Служба icloud API icloud предоставляет функциональные возможности для доступа к информации, хранящейся в iCloud, как в пакетном режиме из резервных копий устройств iOS, так и в режиме реального времени и в режиме реального времени из других источников. API поддерживает доступ к iCloud с момента его первоначального выпуска.

Клиенту может потребоваться выполнить четыре основных операции со службой iCloud.

  • Аутентификация: log-in , perform-2fa-challenge , submit-2fa-challenge
  • list-devices : list-devices
  • Запрашиваемые фиды: fetch-data
  • Запрос необработанных файлов: download-file

Работа с фиктивными данными из API

Чтобы помочь в разработке интеграций с API, предоставляется фиктивная учетная запись, заполненная набором богатых данных. Это позволяет клиентам тестировать многие функции API ricloud без необходимости работать с реальными пользовательскими данными.

Ложная учетная запись называется Jonny Appleseed и доступна с помощью идентификатора учетной записи iCloud john.appleseed@reincubate.com и пароля joshua .

Аутентификация

Вход в log-in : log-in

Первый шаг к взаимодействию с icloud - вход в систему.

Для запроса необходимо указать:

  • service для взаимодействия с: icloud
  • action для выполнения: log-in
  • Параметр account , представляющий идентификатор учетной записи iCloud, например, 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>"
}

Если вы подключены к правильной точке stream_endpoint в конечной точке aschannel , вы увидите, что результат совпадает с <TASK_ID_1> вы получили от конечной точки asapi .

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

Результаты будут включать параметр success который будет иметь значение true, если задача входа в систему выполнена успешно, а также сообщение и токен проверки подлинности Apple для использования с другими действиями службы.

Устранение неполадок при входе

Пожалуйста, смотрите раздел об ответах на ошибки входа в систему для определения ошибок и решений.

2FA и 2SV

После попытки войти в учетную запись iCloud, для которой настроено 2SV или 2FA, произойдет сбой обычного входа в систему и будет возвращено сообщение об ошибке, подобное приведенному ниже.

{ "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 список trustedDevices будет содержать одно или несколько устройств. Клиенты должны выбрать устройство в списке для вызова.

Это делается путем выполнения perform-2fa-challenge с challenge установленным для ключа выбранного устройства от trustedDevices .

Для двухфакторной аутентификации (2FA)

В случае 2FA, список trustedDevices будет установлен на ["Challenge all 2FA devices"] 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"

Асапи ответит как обычно:

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

Конечная точка поиска ответит:

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

Как только запрос отправлен на устройство пользователя, двухфакторный код должен быть возвращен обратно в API с помощью submit-2fa-challenge . В приведенном ниже запросе <CODE> - это числовой код, предоставленный конечным пользователем, который представляет коды, переданные на устройство для входа в систему 2FA / 2SV.

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

Асапи ответит как обычно:

{ "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. Это делается путем выполнения действия list-devices со службой iCloud.

Это делается так же, как и любое другое действие службы. Вот пример запроса curl для этого действия. Приведенный ниже параметр <ACCOUNT> может быть заполнен идентификатором учетной записи, например 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"
    }
  }
}

Этот ответ содержит auth_token для сеанса iCloud указанной учетной записи, а также список устройств, связанных с этой учетной записью, в разделе devices . Каждая запись устройства содержит следующие ключи:

  • ios_version : версия iOS для устройства
  • colour : colour устройства в виде шестнадцатеричного кода
  • device_name : имя устройства, заданное пользователем
  • latest-backup : дата последнего резервного копирования устройства в iCloud
  • model : номер модели устройства
  • serial : серийный номер устройства
  • name : name продукта устройства, рекламируемого Apple

Запрос каналов

Извлечение данных фида: fetch-data

Действие fetch-data используется для доступа к каналам данных JSON из API. Требуются следующие параметры:

  • device : устройство для получения данных от или о
  • data : 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.

Например, используя значение sms в <FEED_MODULES> в приведенной выше команде, можно получить доступ к SMS, MMS и iMessages в резервной копии. Используя значение sms,whatsapp_messages,snapchat_messages в <FEED_MODULES> в команде, мы можем получить доступ к SMS, MMS и iMessages, сообщениям WhatsApp и Snapchat, все в одном и том же результате JSON.

Асапи ответит:

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

Другие модули подачи предоставляют информацию, которую можно использовать для доступа к другим формам контента. Например, действие fetch-data с использованием 'photos' в качестве <FEED_MODULES> для данного устройства будет выглядеть так:

$ 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

Каналы JSON разработаны так, чтобы их было максимально просто проанализировать. Фид вернет все типы данных, запрошенные в одном ответе.

Каждый модуль канала, указанный в флаге модуля, будет иметь свой собственный ключ в словаре JSON верхнего уровня, который возвращается.

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

Запрос необработанных файлов

Извлечение raw-файлов: download-file

Действие download-file доступно для загрузки файлов или вложений сообщений непосредственно из iCloud. Необходимыми параметрами являются цель <DEVICE_ID> и <FILE_ID> .

Некоторые из модулей каналов, включая file_list и photo, содержат ссылки на файлы или вложения, доступные для загрузки. Они содержат <FILE_ID> используемый для идентификации и загрузки файла, и часто некоторые дополнительные метаданные, такие как filename , file_path , size и type . Пожалуйста, ознакомьтесь с экстракторами информации для более подробной информации.

Команда

$ 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>

Асапи ответит:

{ "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 Сервис Apple не инициализирован

Неизвестный сбой

Задача входа не выполнена, и причина была неизвестна. В случае сбоя задачи с этим кодом клиенты должны связаться со службой поддержки .

Аккаунт деактивирован

Это означает, что учетная запись была деактивирована с помощью команды управления деактивацией учетной записи. Он не будет доступен, пока не будет отправлена команда активации вручную.

Устройство отключено

Это означает, что устройство было деактивировано с помощью команды управления деактивацией устройства. Он не будет доступен, пока не будет отправлена команда активации вручную.

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-data не выполняется с icloud-unauthorised . В этом случае сеанс можно продолжать использовать для доступных данных, но его необходимо полностью обновить с помощью задачи log-in в log-in , чтобы получить дополнительные данные.

Ошибка неактивного сервиса

Этот ответ возвращается, если API попытался инициализировать службу, но получил ответ от Apple, который указывает, что он не был деактивирован в учетной записи пользователя. Проверьте соответствующую настройку для запрашиваемого типа данных и убедитесь, что он активирован и инициализирован.

Ответы об ошибках входа

В следующей таблице приведены коды ошибок, которые могут вызывать действия log-in в log-in и submit-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:00 до 17:00 по Гринвичу. Время в настоящее время 6:02 ДП с GMT.

Мы стремимся отвечать на все сообщения в течение одного рабочего дня.

Перейти в раздел поддержки › Связаться с командой предприятия ›
Наша отличная команда поддержки

© 2008 - 2019 Reincubate Ltd. Все права защищены. Зарегистрировано в Англии и Уэльсе #5189175, VAT GB151788978. Reincubate® является зарегистрированным товарным знаком. Защита & Условия. Мы рекомендуем 2FA. Построен с в Лондоне.