Ermee beginnen
Om de ricloud API te gaan gebruiken, moet je eerst contact opnemen om je organisatie in te richten. Zodra dit is voltooid, moet u uw eerste key_token waarmee u toegang krijgt tot de API.
De API-oproepen in deze sectie worden uitgevoerd met behulp van cURL, maar deze kunnen eenvoudig worden vervangen door equivalente oproepen van ricloud-py .
Uw organisatie bekijken
Eerst zullen we snel naar uw organisatie kijken.
curl 'https://ricloud-api.reincubate.com/organisation' \ -H 'Authorization: Token <your key_token>'
Je zou een reactie moeten zien die lijkt op die hieronder. Als u een HTTP 401-antwoord key_token controleert u de key_token waarde die u hebt key_token in de 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" }
Hier kunt u informatie over uw organisatie bekijken:
-
permissionsgeeft de basisrechten voor uw organisatie weer. -
storage_configsenstorage_config_defaultzijn leeg omdat we nog geen instellingen moeten instellen. -
webhook_configsenwebhook_config_defaultzijn ook om dezelfde reden leeg. -
stateis nietunconfiguredwat het gebrek aan geldige opslagconfiguren weerspiegelt.
We komen later terug naar configuratiestappen, omdat dit u er niet van weerhoudt toegang te krijgen tot services via de API.
Nu we hebben bevestigd dat uw organisatie actief is, laten we proberen toegang tot een iCloud-account te krijgen.
Een sessie opzetten
Een sessie vertegenwoordigt toegang tot een bron. In dit geval is onze bron een iCloud-account en het aanmaken van een sessie zal effectief "inloggen" op het account. De sessie zorgt vervolgens voor het bijhouden van de verbinding tussen de API en het iCloud-systeem voor toekomstige verzoeken.
Maak een gebruiker aan
Voordat een sessie kan worden opgezet, moet een gebruiker worden gemaakt om te definiëren welke eindgebruiker toegang tot de bron wil hebben. Dit helpt bij sessiebeheer en gegevensbeveiliging op de 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>" }'
Het antwoord bevat het gebruikers-ID dat nodig is in de volgende oproep.
{ "id": "1", "resource": "user", "organisation": "1", "key": "1", "identifier": "<your user identifier>", "state": "active", "date_created": "2018-11-22T13:49:37.215516Z" }
Maak een sessie
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>" } }'
Het antwoord zal een sessiebron bevatten, die zich aanvankelijk in de pending bevindt, terwijl de API het proces van het opzetten van communicatie met de externe service doorloopt.
{ "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 }
U kunt de status van de sessie controleren via de ophaaloproep.
curl 'https://ricloud-api.reincubate.com/sessions/ed855b07-f72b-4983-ac1d-980fafee8a0b' \ -H 'Authorization: Token <your key_token>'
Als de status failed , is er iets misgegaan tijdens het initialisatieproces. Controleer de waarde van de error attribuut voor meer informatie. Als 2FA is ingeschakeld op uw account - en u heeft uw wachtwoord juist - is de fout die u tegenkomt waarschijnlijk code-required . U wordt gevraagd om een 2FA-code op een van uw iOS-apparaten die op het account zijn aangesloten. Bel gewoon opnieuw vanaf stap (1), maar deze keer inclusief de 2FA-code in de payload.
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>" } }'
Als er een andere fout is opgetreden, kijk dan in het foutengedeelte voor meer informatie.
Zodra de status active de sessie klaar voor gebruik om gegevens en bestanden van de bron op te halen.
Maar zoals we eerder hebben gezien, is uw organisatie nog niet geconfigureerd om deze gegevens te ontvangen.
Ophalen van gegevens en bestanden
Voordat de API kan starten met het ophalen van gegevens uit een bron, moet deze weten waar de gegevens moeten worden gepubliceerd. De API ondersteunt momenteel publiceren naar opslagruimten voor Google Cloud Storage en Amazon S3 (AWS) , die moeten worden geconfigureerd via een opslagconfiguratie van uw organisatie. Volg de stappen in de documentatie voor configuratie van de opslagconfiguratie om zelf een emmer klaar te maken voor gebruik met de API.
Zodra u een opslagconfiguratie heeft, kunt u proberen uw organisatie opnieuw op te halen. De state zou nu active moeten zijn in plaats van niet unconfigured .
Maak een peiling voor gegevens
Om een poll te maken, hoeven we alleen maar de ID van een actieve sessie en enkele details over de gegevens of bestanden die we willen ophalen op te geven.
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"], } }'
Merk op dat we in de bovenstaande oproep het gegevenstype icpl.photos . Mogelijk bent u geïnteresseerd in het ophalen van een ander type gegevens of hebt u mogelijk geen specifieke rechten voor dit gegevenstype. Vervang deze waarde indien nodig.
Hiermee wordt een poll-bron geretourneerd, met state in pending of processing . Op de achtergrond heeft de API ook een taak gemaakt die het daadwerkelijke werk zal doen dat nodig is om deze informatie op te halen (er is ook een taak gemaakt om onze sessie eerder in te stellen).
{ "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 }
Let op het attribuut results , dat op dit moment leeg is. Hier zien we referenties verschijnen voor alle gegevens of bestanden die vanuit deze poll zijn gepubliceerd. Resultaten worden gepubliceerd zodra ze beschikbaar zijn, zodat ze kunnen worden opgehaald voordat de hele peiling is voltooid.
Zodra alle gevraagde gegevens en bestanden naar uw opslag zijn gepubliceerd, verandert de status van de peiling in completed .
Ophalen van resultaatinformatie
Dit wordt gedaan door naar het results van de peiling te kijken.
curl 'https://ricloud-api.reincubate.com/polls/f1447e76-59f1-486b-942f-6b90e3570c63' \ -H 'Authorization: Token <your key_token>'
Het antwoord zal de informatie bevatten die we nodig hebben.
{ "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" }
Het url kenmerk van het resultaat url naar het bestand dat in uw bucket is opgeslagen.
Webhook-evenementen ontvangen
Bepaalde API-functionaliteit wordt automatisch geactiveerd, hetzij als gevolg van externe triggers zoals een Reincubate Relay-app die nieuwe gegevens vindt of als gevolg van een abonnement. In deze gevallen heeft de API een manier nodig om uw systeem te vertellen dat er wijzigingen zijn opgetreden of dat er nieuwe gegevens zijn gepubliceerd waarvan u op de hoogte moet zijn.
Hiervoor maakt de API gebruik van webhook-notificaties. Voordat de API deze kan gaan verzenden en voordat u de Reincubate Relay-service of abonnementen kunt gaan gebruiken, moet uw organisatie worden geconfigureerd met een geldige webhook-configuratie. Volg de gids over webhook-configuratie voor meer details.
