Ermee beginnen

bijgewerkt
Cover image for: 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:

  • permissions geeft de basisrechten voor uw organisatie weer.
  • storage_configs en storage_config_default zijn leeg omdat we nog geen instellingen moeten instellen.
  • webhook_configs en webhook_config_default zijn ook om dezelfde reden leeg.
  • state is niet unconfigured wat 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.

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 11:20 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

Kunnen we dit artikel verbeteren?

We horen graag van gebruikers: Stuur ons een e-mail, laat een reactie achter of stuur een tweet @reincubate?

© 2008 - 2020 Reincubate Ltd. Alle rechten voorbehouden. Geregistreerd in Engeland en Wales #5189175, VAT GB151788978. Reincubate en Camo zijn handelsmerken. Privacybeleid & termen. Wij bevelen 2FA aan. Gebouwd met in Londen.