Quickstart in Python (v2)

bijgewerkt

Overzicht

De referentie Open Source bibliotheek van ricloud is geïmplementeerd in Python en gehost op GitHub.

De implementatie is gebundeld met documentatie en een voorbeeldscript dat laat zien hoe het kan worden gebruikt. Configuratie is beperkt tot het ~/.ricloud.ini een ~/.ricloud.ini configuratiebestand met het specificeren van een token voor verificatie ten opzichte van de API, evenals een eindpuntwaarde van de stream om de resultaten van de serviceactus te verzamelen.

Bron en documentatie voor deze bibliotheek zijn te vinden op GitHub .

Vereisten

De Ricloud-bibliotheek heeft heel weinig ontwerpvereisten. Het zou op de meeste systemen met Python 2.7 . Om de listenermodus te gebruiken , is er nog een vereiste voor MySQL 5.7 of hoger. Bekijk de voorbeeldclient in productie voor perspectieven op het gebruik van de Open Source-bibliotheek in productie.

Installatie

De ricloud- bibliotheek kan met één enkele opdracht worden geïnstalleerd:

$ pip install ricloud

Als u de luisteraarmodus wilt gebruiken met het automatisch dumpen van gegevens naar MySQL, moet het schemaconfiguratiescript worden toegepast op een lokale database. Dit kan worden gebruikt om het vereiste schema en de tabellen in de database te maken:

$ mysql -u root < sql/create_schema.sql

Configuratie

De API is afhankelijk van een reeks beveiligingsreferenties, die zijn opgeslagen in een ricloud.ini bestand. Dit pakket wordt geleverd met een standaardconfiguratiebestand dat beperkte toegang tot de API voor demonstratiedoeleinden mogelijk maakt.

De standaardreferenties kunnen worden overschreven door een override-bestand met de naam .ricloud.ini in de HOME map van de gebruiker. Als alternatief kan een omgevingsvariabele RICLOUD_CONF worden ingesteld, waarbij het volledige pad en de volledige bestandsnaam van het configuratiebestand worden 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

De standaard ricloud.ini is te vinden in deze repository .

Opdrachtregelparameters

De bibliotheek biedt een uitsplitsing van opdrachtregelargumenten als het --help -argument wordt doorgegeven:

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

Interactieve modus met asapi

De interactieve modus van de bibliotheek biedt een voorbeeld van hoe asapi kan worden gebruikt om toegang te krijgen tot een reeks datatypen op een manier die compatibel is met het 2FA-mechanisme van Apple.

Voer de volgende opdracht uit om het voorbeeldinteractiescript uit te voeren:

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

Manager-modus met asmaster

De ricloud- voorbeeldbibliotheek wordt geleverd met een opdrachtbeheerabonnement op opdrachtregel. Op deze manier kunnen klanten handmatig abonnementen beheren waar nodig, en laten ze zien hoe een productie-implementatie kan worden gebouwd.

Hier is een inleiding van hoe een gebruiker de beheermodus kan gebruiken. Ten eerste is het belangrijk dat er iets naar het kanaal luistert wanneer dit gebeurt .

Laten we zien welke abonnementen zijn geregistreerd:

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

Er zijn er geen. Laten we er een toevoegen. Men zou het onechte data-account kunnen toevoegen aan deze regel:

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

Laten we in plaats daarvan een echt account toevoegen dat wordt beschermd door 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"
}

Dit betekent dat john.appleseed@reincubate.com heeft toegewezen account_id van 133733 en een 2FA uitdaging voor die account nodig is:

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

Dit activeert de 2FA-prompt op de apparaten van de eindgebruiker en verstrekt een authenticatiecode. Laten we zeggen dat dat 123456 .

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

Dus de authenticatie is geslaagd en het account is geabonneerd. Dat betekent dat men een lijst kan maken met apparaten en deze kan abonneren. Laten we eens kijken welke beschikbaar zijn:

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

Laten we ook controleren welke apparaten zijn ingeschreven:

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

Dit toont aan dat geen van de apparaten is ingeschreven, dus we moeten er een onderschrijven.

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

Als deze stappen zijn voltooid, worden de gegevens van john.appleseed@reincubate.com en het gekozen apparaat automatisch naar het aschannel afgevouwen zodra het gereed is.

Als we twee keer proberen om zich op hetzelfde account te abonneren, wordt een dergelijke fout geretourneerd:

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

Luisteraarmodus met aschannel

