Начиная
Чтобы начать использовать ricloud API, сначала нужно связаться с вами, чтобы настроить вашу организацию. Как только это будет завершено, у вас должен быть ваш начальный 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": { "data": [], "has_more": false, "total_count": 0, "url": "/configs/storage" }, "storage_config_default": null, "webhook_configs": { "data": [], "has_more": false, "total_count": 0, "url": "/configs/webhook" }, "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 и системой 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": "<user ID from previous request>", "type": "icloud.account", "identifier": "<iCloud account username>" }, "payload": { "password": "<iCloud account password>" } }'
Ответ будет содержать ресурс сеанса, который первоначально будет находиться в состоянии pending пока API проходит процесс настройки связи со сторонней службой.
{ "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 на одном из ваших устройств iOS, подключенных к учетной записи. Просто выполните вызов из шага (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": "<user ID from previous request>", "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.
Если у вас есть конфигурация хранилища, вы можете попытаться восстановить свою организацию снова. Теперь state должно быть active , а не unconfigured .
Создать опрос для данных
Чтобы создать опрос, нам нужно предоставить только идентификатор активного сеанса и некоторые данные о данных или файлах, которые мы хотим получить.
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", "payload": { "data_types": ["icpl.photos"], } }'
Обратите внимание, что в приведенном выше вызове мы запрашиваем icpl.photos данных icpl.photos . Вас может заинтересовать получение данных другого типа, или у вас могут не быть разрешения для этого типа данных, в частности. Подставьте это значение по необходимости.
Это вернет ресурс опроса, state в state pending или processing . В фоновом режиме API также создал задачу, которая будет выполнять фактическую работу, необходимую для извлечения этой информации (ранее была также создана задача для настройки нашего сеанса).
{ "id": "f1447e76-59f1-486b-942f-6b90e3570c63", "resource": "poll", "organisation": "1", "key": "1", "user": "1", "source": "1", "session": "ed855b07-f72b-4983-ac1d-980fafee8a0b", "tasks_pending": [], "tasks_processing": ["6bdb82ad-28bf-4aad-ab2c-b4952a7aa3eb"], "tasks_completed": [], "results": { "data": [], "has_more": false, "total_count": 0, "url": "/polls/f1447e76-59f1-486b-942f-6b90e3570c63/results" }, "errors": { "data": [], "has_more": false, "total_count": 0, "url": "/polls/f1447e76-59f1-486b-942f-6b90e3570c63/errors" }, "state": "processing", "date_created": "2018-11-22T14:20:52.211618Z", "date_started": "2018-11-22T14:20:52.731838Z", "date_completed": null }
Обратите внимание на атрибут results , который на данный момент пуст. Здесь мы увидим ссылки на любые данные или файлы, опубликованные в этом опросе. Результаты публикуются по мере их появления, поэтому их можно получить до завершения всего опроса.
Как только все запрошенные данные и файлы будут опубликованы в вашем хранилище, состояние опроса изменится на completed .
Получить информацию о результате
Это делается путем просмотра атрибута 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", "tasks_pending": [], "tasks_processing": [], "tasks_completed": ["6bdb82ad-28bf-4aad-ab2c-b4952a7aa3eb"], "results": { "data": [ { "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 } ], "has_more": false, "total_count": 0, "url": "/polls/f1447e76-59f1-486b-942f-6b90e3570c63/results" }, "errors": { "data": [], "has_more": false, "total_count": 0, "url": "/polls/f1447e76-59f1-486b-942f-6b90e3570c63/errors" }, "state": "completed", "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 запускаются автоматически либо в результате внешних триггеров, таких как приложение Reincubate Relay, для поиска новых данных, либо из-за подписки. В этих случаях API необходим способ сообщить вашей системе, что произошли изменения или что опубликованы новые данные, о которых вам следует знать.
Для этого API использует уведомления webhook. Прежде чем API сможет начать их отправку, и прежде чем вы сможете начать использовать службу Reincubate Relay или подписки, ваша организация должна быть настроена с допустимой конфигурацией webhook. Следуйте руководству по настройке webhook для более подробной информации.
