Pour commencer
Pour commencer à utiliser l'API ricloud, vous devez d'abord entrer en contact pour configurer votre organisation. Une fois cela terminé, vous devriez avoir votre key_token initial qui vous accordera l'accès à l'API.
Les appels d'API dans cette section sont effectués à l'aide de cURL, mais ils peuvent facilement être remplacés par des appels équivalents à partir de ricloud-py .
Voir votre organisation
Dans un premier temps, nous examinerons rapidement votre organisation.
curl 'https://ricloud-api.reincubate.com/organisation' \ -H 'Authorization: Token <your key_token>'
Vous devriez voir une réponse similaire à celle ci-dessous. Si vous obtenez une réponse HTTP 401, vérifiez la valeur key_token que vous avez fournie dans l'en-tête Authorization .
{ "id": 1, "resource": "organisation", "name": "Getting started", "slug": "getting-started", "permissions": { "id": 1, "resource": "organisation_permissions", "identifier": "default", "scopes": { "source_type:icloud.*": [], "task_type:*": [], "data_type:icloud.account.info": [], }, "date_created": "2018-11-22T12:59:57.168354Z" }, "storage_configs": { "data": [], "has_more": false, "total_count": 0, "url": "/configs/storage" }, "storage_config_default": null, "webhook_configs": { "data": [], "has_more": false, "total_count": 0, "url": "/configs/webhook" }, "webhook_config_default": null, "state": "unconfigured", "date_created": "2018-11-22T12:59:57.016467Z" }
Ici vous pouvez voir quelques informations sur votre organisation:
-
permissionsaffiche les autorisations de base pour votre organisation. -
storage_configsetstorage_config_defaultsont vides car nous n’avons pas encore défini de configuration. -
webhook_configsetwebhook_config_defaultsont également vides pour la même raison. -
staten'est pasunconfiguredce qui reflète l'absence deunconfiguredde stockage valide.
Nous reviendrons sur les étapes de configuration ultérieurement, car cela ne vous empêche pas d'accéder aux services via l'API.
Maintenant que nous avons confirmé que votre organisation est opérationnelle, essayons d'accéder à un compte iCloud.
Mise en place d'une session
Une session représente l'accès à une source. Dans ce cas, notre source sera un compte iCloud et la création d'une session "se connectera" effectivement au compte. La session se chargera ensuite de garder une trace de la connexion entre l'API et le système iCloud pour les demandes futures.
Créer un utilisateur
Avant de pouvoir configurer une session, un utilisateur doit être créé pour définir l'utilisateur final qui souhaite accéder à la source. Cela facilite la gestion de session et la sécurité des données sur l'API.
curl 'https://ricloud-api.reincubate.com/users' \ -X POST \ -H 'Authorization: Token <your key_token>' \ -H 'Content-Type: application/json' \ -d '{ "identifier": "<some identifier for the user your system will recognise>" }'
La réponse contiendra l'ID utilisateur requis lors du prochain appel.
{ "id": "1", "resource": "user", "organisation": "1", "key": "1", "identifier": "<your user identifier>", "state": "active", "date_created": "2018-11-22T13:49:37.215516Z" }
Créer une session
curl 'https://ricloud-api.reincubate.com/sessions' \ -X POST \ -H 'Authorization: Token <your key_token>' \ -H 'Content-Type: application/json' \ -d '{ "source": { "user": "<user ID from previous request>", "type": "icloud.account", "identifier": "<iCloud account username>" }, "payload": { "password": "<iCloud account password>" } }'
La réponse contiendra une ressource de session, qui sera initialement dans l'état en pending pendant que l'API passe par le processus de configuration des communications avec le service tiers.
{ "id": "ed855b07-f72b-4983-ac1d-980fafee8a0b", "resource": "session", "organisation": "1", "user": "1", "source": "1", "state": "pending", "error": null, "date_created": "2018-11-22T13:50:12.628776Z", "date_expired": null }
Vous pouvez vérifier l'état de la session via l'appel de récupération.
curl 'https://ricloud-api.reincubate.com/sessions/ed855b07-f72b-4983-ac1d-980fafee8a0b' \ -H 'Authorization: Token <your key_token>'
Si l'état failed , quelque chose s'est mal passé pendant le processus d'initialisation. Vérifiez la valeur de l'attribut error pour plus de détails. Si 2FA est activé sur votre compte - et que votre mot de passe est correct - l'erreur rencontrée est probablement liée au code-required . Un code 2FA vous sera demandé sur l'un de vos appareils iOS connectés au compte. Faites simplement l'appel à partir de l'étape (1) à nouveau, mais cette fois en incluant le code 2FA dans la charge utile.
curl 'https://ricloud-api.reincubate.com/sessions' \ -X POST \ -H 'Authorization: Token <your key_token>' \ -H 'Content-Type: application/json' \ -d '{ "source": { "user": "<user ID from previous request>", "type": "icloud.account", "identifier": "<iCloud account username>" }, "payload": { "password": "<iCloud account password>", "code": "<2FA code>" } }'
Si une autre erreur s'est produite, veuillez consulter la section des erreurs pour plus d'informations.
Une fois que l'état devient active la session est prête à être utilisée pour récupérer les données et les fichiers de la source.
Cependant, comme nous l'avons vu précédemment, votre organisation n'est pas encore configurée pour recevoir ces données.
Récupérer des données et des fichiers
Avant que l'API puisse commencer à extraire des données d'une source, elle doit savoir où elle doit publier les données. L'API prend actuellement en charge la publication vers des compartiments de stockage Google Cloud Storage et Amazon S3 (AWS) , qui doivent être configurés via une configuration de stockage appartenant à votre organisation. Suivez les étapes décrites dans la documentation d' installation de la configuration de stockage pour préparer votre propre compartiment et l'utiliser avec l'API.
Une fois que vous avez une configuration de stockage, vous pouvez essayer de récupérer à nouveau votre organisation. L' state devrait maintenant être active , plutôt que unconfigured .
Créer un sondage pour les données
Pour créer un sondage, tout ce que nous devons fournir est l'ID d'une session active et quelques détails sur les données ou les fichiers que nous voulons récupérer.
curl https://ricloud-api.reincubate.com/polls \ -X POST \ -H 'Authorization: Token <your key_token>' \ -H 'Content-Type: application/json' \ -d '{ "session": "ed855b07-f72b-4983-ac1d-980fafee8a0b", "payload": { "data_types": ["icpl.photos"], } }'
Notez que dans l'appel ci-dessus, nous demandons le type de données icpl.photos . Vous pourriez être intéressé par la récupération d'un autre type de données, ou ne pas avoir d'autorisations pour ce type de données en particulier. Remplacez cette valeur si nécessaire.
Cela renverra une ressource d'interrogation, avec l' state en pending ou en pending processing . En arrière-plan, l'API a également créé une tâche qui effectuera le travail réel requis pour récupérer ces informations (une tâche a également été créée pour configurer notre session plus tôt).
{ "id": "f1447e76-59f1-486b-942f-6b90e3570c63", "resource": "poll", "organisation": "1", "key": "1", "user": "1", "source": "1", "session": "ed855b07-f72b-4983-ac1d-980fafee8a0b", "tasks_pending": [], "tasks_processing": ["6bdb82ad-28bf-4aad-ab2c-b4952a7aa3eb"], "tasks_completed": [], "results": { "data": [], "has_more": false, "total_count": 0, "url": "/polls/f1447e76-59f1-486b-942f-6b90e3570c63/results" }, "errors": { "data": [], "has_more": false, "total_count": 0, "url": "/polls/f1447e76-59f1-486b-942f-6b90e3570c63/errors" }, "state": "processing", "date_created": "2018-11-22T14:20:52.211618Z", "date_started": "2018-11-22T14:20:52.731838Z", "date_completed": null }
Notez l'attribut results , qui est vide à ce stade. C'est là que nous verrons apparaître des références pour toutes les données ou fichiers publiés à partir de ce sondage. Les résultats sont publiés dès qu'ils sont disponibles, de sorte qu'ils peuvent être récupérés avant la fin du sondage.
Une fois que toutes les données et tous les fichiers demandés ont été publiés sur votre stockage, l'état du sondage passera à completed .
Récupérer les informations sur les résultats
Cela se fait en examinant l'attribut results du sondage.
curl 'https://ricloud-api.reincubate.com/polls/f1447e76-59f1-486b-942f-6b90e3570c63' \ -H 'Authorization: Token <your key_token>'
La réponse contiendra les informations dont nous avons besoin.
{ "id": "f1447e76-59f1-486b-942f-6b90e3570c63", "resource": "poll", "organisation": "1", "key": "1", "user": "1", "source": "1", "session": "ed855b07-f72b-4983-ac1d-980fafee8a0b", "tasks_pending": [], "tasks_processing": [], "tasks_completed": ["6bdb82ad-28bf-4aad-ab2c-b4952a7aa3eb"], "results": { "data": [ { "id": "754cfef0-7576-44c0-acfe-8b0d8d0dd32f", "resource": "result", "task": "6bdb82ad-28bf-4aad-ab2c-b4952a7aa3eb", "identifier": "data:info.account", "url": "<your storage config url>", "checksum": "2668324d21a20301ce71c28bc5e621d4", "size": 12345, "state": "available", "date_created": "2018-11-22T14:20:53.506542Z", "date_consumed": null, "date_deleted": null } ], "has_more": false, "total_count": 0, "url": "/polls/f1447e76-59f1-486b-942f-6b90e3570c63/results" }, "errors": { "data": [], "has_more": false, "total_count": 0, "url": "/polls/f1447e76-59f1-486b-942f-6b90e3570c63/errors" }, "state": "completed", "date_created": "2018-11-22T14:20:52.211618Z", "date_started": "2018-11-22T14:20:52.731838Z", "date_completed": "2018-11-22T14:20:53.548372Z" }
L'attribut url du résultat pointe vers le fichier stocké dans votre compartiment.
Réception d'événements Webhook
Certaines fonctionnalités de l'API sont déclenchées automatiquement, soit à la suite de déclencheurs externes tels qu'une application Reincubate Relay trouvant de nouvelles données ou en raison d'un abonnement. Dans ces cas, l'API a besoin d'un moyen de dire à votre système que des changements sont survenus ou que de nouvelles données ont été publiées dont vous devez être conscient.
Pour ce faire, l'API utilise des notifications de webhook. Avant que l'API puisse commencer à les envoyer et avant de pouvoir utiliser le service Reincubate Relay ou les abonnements, votre organisation doit être configurée avec une configuration de webhook valide. Suivez le guide sur la configuration du webhook pour plus de détails.
