Python快速入门(v2)

更新

概观

ricloud的参考开源库是用Python实现的,并托管在GitHub上。

该实现与文档和示例脚本捆绑在一起,该脚本显示了如何使用它。配置仅限于填充~/.ricloud.ini配置文件,并指定用于针对API进行身份验证的token以及用于收集服务操作结果的流端点值。

可以在GitHub上找到该库的源代码和文档。

要求

ricloud库的设计要求很少。它应该在Python 2.7大多数系统上运行。为了使用监听模式 ,还需要MySQL 5.7或更高版本。有关在生产中使用Open Source库的观点,请参阅生产中的示例客户端

安装

可以使用单个命令安装ricloud库:

$ pip install ricloud

要将侦听器模式与数据自动转储到MySQL,必须将架构配置脚本应用于本地数据库。这可用于在数据库中创建所需的模式和表:

$ mysql -u root < sql/create_schema.sql

组态

API依赖于一组安全凭证,这些凭据存储在ricloud.ini文件中。此软件包附带一个默认配置文件,该文件允许对API进行有限访问以进行演示。

可以通过在用户的HOME目录中创建名为.ricloud.ini的覆盖文件来覆盖默认凭据。或者,可以设置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示例库附带命令行订阅管理模式。这使客户可以根据需要手动管理订阅,并演示如何构建生产实现。

以下是用户如何使用管理员模式的演练。首先,重要的是,在执行此操作时,某些内容正在倾听。

让我们看看注册了什么订阅:

{ "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已被分配了一个133733account_id ,并且需要为该帐户提供2FA挑战:

$ 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如,当它准备好与所选择的设备将自动流下来aschannel。

如果我们尝试两次订阅同一个帐户,则会返回如下错误:

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

带有aschannel的监听模式

ricloud侦听器是API的本地部署侦听器机制。从本质上讲,它允许客户在自己的云或数据中心中安装服务,自动将从API接收的数据插入本地数据库和文件系统。

侦听器自动从API取消数据,将提要结果和元数据插入本地数据库,并将文件存储在文件系统上。监听器是开源的,可以由用户自由修改。可以使用许多策略,包括将其写入共享文件系统存储,甚至修改它以将数据插入客户端的生产数据存储。

除了将接收到的任何文件写入磁盘之外,侦听器的数据库还包含用于提供给它的所有数据的表。

  • feed :来自Feed模块的JSON数据和元数据存储在此处
  • file :文件指针和元数据存储在此处
  • message :信息性消息存储在此处
  • system :系统消息存储在此处

为了理解所接收的数据并对其采取行动,定期扫描这些表以获取新记录非常重要。客户端应用程序可能只是删除已读取或导入的行。

运行

可以使用以下命令启动侦听器进程:

$ python -m ricloud --listen

解释消息和系统通知

消息和系统通知自动存储在两个表中: messagessystem 。这些消息在通过流发送后存储。大多数这些消息纯粹是信息性的,但有些是至关重要的。

消息

  • 用户令牌已过期;需要令牌刷新。
  • 用户帐户被锁定;需要令牌刷新。
  • 访问数据的其他错误;无需任何操作。

系统通知

最常见的系统消息在系统消息中描述。它们将指示继续从流中读取的任何问题。

访问Feed数据

监听器将其接收的每个馈送存储在feed表中。关键领域如下:

  • received :检索Feed的日期。
  • account_id :与Feed相关的帐户ID。
  • device_id :与Feed相关的设备ID。
  • body :JSON格式的feed。

检索文件

侦听器在数据库中为它接收的每个文件创建一个条目,并将文件写入output/files夹中的文件系统,相对于执行shell的当前路径。

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

文件仅由Feed数据提供上下文,因此开始的位置是使用Feed条目引用的file_id

数据库中的file表具有以下关键字段:

  • received :检索文件的日期。
  • account_id :与文件有关的帐户ID。
  • device_id :与文件有关的设备ID。
  • location :侦听器磁盘上文件的位置。
  • file_id :文件的ID。

维护侦听器数据库

任何侦听器表都没有任何对侦听器工作至关重要的数据。因此,一旦客户端应用程序使用了数据,客户端就可以自由地删除数据。

同样,下载的文件可以随时自由删除。

我们能帮你什么吗?

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

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

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

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

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