Быстрый старт в Python (v2)

обновленный

обзор

Справочная библиотека с открытым исходным кодом ricloud реализована на Python и размещена на GitHub.

Реализация связана с документацией и примером сценария, который показывает, как его можно использовать. Конфигурация ограничивается ~/.ricloud.ini файла конфигурации ~/.ricloud.ini указанием token для аутентификации по API, а также значением конечной точки потока для сбора результатов действия службы.

Исходный код и документацию для этой библиотеки можно найти на GitHub .

Требования

У библиотеки ricloud очень мало требований к дизайну. Он должен работать на большинстве систем с Python 2.7 . Для использования режима слушателя есть дополнительное требование MySQL 5.7 или выше. Смотрите пример использования клиента в производстве, чтобы узнать, как использовать библиотеку с открытым исходным кодом в работе.

Монтаж

Библиотека ricloud может быть установлена с помощью одной команды:

$ pip install ricloud

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

$ mysql -u root < sql/create_schema.sql

конфигурация

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

.ricloud.ini данные по умолчанию можно переопределить, создав файл переопределения с именем .ricloud.ini в .ricloud.ini пользователя HOME . Кроме того, можно установить переменную окружения RICLOUD_CONF , указав полный путь и имя файла конфигурации.

[mysql]
# Database config is only needed for listen mode.
host = 127.0.0.1
port = 3306
database = ricloud
username = your-ricloud-mysql-user-here
password = your-ricloud-mysql-password-here

[hosts]
api_host = https://asapi.reincubate.com
asmaster_host = https://asmaster.reincubate.com
stream_host = https://aschannel.reincubate.com

[endpoints]
account_information = /account/
register_account = /register-account/
task_status = /task-status/
result_consumed = /results-consumed/

[asmaster_endpoints]
list_services = /list-services/
list_subscriptions = /list-subscriptions/
subscribe_account = /subscribe-account/
perform_2fa_challenge = /perform-2fa-challenge/
submit_2fa_challenge = /submit-2fa-challenge/
list_devices = /list-devices/
subscribe_device = /subscribe-device/
resubscribe_account = /resubscribe-account/
unsubscribe_device = /unsubscribe-device/
unsubscribe_account = /unsubscribe-account/

[stream]
# This value provided by Reincubate.
stream_endpoint = your-aschannel-stream-name-here

[auth]
# This value provided by Reincubate.
token = your-ricloud-api-access-token-here

[output]
output_directory = output

[logging]
logs_directory = logs
time_profile = False
level = WARNING

[performance]
object_store_greenlets = 50

В этом репозитории можно найти ricloud.ini умолчанию.

Параметры командной строки

Библиотека предоставляет разбивку аргументов командной строки, если передан аргумент --help :

$ python -m ricloud --help
ricloud API Client.

Usage, interactive mode:
    ricloud <account> [--password=<password>] [--timeout=<timeout>]

Options, interactive mode:
    -h --help               Show this screen.
    --timeout=<timeout>     How long should we wait for tasks to complete, in seconds. (default: 600s or 10 minutes)
    --password=<password>   The password for this account.

Usage, manager mode:
    ricloud --list-subscriptions <service> [--timeout=<timeout>]
    ricloud --subscribe-account <username> <password> <service> [--timeout=<timeout>]
    ricloud --perform-2fa-challenge <account_id> <device_id> [--timeout=<timeout>]
    ricloud --submit-2fa-challenge <account_id> <code> [--timeout=<timeout>]
    ricloud --resubscribe-account <account_id> <password> [--timeout=<timeout>]
    ricloud --unsubscribe-account <account_id> [--timeout=<timeout>]
    ricloud --list-devices <account_id> [--timeout=<timeout>]
    ricloud --subscribe-device <account_id> <device_id> [--timeout=<timeout>]
    ricloud --unsubscribe-device <account_id> <device_id> [--timeout=<timeout>]

Options, manager mode:
    -h --help               Show this screen.
    --timeout=<timeout>     How long should we wait for tasks to complete, in seconds. (default: 600s or 10 minutes)

Usage, listener mode:
    ricloud --listen [--timeout=<timeout>]

Options, listener mode:
    -h --help               Show this screen.
    --timeout=<timeout>     How long should we wait for tasks to complete, in seconds. (default: 600s or 10 minutes)

Интерактивный режим с Asapi

