Início rápido em Python (v2)

Atualizada

visão global

A biblioteca de código aberto de referência do ricloud é implementada em Python e hospedada no GitHub.

A implementação é fornecida com documentação e um script de amostra que mostra como ela pode ser usada. A configuração é limitada ao preenchimento de um arquivo de configuração ~/.ricloud.ini com a especificação de um token para autenticação na API, bem como um valor de ponto de extremidade de fluxo para coletar os resultados da ação de serviço.

A fonte e a documentação desta biblioteca podem ser encontradas no GitHub .

Requisitos

A biblioteca ricloud tem muito poucos requisitos por design. Ele deve ser executado na maioria dos sistemas com o Python 2.7 . Para usar o modo ouvinte, existe um requisito adicional do MySQL 5.7 ou superior. Veja usando o cliente de amostra em produção para obter perspectivas sobre o uso da biblioteca Open Source em produção.

Instalação

A biblioteca ricloud pode ser instalada com um único comando:

$ pip install "ricloud<3"

Para usar o modo listener com o descarregamento automático de dados para o MySQL, o script de configuração do esquema deve ser aplicado a um banco de dados local. Isso pode ser usado para criar o esquema e as tabelas necessárias no banco de dados:

$ mysql -u root < sql/create_schema.sql

Configuração

A API depende de um conjunto de credenciais de segurança, que são armazenadas em um arquivo ricloud.ini . Este pacote é fornecido com um arquivo de configuração padrão que permite acesso limitado à API para fins de demonstração.

As credenciais padrão podem ser substituídas, criando um arquivo de substituição denominado .ricloud.ini no diretório HOME do usuário. Como alternativa, uma variável de ambiente RICLOUD_CONF pode ser definida, especificando o caminho completo e o nome do arquivo de configuração.

[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

O ricloud.ini padrão pode ser encontrado neste repositório .

Parâmetros de linha de comando

A biblioteca fornece um detalhamento dos argumentos da linha de comando se passar pelo 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 interativo com asapi

O modo interativo da biblioteca fornece um exemplo de como o asapi pode ser usado para acessar uma variedade de tipos de dados de uma maneira compatível com o mecanismo 2FA da Apple.

Para executar o script interativo de amostra, execute o seguinte comando:

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

Modo gerente com asmaster

A biblioteca de amostras ricloud é fornecida com um modo de gerenciamento de assinatura da linha de comandos. Isso permite que os clientes gerenciem manualmente as assinaturas quando necessário e demonstrem como uma implementação de produção pode ser construída.

Aqui está uma explicação de como um usuário pode usar o modo gerenciador. Em primeiro lugar, é importante que algo está ouvindo aschannel ao fazer isto.

Vamos ver quais assinaturas estão 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}

Não há nenhum. Vamos adicionar um. Pode-se adicionar a conta de dados simulada com esta linha:

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

Em vez disso, vamos adicionar uma conta real 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"
}

Isso significa que john.appleseed@reincubate.com recebeu um account_id de 133733 e um desafio 2FA para essa conta é necessário:

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

Isso aciona o prompt 2FA nos dispositivos do usuário final, fornecendo um código de autenticação. Digamos que seja 123456 .

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

Portanto, a autenticação foi bem-sucedida e a conta está inscrita. Isso significa que é possível listar e assinar dispositivos. Vamos ver quais estão disponíveis:

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

Vamos também verificar quais dispositivos estão inscritos:

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

Isso mostra que nenhum dos dispositivos foi inscrito, por isso devemos assinar um.

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

Com estes passos completa, os dados do john.appleseed@reincubate.com e o dispositivo escolhido irá fluir automaticamente aschannel como e quando ele está pronto.

Se tentarmos assinar a mesma conta duas vezes, um erro como este será retornado:

$ 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 ouvinte com aschannel

O listener do ricloud é um mecanismo de escuta implantado localmente para a API. Essencialmente, ele permite que os clientes instalem um serviço em sua própria nuvem ou datacenter, que insere automaticamente os dados recebidos da API em um banco de dados local e sistema de arquivos.

