Démarrage rapide en Python (v2)

Mis à jour

Vue d'ensemble

La bibliothèque Open Source de référence de ricloud est implémentée en Python et hébergée sur GitHub.

L'implémentation est fournie avec la documentation et un exemple de script qui montre comment l'utiliser. La configuration se limite à ~/.ricloud.ini un fichier de configuration ~/.ricloud.ini avec la spécification d'un token d'authentification sur l'API, ainsi qu'une valeur de point de terminaison de flux pour collecter les résultats de l'action de service.

La source et la documentation de cette bibliothèque sont disponibles sur GitHub .

Exigences

La bibliothèque ricloud a très peu d'exigences de par sa conception. Il devrait fonctionner sur la plupart des systèmes avec Python 2.7 . Pour utiliser le mode écouteur, MySQL 5.7 ou supérieur est requis. Reportez-vous à l'utilisation de l'exemple de client en production pour connaître les perspectives d'utilisation de la bibliothèque Open Source en production.

Installation

La bibliothèque ricloud peut être installée avec une seule commande:

$ pip install ricloud

Pour utiliser le mode écouteur avec vidage automatique des données vers MySQL, le script de configuration du schéma doit être appliqué à une base de données locale. Ceci peut être utilisé pour créer le schéma et les tables requis dans la base de données:

$ mysql -u root < sql/create_schema.sql

Configuration

L'API repose sur un ensemble d'informations d'identification de sécurité, qui sont stockées dans un fichier ricloud.ini . Ce package est livré avec un fichier de configuration par défaut qui permet un accès limité à l'API à des fins de démonstration.

Les informations d' identification par défaut peuvent être remplacées en créant un fichier de remplacement nommé .ricloud.ini dans l'utilisateur HOME répertoire. Vous pouvez également définir une variable d'environnement RICLOUD_CONF , en spécifiant le chemin complet et le nom du fichier du fichier de configuration.

[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

Le ricloud.ini par défaut se trouve dans ce référentiel .

Paramètres de ligne de commande

La bibliothèque fournit une ventilation des arguments de ligne de commande si l'argument --help est passé:

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

Mode interactif avec asapi

Le mode interactif de la bibliothèque fournit un exemple d'utilisation d' Asapi pour accéder à une gamme de types de données de manière compatible avec le mécanisme 2FA d'Apple.

Pour exécuter l'exemple de script interactif, exécutez la commande suivante:

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

Mode Manager avec asmaster

La bibliothèque exemple ricloud est livrée avec un mode de gestion des abonnements en ligne de commande. Cela permet aux clients de gérer manuellement les abonnements, le cas échéant, et montre comment une implémentation de production peut être construite.

Voici un aperçu de la manière dont un utilisateur peut utiliser le mode gestionnaire. Tout d' abord, il est important que quelque chose écoute aschannel lors de cette opération .

Voyons quels abonnements sont enregistrés:

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

Il n'y en a pas. Ajoutons un. On pourrait ajouter le compte de données fictif avec cette ligne:

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

Au lieu de cela, ajoutons un compte réel protégé par 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"
}

Cela signifie que john.appleseed@reincubate.com s'est vu attribuer un account_id de 133733 et qu'un défi 2FA est requis pour ce compte:

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

Cela déclenche l'invite 2FA sur les périphériques de l'utilisateur final, fournissant un code d'authentification. Disons que c'est 123456 .

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

Donc, l'authentification a réussi et le compte est abonné. Cela signifie que l’on peut lister et souscrire à des appareils. Voyons quels sont disponibles:

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

Voyons également quels appareils sont abonnés:

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

Cela montre qu'aucun des périphériques n'a été souscrit, nous devrions donc en souscrire à un.

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

Ces étapes terminées, les données provenant de john.appleseed@reincubate.com et du périphérique choisi seront automatiquement acheminées vers le canal au fur et à mesure de leur disponibilité.

Si nous essayons de souscrire deux fois au même compte, une erreur comme celle-ci sera renvoyée:

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

Mode auditeur avec aschannel

