Inicio rápido en Python (v2)

Actualizado

Visión general

La biblioteca de código abierto de referencia de ricloud se implementa en Python y se hospeda en GitHub.

La implementación se incluye con documentación y una secuencia de comandos de muestra que muestra cómo se puede utilizar. La configuración se limita a ~/.ricloud.ini un archivo de configuración ~/.ricloud.ini con la especificación de un token para la autenticación en la API, así como un valor de punto final de flujo para recopilar los resultados de la acción de servicio.

La fuente y la documentación de esta biblioteca se pueden encontrar en GitHub .

Requerimientos

La biblioteca de ricloud tiene muy pocos requisitos de diseño. Debería ejecutarse en la mayoría de los sistemas con Python 2.7 . Para usar el modo de escucha, hay un requisito adicional de MySQL 5.7 o superior. Consulte el uso del cliente de muestra en producción para obtener perspectivas sobre el uso de la biblioteca de código abierto en producción.

Instalación

La biblioteca de ricloud se puede instalar con un solo comando:

$ pip install ricloud

Para usar el modo de escucha con volcado automático de datos a MySQL, el script de configuración del esquema debe aplicarse a una base de datos local. Esto se puede usar para crear el esquema y las tablas requeridas en la base de datos:

$ mysql -u root < sql/create_schema.sql

Configuración

La API se basa en un conjunto de credenciales de seguridad, que se almacenan en un archivo ricloud.ini . Este paquete se entrega con un archivo de configuración predeterminado que permite el acceso limitado a la API con fines de demostración.

Las credenciales predeterminadas se pueden anular creando un archivo de anulación denominado .ricloud.ini en el directorio de HOME del usuario. Alternativamente, se puede establecer una variable de entorno RICLOUD_CONF , especificando la ruta completa y el nombre de archivo del archivo de configuración.

[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

El ricloud.ini predeterminado se puede encontrar en este repositorio .

Parámetros de línea de comando

La biblioteca proporciona un desglose de los argumentos de la línea de comandos si se pasa el argumento --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)

Modo interactivo con asapi

El modo interactivo de la biblioteca proporciona un ejemplo de cómo se puede usar asapi para acceder a una variedad de tipos de datos de una manera que es compatible con el mecanismo 2FA de Apple.

Para ejecutar el script interactivo de muestra, ejecute el siguiente comando:

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

Modo administrador con asmaster

La biblioteca de muestra de ricloud se envía con un modo de administración de suscripción de línea de comandos. Esto permite a los clientes administrar suscripciones manualmente cuando sea necesario, y demuestra cómo se puede construir una implementación de producción.

A continuación se explica cómo un usuario puede usar el modo administrador. En primer lugar, es importante que algo esté escuchando un canal al hacer esto.

Veamos que suscripciones están registradas:

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

No hay ninguno. Vamos a añadir uno. Uno podría agregar la cuenta de datos simulados con esta línea:

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

En su lugar, agreguemos una cuenta real que esté protegida por 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"
}

Esto significa que a john.appleseed@reincubate.com se le ha asignado un account_id de 133733 , y se necesita un desafío 2FA para esa cuenta:

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

Esto activa el indicador de 2FA en los dispositivos del usuario final, proporcionando un código de autenticación. Digamos que es 123456 .

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

Así que la autenticación ha sido exitosa, y la cuenta está suscrita. Eso significa que uno puede enumerar y suscribirse a dispositivos. Veamos cuales están 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}

Veamos también qué dispositivos están suscritos:

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

Esto muestra que ninguno de los dispositivos se ha suscrito, por lo que debemos suscribirnos a uno.

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

Con estos pasos completos, los datos de john.appleseed@reincubate.com y el dispositivo elegido fluirán automáticamente hacia abajo de un canal cuando esté listo.

Si intentamos suscribirnos a la misma cuenta dos veces, se devolverá un error como este:

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

Modo de escucha con un canal

El escucha de ricloud es un mecanismo de escucha implementado localmente para la API. Esencialmente, permite a los clientes instalar un servicio en su propia nube o centro de datos que inserta automáticamente los datos recibidos de la API en una base de datos y sistema de archivos local.