O ouvinte dechunks automaticamente os dados da API, insere resultados de feed e metadados em um banco de dados local e armazena arquivos no sistema de arquivos. O ouvinte é Open Source e pode ser modificado livremente pelos usuários. Existem muitas estratégias que podem ser usadas com ele, incluindo que ele grave no armazenamento compartilhado do sistema de arquivos ou até mesmo modifique-o para inserir dados no armazenamento de dados de produção de um cliente.

Além de gravar todos os arquivos que recebe no disco, o banco de dados do ouvinte possui tabelas para todos os dados que são alimentados para ele.

  • feed : os dados JSON e os metadados dos módulos de feed são armazenados aqui
  • file : Os ponteiros e metadados do arquivo são armazenados aqui
  • message : mensagens informativas são armazenadas aqui
  • system : mensagens do sistema são armazenadas aqui

Para entender e agir sobre os dados sendo recebidos, é importante verificar regularmente essas tabelas para novos registros. Pode ser que o aplicativo cliente simplesmente exclua linhas já lidas ou importadas.

Corrida

O processo do listener pode ser iniciado com o seguinte comando:

$ python -m ricloud --listen

Interpretando mensagens e avisos do sistema

Mensagens e avisos do sistema são armazenados automaticamente em duas tabelas: messages e system . Essas mensagens são armazenadas depois de serem enviadas pelo fluxo. A maioria dessas mensagens é puramente informativa, mas algumas são críticas.

Mensagens

  • O token do usuário expirou; atualização de token necessária.
  • Conta de usuário bloqueada; atualização de token necessária.
  • Outro erro ao acessar dados; Nenhuma ação é requerida.

Avisos do sistema

As mensagens mais comuns do sistema são descritas nas mensagens do sistema . Eles indicarão qualquer problema ao continuar lendo o fluxo.

Acessando dados do feed

O ouvinte armazena cada feed recebido na tabela de feed . Os campos-chave são como abaixo:

  • received : a data em que o feed foi recuperado.
  • account_id : o ID da conta referente ao feed.
  • device_id : o ID do dispositivo relativo ao feed.
  • body : o feed no formato JSON.

Recuperando Arquivos

O listener cria uma entrada no banco de dados para cada arquivo que recebe e grava arquivos no sistema de arquivos na pasta output/files , relativa ao caminho atual do shell de execução.

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

Os arquivos só recebem contexto por dados de feed, portanto, o local a ser iniciado é com um file_id referenciado por uma entrada de feed.

A tabela de file no banco de dados possui os seguintes campos-chave:

  • received : A data em que o arquivo foi recuperado.
  • account_id : o ID da conta referente ao arquivo.
  • device_id : o ID do dispositivo relativo ao arquivo.
  • location : a localização do arquivo no disco do ouvinte.
  • file_id : o ID do arquivo.

Mantendo o banco de dados do ouvinte

Nenhuma das tabelas do listener possui nenhum dado nelas que seja crítico para o funcionamento do listener. Consequentemente, uma vez que os dados foram consumidos pelo aplicativo cliente, o cliente pode excluir os dados livremente.

Da mesma forma, os arquivos baixados podem ser excluídos livremente a qualquer momento.

Como podemos ajudar?

Nossa equipe de suporte está aqui para ajudar!

Nosso horário de atendimento é de segunda a sexta, das 9h às 17h GMT. A hora é atualmente 7:36 AM GMT.

Nosso objetivo é responder a todas as mensagens dentro de um dia útil.

Vá para a seção de apoio › Entre em contato com a equipe da empresa ›
Nossa equipe de suporte incrível

© 2008 - 2019 Reincubate Ltd. Todos os direitos reservados. Registrado na Inglaterra e no País de Gales #5189175, VAT GB151788978. Reincubate® é uma marca registrada. Privacidade e Termos. Recomendamos 2FA. Construído com em Londres.