De ricloud-luisteraar is een lokaal geïmplementeerd luistermechanisme voor de API. In wezen kunnen klanten een service installeren in hun eigen cloud of datacenter, die automatisch gegevens van de API invoegt in een lokale database en bestandssysteem.

De luisteraar ontkist automatisch gegevens van de API, voegt feedresultaten en metadata in een lokale database in en bewaart bestanden op het bestandssysteem. De luisteraar is Open Source en kan vrij worden gewijzigd door gebruikers. Er zijn veel strategieën die ermee kunnen worden gebruikt, inclusief het schrijven naar gedeelde bestandssysteemopslag of zelfs wijzigen om gegevens in te voegen in de productie-gegevensopslag van een klant.

Naast het schrijven van bestanden die het ontvangt op schijf, bevat de database van de luisteraar tabellen voor alle gegevens die eraan worden toegevoerd.

  • feed : JSON-gegevens en metagegevens van feedmodules worden hier opgeslagen
  • file : bestandsaanwijzers en metagegevens worden hier opgeslagen
  • message : Informatieve berichten worden hier opgeslagen
  • system : systeemberichten worden hier opgeslagen

Om de ontvangen gegevens te begrijpen en ernaar te handelen, is het belangrijk om deze tabellen regelmatig te scannen op nieuwe records. Het kan zijn dat de clienttoepassing eenvoudig rijen verwijdert die al zijn gelezen of geïmporteerd.

hardlopen

Het luisterproces kan worden gestart met de volgende opdracht:

$ python -m ricloud --listen

Berichten en systeemmeldingen interpreteren

Berichten en systeemmeldingen worden automatisch opgeslagen in twee tabellen: messages en system . Deze berichten worden opgeslagen nadat ze via de stream zijn verzonden. De meeste van deze berichten zijn louter informatief, maar sommige zijn kritiek.

berichten

  • Gebruikersfiche is verlopen; token vernieuwen vereist.
  • Gebruikersaccount vergrendeld; token vernieuwen vereist.
  • Andere fout bij toegang tot gegevens; geen actie nodig.

Systeem kennisgevingen

De meest voorkomende systeemberichten worden beschreven in systeemberichten . Ze geven eventuele problemen aan die blijven doorlezen uit de updates.

Toegang tot feedgegevens

De luisteraar slaat elke feed op die wordt ontvangen in de feed tabel. De belangrijkste velden zijn zoals hieronder:

  • received : de datum waarop de feed is opgehaald.
  • account_id : de account-ID die betrekking heeft op de feed.
  • device_id : de apparaat-ID die betrekking heeft op de feed.
  • body : de feed in JSON-indeling.

Bestanden ophalen

De luisteraar maakt een ingang in de database voor elk bestand dat het ontvangt en schrijft bestanden naar het bestandssysteem in de map output/files , relatief ten opzichte van het huidige pad van de uitvoerende 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

Bestanden krijgen alleen context door feedgegevens, dus de plaats om te beginnen is met een file_id verwezen door een file_id .

De file in de database heeft de volgende sleutelvelden:

  • received : de datum waarop het bestand is opgehaald.
  • account_id : de account-ID die bij het bestand hoort.
  • device_id : de apparaat-ID die bij het bestand device_id .
  • location : de locatie van het bestand op de schijf van de luisteraar.
  • file_id : de ID van het bestand.

De listener-database onderhouden

Geen van de listenertabellen bevat gegevens die essentieel zijn voor de werking van de luisteraar. Als de gegevens eenmaal zijn verbruikt door de clienttoepassing, kan de client de gegevens vrij wissen.

Evenzo kunnen de gedownloade bestanden op elk moment vrij worden verwijderd.

Hoe kunnen we helpen?

Ons ondersteuningsteam is er om u te helpen!

Onze kantooruren zijn van maandag tot vrijdag van 09.00 tot 17.00 uur GMT. De tijd is momenteel 7:36 AM GMT.

We streven ernaar om alle berichten binnen één werkdag te beantwoorden.

Ga naar het ondersteuningsgedeelte › Neem contact op met het Enterprise-team ›
Ons geweldige ondersteuningsteam

© 2008 - 2019 Reincubate Ltd. Alle rechten voorbehouden. Geregistreerd in Engeland en Wales #5189175, VAT GB151788978. Reincubate® is een geregistreerd handelsmerk. Privacy en voorwaarden. Wij bevelen 2FA aan. Gebouwd met in Londen.