El oyente automáticamente descarta los datos de la API, inserta resultados de alimentación y metadatos en una base de datos local y almacena los archivos en el sistema de archivos. El oyente es Open Source y los usuarios pueden modificarlo libremente. Hay muchas estrategias que se pueden usar con él, incluso hacer que escriba en el almacenamiento del sistema de archivos compartido o incluso modificarlo para insertar datos en el almacén de datos de producción de un cliente.

Además de escribir los archivos que recibe en el disco, la base de datos del oyente tiene tablas para todos los datos que se le suministran.

  • feed : los datos JSON y los metadatos de los módulos de feed se almacenan aquí
  • file : los punteros y metadatos del archivo se almacenan aquí.
  • message : los mensajes informativos se almacenan aquí
  • system : los mensajes del sistema se almacenan aquí

Para comprender y actuar sobre los datos que se reciben, es importante escanear regularmente estas tablas en busca de nuevos registros. Puede ser que la aplicación cliente simplemente elimine las filas que ya ha leído o importado.

Corriendo

El proceso de escucha se puede iniciar con el siguiente comando:

$ python -m ricloud --listen

Interpretación de mensajes y avisos del sistema.

Los mensajes y avisos del sistema se almacenan automáticamente en dos tablas: messages y system . Estos mensajes se almacenan después de ser enviados a través de la secuencia. La mayoría de estos mensajes son puramente informativos, pero algunos son críticos.

Mensajes

  • El token de usuario ha caducado; actualización de token requerida.
  • Cuenta de usuario bloqueada; actualización de token requerida.
  • Otro error al acceder a los datos; no se requiere accion.

Avisos del sistema

Los mensajes del sistema más comunes se describen en los mensajes del sistema . Ellos indicarán cualquier problema que continúe leyendo de la transmisión.

Acceso a los datos de alimentación

El oyente almacena cada feed que recibe en la tabla de feed . Los campos clave son los siguientes:

  • received : la fecha en que se recuperó el feed.
  • account_id : el ID de cuenta correspondiente a la fuente.
  • device_id : el ID del dispositivo que pertenece a la fuente.
  • body : El feed en formato JSON.

Recuperando archivos

El oyente crea una entrada en la base de datos para cada archivo que recibe y escribe los archivos en el sistema de archivos en la carpeta de output/files , en relación con la ruta actual del shell en ejecución.

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

A los archivos solo se les da contexto por los datos del feed, por lo que el lugar para comenzar es con un file_id referenciado por una entrada del feed.

La tabla de file en la base de datos tiene los siguientes campos clave:

  • received : la fecha en que se recuperó el archivo.
  • account_id : el ID de cuenta correspondiente al archivo.
  • device_id : el ID del dispositivo que pertenece al archivo.
  • location : la ubicación del archivo en el disco del oyente.
  • file_id : El ID del archivo.

Mantener la base de datos de oyentes

Ninguna de las tablas de escucha tiene datos que sean críticos para el funcionamiento del escucha. En consecuencia, una vez que los datos han sido consumidos por la aplicación cliente, el cliente puede eliminar los datos libremente.

Del mismo modo, los archivos descargados se pueden eliminar libremente en cualquier momento.

¿Cómo podemos ayudar?

¡Nuestro equipo de soporte está aquí para ayudar!

Nuestro horario de atención es de lunes a viernes de 9 a.m. a 5 p.m. GMT. El tiempo es actualmente 11:30 AM GMT.

Intentamos responder todos los mensajes en un plazo de un día laboral.

Ir a la sección de soporte › Póngase en contacto con el equipo de la empresa. ›
Nuestro increíble equipo de soporte.

© 2008 - 2019 Reincubate Ltd. Todos los derechos reservados. Registrado en Inglaterra y Gales #5189175, VAT GB151788978. Reincubate® es una marca registrada. Términos y privacidad. Recomendamos la autenticación de múltiples factores. Construido con en Londres.