Pour commencer

Mis à jour

Pour commencer à utiliser l'API ricloud v3 , vous devez tout d'abord prendre contact pour configurer votre organisation. Une fois cette opération terminée, vous devriez avoir votre key_token initial qui vous donnera 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": [],
    "storage_config_default": null,
    "webhook_configs": [],
    "webhook_config_default": null,
    "state": "unconfigured",
    "date_created": "2018-11-22T12:59:57.016467Z"
}

Ici vous pouvez voir quelques informations sur votre organisation:

  • permissions affiche les autorisations de base pour votre organisation.
  • storage_configs et storage_config_default sont vides car nous n’avons pas encore défini de configuration.
  • webhook_configs et webhook_config_default sont également vides pour la même raison.
  • state n'est pas unconfigured ce qui reflète l'absence de unconfigured de 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 le cas d'une source de compte iCloud, l'API devra se connecter au compte pour créer la session entre elle-même et le service iCloud d'Apple.

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": "1",
    "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 suit le processus de configuration des communications avec le service tiers. Dans ce cas, nous obtenons un accès à iCloud.

{
  "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 , une erreur s'est produite lors du processus d'initialisation. Vérifiez la valeur de l'attribut error pour plus de détails sur ce qui n'a pas fonctionné.

Dans le cas où 2FA est activé sur votre compte, l'erreur rencontrée risque fort de nécessiter du code-required et le processus 2FA vous aura été demandé sur l'un de vos appareils. Il suffit de faire à nouveau l’appel de l’étape (1), mais cette fois-ci 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": "1",
    "type": "icloud.account",
    "identifier": "<iCloud account username>"
  },
  "payload": {
    "password": "<iCloud account password>"
    "code": "<2FA code>"
  }
}'

Si une autre erreur survient, veuillez consulter la section erreurs pour plus de détails.

Une fois l'état active la session est prête à être utilisée pour extraire des données et des 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, ce qui nous amène à l'étape suivante.

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.

Créer un sondage pour les données

L'ensemble de données le plus simple à récupérer à partir d'iCloud est constitué d'informations de base sur le compte. Tout ce dont vous avez besoin est l’ID d’une session active et certains spécificateurs pour les données que vous souhaitez 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",
  "type": "data",
  "payload": {
    "data_types": ["callkit.calls"],
  }
}'

Notez que, dans l'appel ci-dessus, nous avons spécifié le type de données callkit.calls , mais votre clé peut disposer d'autorisations pour différents types de données ou vous souhaitez peut-être extraire un type de données différent, remplacez-le si nécessaire.

Cela renverra une ressource de sondage. En arrière-plan, l'API a également créé une tâche qui effectuera le travail nécessaire pour extraire ces informations (une tâche a également été créée pour configurer notre session plus tôt). L'ID de la tâche peut être vu sous l'attribut tasks .

{
  "id": "f1447e76-59f1-486b-942f-6b90e3570c63",
  "resource": "poll",
  "organisation": "1",
  "key": "1",
  "user": "1",
  "source": "1",
  "session": "ed855b07-f72b-4983-ac1d-980fafee8a0b",
  "type": "data",
  "tasks_pending": [],
  "tasks_processing": ["6bdb82ad-28bf-4aad-ab2c-b4952a7aa3eb"],
  "tasks_completed": [],
  "results": [],
  "state": "processing",
  "date_created": "2018-11-22T14:20:52.211618Z",
  "date_started": "2018-11-22T14:20:52.731838Z",
  "date_completed": null
}

Notez également l'attribut results , qui est vide à ce stade. C'est ici que nous allons commencer à voir les identifiants des données publiées à partir de la tâche.

Nous souhaitons maintenant attendre que le traitement soit terminé et que l'état du sondage soit défini sur succeeded .

Récupérer les informations sur les résultats

Cela se fait facilement en regardant 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",
  "type": "data",
  "tasks_pending": [],
  "tasks_processing": [],
  "tasks_completed": ["6bdb82ad-28bf-4aad-ab2c-b4952a7aa3eb"],
  "results": [
    {
      "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
    }
  ],
  "state": "processing",
  "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, à la suite de déclencheurs externes tels qu'une instance asrelay recherchant de nouvelles données ou suite à une interrogation planifiée. Dans ces cas, l'API a besoin d'un moyen d'indiquer à votre système que des modifications ont eu lieu ou que de nouvelles données ont été publiées, dont vous devez être au courant.

Pour ce faire, l’API utilise les notifications Webhook. Avant que l'API puisse commencer à les envoyer et avant que vous puissiez commencer à utiliser le service asrelay ou des scrutations planifiées, votre organisation doit être configurée avec une configuration Webhook valide. Suivez le guide sur la configuration de Webhook pour plus de détails.

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 8:02 Après-midi 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

Pouvons-nous améliorer cet article?

Nous aimons entendre les utilisateurs: pourquoi ne pas nous envoyer un email, laisser un commentaire ou tweet @reincubate?

© 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.