L'écouteur ricloud est un mécanisme d'écoute déployé localement pour l'API. Il permet essentiellement aux clients d’installer un service dans leur propre cloud ou centre de données, qui insère automatiquement les données reçues de l’API dans une base de données et un système de fichiers locaux.

L'écouteur déchiffre automatiquement les données de l'API, insère les résultats de flux et les métadonnées dans une base de données locale et stocke les fichiers sur le système de fichiers. L'écouteur est Open Source et peut être librement modifié par les utilisateurs. De nombreuses stratégies peuvent être utilisées avec cette application, notamment l'écriture dans un stockage de système de fichiers partagé ou même sa modification pour insérer des données dans le magasin de données de production d'un client.

En plus d'écrire tous les fichiers qu'il reçoit sur le disque, la base de données du programme d'écoute contient des tables pour toutes les données qui lui sont fournies.

  • feed : les données et métadonnées JSON des modules de feed sont stockées ici
  • file : les pointeurs et métadonnées de fichier sont stockés ici
  • message : les messages d'information sont stockés ici
  • system : les messages système sont stockés ici

Afin de comprendre les données reçues et d’agir sur celles-ci, il est important d’analyser régulièrement ces tables à la recherche de nouveaux enregistrements. Il se peut que l'application client supprime simplement les lignes déjà lues ou importées.

Fonctionnement

Le processus d'écoute peut être démarré avec la commande suivante:

$ python -m ricloud --listen

Interprétation des messages et des avis système

Les messages et les avis système sont automatiquement stockés dans deux tableaux: messages et system . Ces messages sont stockés après avoir été envoyés via le flux. La plupart de ces messages sont purement informatifs, mais certains sont critiques.

messages

  • Le jeton utilisateur a expiré; l'actualisation du jeton est requise.
  • Compte d'utilisateur verrouillé; l'actualisation du jeton est requise.
  • Autre erreur lors de l'accès aux données; Aucune action nécessaire.

Avis système

Les messages système les plus courants sont décrits dans les messages système . Ils indiqueront tout problème persistant lors de la lecture du flux.

Accéder aux données de flux

L'écouteur stocke chaque flux qu'il reçoit dans la table de feed . Les champs clés sont les suivants:

  • received : date à laquelle le flux a été récupéré.
  • account_id : l'ID de compte account_id au flux.
  • device_id : l'ID de périphérique correspondant au flux.
  • body : le flux au format JSON.

Récupérer des fichiers

L'écouteur crée une entrée dans la base de données pour chaque fichier qu'il reçoit et écrit les fichiers sur le système de fichiers dans le dossier de output/files , par rapport au chemin actuel du shell en cours d'exécution.

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

Les fichiers ne sont mis en contexte que par les données de flux, il est donc file_id de commencer par un file_id référencé par une entrée de flux.

La table de file dans la base de données contient les champs de clé suivants:

  • received : date à laquelle le fichier a été récupéré.
  • account_id : l'ID de compte appartenant au fichier.
  • device_id : l'ID de périphérique correspondant au fichier.
  • location : emplacement du fichier sur le disque de l'auditeur.
  • file_id : l'ID du fichier.

Maintenir la base de données de l'auditeur

Aucune des tables du programme d'écoute ne contient des données essentielles au fonctionnement du programme. Par conséquent, une fois que les données ont été consommées par l'application cliente, le client peut supprimer librement les données.

De même, les fichiers téléchargés peuvent être librement supprimés à tout moment.

Comment pouvons nous aider?

Notre équipe de support est là pour vous aider!

Nos bureaux sont ouverts du lundi au vendredi, de 9 h à 17 h GMT. L’heure est actuellement 1:54 Matin GMT.

Notre objectif est de répondre à tous les messages en un jour ouvrable.

Aller à la section support › Contacter l'équipe de l'entreprise ›
Notre superbe équipe de support

© 2008 - 2019 Reincubate Ltd. Tous droits réservés. Enregistré en Angleterre et au Pays de Galles #5189175, VAT GB151788978. Reincubate® est une marque déposée. Confidentialité et modalités. Nous recommandons l'authentification multi-facteurs. Construit avec à Londres.