Начиная

обновленный

Чтобы начать использовать API ricloud v3 , сначала необходимо связаться с вами, чтобы настроить свою организацию. Как только это будет завершено, у вас должен быть ваш начальный key_token который предоставит вам доступ к API.

Вызовы API в этом разделе выполняются с использованием cURL, но их можно легко заменить эквивалентными вызовами из ricloud-py .

Просмотр вашей организации

Сначала мы кратко рассмотрим вашу организацию.

curl 'https://ricloud-api.reincubate.com/organisation' \
  -H 'Authorization: Token <your key_token>'

Вы должны увидеть ответ, аналогичный приведенному ниже. Если вы получите ответ HTTP 401, проверьте значение key_token в заголовке Authorization .

{
    "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_configs и storage_config_default пусты, так как мы еще не настроили их.
  • webhook_configs и webhook_config_default также пусты по той же причине.
  • state не unconfigured что отражает отсутствие допустимых конфигов хранилища.

Мы вернемся к этапам настройки позже, так как это не мешает вам получать доступ к службам через 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": "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>"
  }
}'

Ответ будет содержать ресурс сеанса, который первоначально будет находиться в состоянии pending то время как API проходит процесс настройки связи со сторонней службой. В этом случае мы получаем доступ к 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 для более подробной информации о том, что пошло не так.

В случае, если в вашей учетной записи включено 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 Cloud Storage и Amazon S3 (AWS) , которые необходимо настроить через конфигурацию хранилища, принадлежащую вашей организации. Следуйте инструкциям, приведенным в документации по настройке хранилища, чтобы получить собственную корзину, готовую для использования с API.

Создать опрос для данных

Простейший набор данных для извлечения из iCloud - это некоторая базовая информация об учетной записи. Все, что нужно, это идентификатор активного сеанса и некоторые спецификаторы для данных, которые вы хотите восстановить.

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 данных callkit.calls , но ваш ключ может иметь разрешения для разных типов данных, или вы можете быть заинтересованы в получении данных другого типа, просто замените их при необходимости.

Это вернет ресурс опроса. В фоновом режиме API также создал задачу, которая будет выполнять фактическую работу, необходимую для извлечения этой информации (ранее была также создана задача для настройки нашей сессии). Идентификатор задачи можно увидеть под атрибутом tasks .

{
  "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 , который на данный момент пуст. Здесь мы начнем видеть идентификаторы данных, опубликованных из задачи.

Теперь мы хотим подождать, пока обработка не будет завершена и состояние опроса установлено как 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:00 до 17:00 по Гринвичу. Время в настоящее время 4:12 ПП с GMT.

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

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

Можем ли мы улучшить эту статью?

Нам нравится слышать от пользователей: почему бы не написать нам электронное письмо, оставить комментарий или написать в Твиттере @reincubate?

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