Ermee beginnen

bijgewerkt

Als u de ricloud v3 API wilt gaan gebruiken, moet u eerst contact opnemen om uw organisatie in te stellen. Zodra dit is voltooid, zou u uw initiële key_token moeten hebben die u toegang tot de API zal verlenen.

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": [],
    "storage_config_default": null,
    "webhook_configs": [],
    "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 de toegang tot een bron. In het geval van een iCloud-accountbron, moet de API zich aanmelden bij het account om de sessie tussen zichzelf en de iCloud-service van Apple te maken.

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": "1",
    "type": "icloud.account",
    "identifier": "<iCloud account username>"
  },
  "payload": {
    "password": "<iCloud account password>"
  }
}'

Het antwoord bevat een sessiebron, die zich aanvankelijk in de status In pending bevindt, terwijl de API bezig is met het instellen van communicatie met de service van derden. In dit geval krijgen we toegang tot de 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
}

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 over wat er mis ging.

In het geval dat 2FA is ingeschakeld voor uw account, is de kans groot dat de fout waarschijnlijk is code-required en wordt u op een van uw apparaten om het 2FA-proces gevraagd. Voer eenvoudig de oproep vanaf stap (1) opnieuw uit, 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": "1",
    "type": "icloud.account",
    "identifier": "<iCloud account username>"
  },
  "payload": {
    "password": "<iCloud account password>"
    "code": "<2FA code>"
  }
}'

Als er nog een fout is opgetreden, raadpleegt u het gedeelte over fouten voor meer informatie.

Zodra de status active de sessie klaar voor gebruik om gegevens en bestanden uit de bron op te halen. Zoals we eerder zagen, is uw organisatie echter nog niet geconfigureerd om een van deze gegevens te ontvangen, wat ons naar de volgende stap brengt.

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.

Maak een peiling voor gegevens

De eenvoudigste set gegevens die u uit de iCloud kunt ophalen, is basisinformatie over uw account. Het enige dat nodig is, is de ID van een actieve sessie en enkele specifiers voor de gegevens die u wilt herstellen.

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"],
  }
}'

Let op: in de bovenstaande aanroep hebben we het gegevenstype callkit.calls opgegeven, maar uw sleutel heeft mogelijk machtigingen voor verschillende gegevenstypen of u bent misschien geïnteresseerd in het ophalen van een ander soort gegevens, vervang gewoon indien nodig.

Hiermee wordt een peilingbron geretourneerd. Op de achtergrond heeft de API ook een taak gemaakt die het daadwerkelijke werk uitvoert dat nodig is om deze informatie op te halen (er is ook een taak gemaakt om onze sessie eerder in te stellen). De ID van de taak is te zien onder het attribuut 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
}

Let ook op het results , dat op dit moment leeg is. Hier zien we de ID's van gegevens die van de taak zijn gepubliceerd.

Nu willen we wachten totdat de verwerking is voltooid en de status van de peiling is ingesteld om te succeeded .

Ophalen van resultaatinformatie

Dit is eenvoudig te doen 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",
  "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"
}

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 asrelay- instantie die nieuwe gegevens vindt of vanwege een geplande peiling. In deze gevallen heeft de API een manier nodig om uw systeem te vertellen dat er veranderingen zijn gebeurd of dat er nieuwe gegevens zijn gepubliceerd waarvan u op de hoogte moet zijn.

Om dit te doen, maakt de API gebruik van webhookmeldingen. Voordat de API deze kan verzenden, en voordat u de asrelay- service of geplande peilingen kunt gebruiken, moet uw organisatie worden geconfigureerd met een geldige webhook-configuratie. Volg de gids over de configuratie van de webhook 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 1:26 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 - 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.