Интерактивный режим библиотеки предоставляет пример того, как asapi можно использовать для доступа к ряду типов данных способом, совместимым с механизмом Apple 2FA.

Чтобы запустить пример интерактивного сценария, выполните следующую команду:

$ python -m ricloud john.appleseed@reincubate.com --password=joshua

Режим менеджера с asmaster

Библиотека примеров ricloud поставляется с режимом управления подпиской в командной строке. Это позволяет клиентам вручную управлять подписками, где это необходимо, и демонстрирует, как можно реализовать производственную реализацию.

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

Давайте посмотрим, какие подписки зарегистрированы:

{ "services": [{
    "name": "iCloud",
    "actions": [{
      "description": "",
      "parameters": [{
        "type": "string",
        "description": "",
        "optional": false,
        "name": "Device",
        "slug": "device"
      }, {
        "type": "date",
        "description": "",
        "optional": true,
        "name": "Since",
        "slug": "since"
      }],
      "name": "Fetch Data",
      "execution": "Asynchronous",
      "slug": "fetch-data",
      "permissions": {
        "data": ["sms"]
      }
    }],
    "slug": "icloud"
  }],
  "stream_endpoints": [{
    "host": "aschannel.reincubate.com",
    "protocol": "https",
    "uri": "/stream/"
  }]
}
python -m ricloud --list-subscriptions icloud
{u'accounts': [], u'success': True}

Там нет ни одного. Давайте добавим один. Можно добавить фиктивную учетную запись с помощью этой строки:

$ python -m ricloud --subscribe-account john.appleseed@reincubate.com joshua icloud

Вместо этого давайте добавим реальную учетную запись, защищенную 2FA:

$ python -m ricloud --subscribe-account john.appleseed@reincubate.com "xxxx" icloud
{
  "message": "This account has Multi Factor Authentication enabled, please select a device to challenge.",
  "data": {
    "trusted_devices": [
      "Challenge all 2FA devices"
    ]
  },
  "account_id": 133733,
  "success": false,
  "error": "2fa-required"
}

Это означает, что john.appleseed@reincubate.com был назначен account_id 133733 , и для этой учетной записи требуется вызов 133733 :

$ python -m ricloud --perform-2fa-challenge 133733 0
{u'message': u'Challenge has been submitted.', u'success': True}

Это вызывает приглашение 2FA на устройствах конечного пользователя, предоставляя код аутентификации. Допустим, это 123456 .

$ python -m ricloud --submit-2fa-challenge 133733 123456
{u'account_id': 133733, u'success': True}

Итак, аутентификация прошла успешно, и аккаунт подписан. Это означает, что можно перечислить и подписаться на устройства. Посмотрим, какие есть в наличии:

$ python -m ricloud --list-devices 133733
{u'devices': [
  {u'ios_version': u'10.2', u'name': u'iPhone 7 Plus', u'colour': u'1', u'device_name': u'Johnny\'s iP7 iOS10 Black', u'latest-backup': u'2017-01-31 22:06:06.000000', u'model': u'D111AP', u'device_tag': u'3d0d7e5fb2ce288813306e4d4636395e047a3d28', u'serial': u'ABC123AAAAAA', u'device_id': 2},
  {u'ios_version': u'10.3.1', u'name': u'iPad Pro', u'colour': u'#e4e7e8', u'device_name': u'Johnny\'s iPad', u'latest-backup': u'2017-04-22 15:39:25.000000', u'model': u'J127AP', u'device_tag': u'b39bac0d347adfaf172527f97c3a5fa3df726a3a', u'serial': u'ABC123BBBBBB', u'device_id': 3},
  {u'ios_version': u'10.3.1', u'name': u'iPhone 7 Plus', u'colour': u'1', u'device_name': u'Johnny\'s other iPhone', u'latest-backup': u'2017-04-13 21:08:47.000000', u'model': u'D111AP', u'device_tag': u'a49bfab36504be1bf563c1d1813b05efd6076717', u'serial': u'DFVDASDDSVAS', u'device_id': 4}
], u'success': True}

Давайте также проверим, какие устройства подписаны:

$ python -m ricloud --list-subscriptions
{
  "accounts": [
    {
      "status": "ok",
      "service": "icloud",
      "account_id": 133733,
      "devices": [
        {
          "status": "ok",
          "device_id": 2
        },
        {
          "status": "ok",
          "device_id": 3
        },
        {
          "status": "ok",
          "device_id": 4
        }
      ]
    }
  ]
}

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

$ python -m ricloud --subscribe-device 133733 2
{u'account_id': 133733, u'device_id': 2, u'success': True}

После выполнения этих действий данные с john.appleseed@reincubate.com и выбранного устройства будут автоматически передаваться по каналу по мере готовности.

Если мы попытаемся подписаться на одну и ту же учетную запись дважды, будет возвращена ошибка, подобная этой:

$ python -m ricloud --subscribe-account john.appleseed@reincubate.com josha icloud
{
  "message": "You are already subscribed to receive content for this account.",
  "account_id": 133733,
  "success": false,
  "error": "asmaster-account-already-active"
}

Режим прослушивания с каналом

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

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

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

  • feed : здесь хранятся данные JSON и метаданные из модулей feed
  • file : Файловые указатели и метаданные хранятся здесь
  • message : здесь хранятся информационные сообщения
  • system : здесь хранятся системные сообщения

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

Бег

Процесс слушателя может быть запущен с помощью следующей команды:

$ python -m ricloud --listen

Интерпретация сообщений и системных уведомлений

Сообщения и системные уведомления автоматически сохраняются в двух таблицах: messages и system . Эти сообщения сохраняются после отправки через поток. Большинство из этих сообщений носят исключительно информационный характер, но некоторые являются критическими.

Сообщения

  • Срок действия токена пользователя истек; требуется обновление токена.
  • Учетная запись пользователя заблокирована; требуется обновление токена.
  • Другая ошибка доступа к данным; Никаких действий не требуется.

Системные уведомления

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

Доступ к данным канала

Слушатель сохраняет каждый полученный feed таблице feed . Ключевые поля как ниже:

  • received : дата получения канала.
  • account_id : идентификатор учетной записи, относящейся к каналу.
  • device_id : идентификатор устройства, относящийся к device_id .
  • body : канал в формате JSON.

Получение файлов

Слушатель создает запись в базе данных для каждого получаемого файла и записывает файлы в файловую систему в папке output/files относительно текущего пути исполняющей оболочки.

mysql> SELECT id, received, account_id, device_id, location, file_id FROM file LIMIT 1000;
+----+---------------------+------------+-----------+--------------------------------------+---------+
| id | received            | account_id | device_id | location                             | file_id |
+----+---------------------+------------+-----------+--------------------------------------+---------+
|  1 | 2017-04-14 15:38:39 |       NULL |      NULL | 91f49a4f-3368-4350-ae90-a944d4652fbe |         |
|  2 | 2017-04-14 15:38:40 |       NULL |      NULL | 9b0381b6-244d-4d82-8198-57798d89a379 |         |
|  3 | 2017-04-14 15:38:41 |       NULL |      NULL | b9ccd1ed-8d80-4b33-be99-a3a7f1af73ce |         |
|  4 | 2017-04-14 15:38:42 |       NULL |      NULL | b3666148-a17e-4ca8-90db-975e1850a72b |         |
+----+---------------------+------------+-----------+--------------------------------------+---------+
4 rows in set (0.00 sec)
$ ls -l output/files
-rw-r--r-- 1 renate 1143 Apr 14 13:47 91f49a4f-3368-4350-ae90-a944d4652fbe
-rw-r--r-- 1 renate 2866 Apr 14 14:09 9b0381b6-244d-4d82-8198-57798d89a379
-rw-r--r-- 1 renate 2866 Apr 14 15:18 b9ccd1ed-8d80-4b33-be99-a3a7f1af73ce
-rw-r--r-- 1 renate 1143 Apr 14 13:49 b3666148-a17e-4ca8-90db-975e1850a72b

Файлы задаются контекстом только по данным канала, поэтому начинать нужно с file_id ссылается запись канала.

Таблица file в базе данных имеет следующие ключевые поля:

  • received : дата получения файла.
  • account_id : идентификатор учетной записи, относящейся к файлу.
  • device_id : идентификатор устройства, относящийся к файлу.
  • location : местоположение файла на диске слушателя.
  • file_id : идентификатор файла.

Ведение базы данных слушателей

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

Точно так же загруженные файлы могут быть свободно удалены в любое время.

Как мы можем помочь?

Наша служба поддержки здесь, чтобы помочь!

Наш офис работает с понедельника по пятницу с 9:00 до 17:00 по Гринвичу. Время в настоящее время 3:19 ПП с GMT.

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

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

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