Apple iCloud-service (v2)

bijgewerkt

De icloud service van de ricloud API biedt functionaliteit voor toegang tot informatie die is opgeslagen op de iCloud, beide in batch-vorm vanaf back-ups van iOS-apparaten en in realtime en bijna-tijd van andere bronnen. De API ondersteunt de toegang tot de iCloud sinds de oorspronkelijke release.

Er zijn vier kernbewerkingen die een klant mogelijk moet uitvoeren met de iCloud-service.

  • Authenticatie: log-in , perform-2fa-challenge , submit-2fa-challenge
  • Apparaattelling: list-devices
  • Feeds aanvragen: fetch-data
  • Aanvragen van onbewerkte bestanden: download-file

Werken met mock-gegevens uit de API

Om de ontwikkeling van integraties met de API te ondersteunen, wordt een onecht account gevuld met een reeks rijke gegevens beschikbaar gemaakt. Dit stelt klanten in staat om veel van de functies van de ricloud API's te testen zonder te hoeven werken met echte gebruikersgegevens.

Het schijnbericht wordt Jonny Appleseed genoemd en is toegankelijk via de iCloud-account-ID john.appleseed@reincubate.com en wachtwoord joshua .

authenticatie

Inloggen: log-in

De eerste stap naar het communiceren van de icloud service is inloggen.

Voor het verzoek moeten we het volgende specificeren:

  • De service om interactief mee om te gaan: icloud
  • De uit te voeren action : log-in
  • De parameter account , die de iCloud accountcode zoals john.appleseed@reincubate.com
  • De actieparameters vereist door de actie, die in dit geval slechts een password
  • We kunnen ook optionele actieparameters specificeren die worden weergegeven door het /account/ eindpunt
$ curl \
    -X POST \
    -H "Authorization: Token <TOKEN>"
    -d "service=icloud" \
    -d "action=log-in" \
    -d "account=<ACCOUNT>" \
    -d "password=<PASSWORD>" \
    <TASK_SUBMISSION_ENDPOINT>

Het asapi- eindpunt antwoordt in JSON-indeling:

{ "retrieval_protocol": "aschannel",
  "stream": "<STREAM>",
  "success": true,
  "task_id": "<TASK_ID_1>"
}

Als u bent verbonden met het juiste stream_endpoint op het aschannel- eindpunt, ziet u een resultaat dat overeenkomt met het <TASK_ID_1> u van het asapi- eindpunt hebt ontvangen.

{ "message": "Log-in successful",
  "auth_token": "ABCDEFGABCDEFGABCDEFGABCDEFGABCDEFGABCDEFGABCDEFGABCDEFG",
  "success": true
}

De resultaten zullen onder andere een success parameter die waar zal zijn als de login taak gelukt, samen met een boodschap en een Apple-authenticatie token voor gebruik met andere dienstverleners acties.

Problemen met aanmelden oplossen

Zie de sectie over foutreacties bij inloggen voor foutdefinities en oplossingen.

2FA en 2SV

Nadat u hebt geprobeerd in te loggen op een iCloud-account dat is ingesteld met 2SV of 2FA, mislukt de normale aanmelding en wordt een foutbericht weergegeven dat lijkt op het onderstaande bericht.

{ "message": "This account has Two Step Verification enabled, please select a device to challenge.",
  "data": {
    "trustedDevices": ["********12", "Renate's iPhone - iPhone 6s"],
  },
  "error": "2fa-required"
}

Het data bevat een lijst met apparaten, ingetoetst door device_id . Dit zijn de apparaten die worden vertrouwd door het iCloud-account om de volgende authenticatiestap uit te voeren.

Voor tweestapsverificatie (2SV)

In het geval van 2SV bevat de lijst met trustedDevices een of meer apparaten. Clients moeten een vermeld apparaat selecteren om aan te vallen.

Dit wordt gedaan door perform-2fa-challenge met challenge set op de sleutel van het gekozen apparaat via trustedDevices .

Voor authenticatie met twee factoren (2FA)

In het geval van 2FA wordt de lijst met trustedDevices ["Challenge all 2FA devices"] ingesteld op ["Challenge all 2FA devices"] uitdagen ["Challenge all 2FA devices"] , waarmee wordt aangegeven dat een uitdaging moet worden verzonden naar alle iOS-apparaten die op dat account zijn aangesloten. Dit wordt gedaan door perform-2fa-challenge met challenge set naar de waarde van ["Challenge all 2FA devices"] .

perform-2fa-challenge

Deze methode stuurt een aanvraag in realtime naar alle apparaten in de account in het geval van 2FA of het gekozen apparaat in het geval van 2SV.

$ curl \
    -X POST \
    -H "Authorization: Token <TOKEN>"
    -d "service=icloud" \
    -d "action=perform-2fa-challenge" \
    -d "challenge=<TRUSTED_DEVICE>" \
    <TASK_SUBMISSION_ENDPOINT>

<TRUSTED_DEVICE> must be set to a device_id, or to "Challenge all 2FA devices"

asapi zal zoals gewoonlijk antwoorden:

{ "retrieval_protocol": "aschannel",
  "stream": "<STREAM>",
  "success": true,
  "task_id": "<TASK_ID_X>"
}

Het ophaal eindpunt zal antwoorden met:

{ "message": "Challenge has been submitted.",
  "success": true
}

Nadat de uitdaging is verzonden naar het apparaat van de gebruiker, moet de code met twee factoren worden teruggezonden naar de API met behulp van submit-2fa-challenge . In het onderstaande verzoek is <CODE> de numerieke code die door de eindgebruiker wordt verstrekt en die de codes vertegenwoordigt die naar het apparaat zijn verzonden voor aanmelding bij 2FA / 2SV.

$ curl \
    -X POST \
    -H "Authorization: Token <TOKEN>"
    -d "service=icloud" \
    -d "action=submit-2fa-challenge" \
    -d "code=<CODE>" \
    <TASK_SUBMISSION_ENDPOINT>

asapi zal zoals gewoonlijk antwoorden:

{ "retrieval_protocol": "aschannel",
  "stream": "<STREAM>",
  "success": true,
  "task_id": "<TASK_ID_X>"
}

Het eindpunt van het ophalen antwoordt met een normaal inlogbericht:

{ "message": "Log-in successful",
  "auth_token": "ABCDEFGABCDEFGABCDEFGABCDEFGABCDEFGABCDEFGABCDEFGABCDEFG",
  "success": true
}

Een accountaanmelding vernieuwen met behulp van authenticatietokens

ricloud biedt verificatietokens voor gebruik bij het vernieuwen van aanmeldingen zonder de noodzaak om volledige iCloud-referenties te gebruiken. Gebruikers van het tokenisatiemechanisme hoeven geen gebruikersreferenties aan te houden.

Om dit te doen, moeten clients het auth_token veld gebruiken dat is opgehaald tijdens het inloggen. Dit moet worden verzonden naar het actie-eindpunt van de refresh-session .

$ curl \
    -X POST \
    -H "Authorization: Token <TOKEN>"
    -d "service=icloud" \
    -d "action=refresh-session" \
    -d "auth_token=<ICLOUD_AUTH_TOKEN>" \
    <TASK_SUBMISSION_ENDPOINT>

Wanneer dit is voltooid, kan elke serviceactie worden uitgevoerd tegen de service.

Apparaattelling

Opsomming van apparaten: list-devices

Als u bent aangemeld bij een account, kunnen clients apparaten en apparaatback-ups aan het iCloud-account koppelen. Dit wordt gedaan door de actie list-devices tegen de iCloud-service uit te voeren.

Dit gebeurt op dezelfde manier als elke andere serviceactie. Hier is een voorbeeld van een curl voor deze actie. De onderstaande parameter <ACCOUNT> kan worden gevuld met een account-ID, zoals john.appleseed@reincubate.com .

$ curl \
    -X POST \
    -H "Authorization: Token <TOKEN>"
    -d "service=icloud" \
    -d "action=list-devices" \
    -d "account=<ACCOUNT>" \
    <TASK_SUBMISSION_ENDPOINT>

Het asapi- eindpunt antwoordt in JSON-indeling:

{ "retrieval_protocol": "aschannel",
  "stream": "<STREAM>",
  "success": true,
  "task_id": "<TASK_ID_2>"
}

Uw resultaat verschijnt kort op het eindpunt van de ophaalactie. Hieronder ziet u een voorbeeldantwoord:

{ "auth_token": "ABCDEFGABCDEFGABCDEFGABCDEFGABCDEFGABCDEFGABCDEFGABCDEFG",
  "devices": {
    "<DEVICE_ID_1>": {
      "ios_version": "10.0",
      "colour": "1",
      "device_name": "Johnny's iP7 iOS10 Black",
      "latest-backup": "2016-09-16 14:08:13.000000",
      "model": "D101AP",
      "serial": "ABC123AAAAAA",
      "name": "iPhone 7"
    },
    "<DEVICE_ID_2>": {
      "ios_version": "9.1",
      "colour": "#e1e4e3",
      "device_name": "Johnny's iPad",
      "latest-backup": "2016-11-16 16:36:33.000000",
      "model": "J98aAP",
      "serial": "ABC123BBBBBB",
      "name": "iPad Pro"
    },
    "<DEVICE_ID_3>": {
      "ios_version": "9.2.1",
      "colour": "#3b3b3c",
      "device_name": "Johnny's other iPhone",
      "latest-backup": "2016-06-16 16:00:49.000000",
      "model": "N49AP",
      "serial": "DFVDASDDSVAS",
      "name": "iPhone 5c"
    },
    "<DEVICE_ID_4>": {
      "ios_version": "9.0.2",
      "colour": "#e1e4e3",
      "device_name": "Johnny's white iPhone",
      "latest-backup": "2016-02-25 15:37:38.000000",
      "model": "N61AP",
      "serial": "HYTWGFHGHDSF",
      "name": "iPhone 6"
    }
  }
}

Dit antwoord bevat de auth_token voor de iCloud-sessie van het opgegeven account, samen met een lijst met apparaten die aan dat account zijn gekoppeld in het gedeelte devices . Elk apparaat-item bevat de volgende toetsen:

  • ios_version : de iOS-versie van het apparaat
  • colour : de kleur van het apparaat als een hexadecimale code
  • device_name : de naam van het apparaat zoals ingesteld door de gebruiker
  • latest-backup : de datum waarop het apparaat het laatst is geback-upt naar de iCloud
  • model : het modelnummer van het apparaat
  • serial : het serienummer van het apparaat
  • name : de productnaam van het apparaat zoals geadverteerd door Apple

Feeds aanvragen

Ophalen van feedgegevens: fetch-data

De fetch-data wordt gebruikt om toegang te krijgen tot feeds van JSON-gegevens uit de API. Het vereist de volgende parameters:

  • device : het apparaat om gegevens van of over op te halen
  • data : een CSV van de gevraagde invoermodules

Optionele parameters zijn:

  • since : de tijdsperiode vanaf welke de resultaten moeten overeenkomen

Hieronder ziet u een voorbeeld van een actie voor fetch-data .

$ curl \
    -X POST \
    -H "Authorization: Token <TOKEN>" \
    -d "service=icloud" \
    -d "action=fetch-data" \
    -d "account=<ACCOUNT>" \
    -d "device=<DEVICE_ID>" \
    -d "data=<FEED_MODULES>" \
    <TASK_SUBMISSION_ENDPOINT>

<FEED_MODULES> can be any of the feed modules listed in feed modules.

Als u bijvoorbeeld de waarde sms in <FEED_MODULES> in de bovenstaande opdracht gebruikt, heeft u toegang tot SMS, MMS en iMessages in een back-up. Als we de waarde sms,whatsapp_messages,snapchat_messages in <FEED_MODULES> in de opdracht, hebben we toegang tot SMS, MMS en iMessages, WhatsApp-berichten en Snapchat-berichten, allemaal in hetzelfde JSON-resultaat.

De asapi reageren met:

{ "retrieval_protocol": "aschannel",
  "stream": "<STREAM>",
  "success": true,
  "task_id": "<TASK_ID_3>"
}

Kort daarna verschijnen resultaten op het eindpunt van de resultaten met dezelfde task_id :

{ "sms": [
    { "group_handles": [
        "+441234567890",
        "renate@reincubate.com"
      ],
      "attachments": [],
      "deleted": false,
      "text": "Welcome to Vodafone!",
      "conversation_id": "vodafone",
      "from_me": false,
      "date": "2015-10-28 09:18:17.000000",
      "handle": "vodafone",
      "type": "SMS",
      "id": 6
    }
  ]
}

Andere feedmodules bieden informatie die kan worden gebruikt voor toegang tot andere vormen van inhoud. Een fetch-data met 'foto's' als <FEED_MODULES> voor een bepaald apparaat ziet er bijvoorbeeld als volgt uit:

$ curl \
    -X POST \
    -H "Authorization: Token <TOKEN>" \
    -d "service=icloud" \
    -d "action=fetch-data" \
    -d "account=<ACCOUNT>" \
    -d "device=<DEVICE_ID>" \
    -d "data=photos" \
    <TASK_SUBMISSION_ENDPOINT>

Zal asapi doen reageren met:

{ "retrieval_protocol": "aschannel",
  "stream": "<STREAM>",
  "success": true,
  "task_id": "<TASK_ID_4>"
}

Het volgende resultaat verschijnt op het juiste eindpunt:

{ "photos": [{
    "file_path": "Media/DCIM/100APPLE/IMG_0001.PNG",
    "last_modified": "2016-10-05 10:24:03.000000",
    "file_id": "c8ada38b9acf7368c6347be1c353dc68ed2c7741",
    "filename": "IMG_0001.PNG"
  }, {
    "file_path": "Media/DCIM/100APPLE/IMG_0002.MOV",
    "last_modified": "2016-10-11 09:39:25.000000",
    "file_id": "5c3e35cc01689340a34d13d34a0591e2ed450e63",
    "filename": "IMG_0002.MOV"
  }]
}

JSON-feedindelingen

De JSON- feeds zijn zo ontworpen dat ze zo eenvoudig mogelijk te ontleden zijn. De feed retourneert alle gegevenstypen die binnen één antwoord zijn aangevraagd.

Elke invoermodule die is opgegeven in de modulevlag, heeft zijn eigen sleutel in het JSON-woordenboek op het hoogste niveau dat wordt geretourneerd.

{
    "first_module_name": "Module's data",
    "second_module_name": "Module's data",
    "etc.": "etc."
}

Raw-bestanden aanvragen

Ophalen van onbewerkte bestanden: download-file

De download-file actie is beschikbaar voor het downloaden van bestanden of e-mailbijlagen rechtstreeks vanuit de iCloud. De benodigde parameters zijn het doel <DEVICE_ID> en een <FILE_ID> .

Sommige file_list inclusief de file_list en file_list bevatten verwijzingen naar bestanden of bijlagen die kunnen worden gedownload. Deze bevatten een <FILE_ID> gebruikt om het bestand te identificeren en te downloaden, en vaak enkele extra metadata zoals filename , file_path , size en type . Zie informatie-extractors voor meer details.

Het bevel

$ curl \
    -X POST \
    -H "Authorization: Token <TOKEN>" \
    -d "service=icloud" \
    -d "action=download-file" \
    -d "account=<ACCOUNT>" \
    -d "device=<DEVICE_ID>" \
    -d "file=<FILE_ID>" \
    <TASK_SUBMISSION_ENDPOINT>

asapi reageert met:

{ "retrieval_protocol": "aschannel",
  "stream": "<STREAM>",
  "success": true,
  "task_id": "<TASK_ID_5>"
}

Kort na de resultaten verschijnen op het eindpunt met dezelfde task_id .

Foutreacties oplossen

Algemene foutreacties

De volgende tabel toont de foutcodes die elke actie kan opwerpen.

antwoord Samenvatting
task-failed Onbekende mislukking
deactivated-account Account gedeactiveerd
deactivated-device Apparaat gedeactiveerd
client-account-disabled API-token uitgeschakeld
account-locked Account geblokkeerd
account-credentials-blocked Account vergrendeld en beveiligd
push-api-timeout Interne time-out
icloud-unauthorised Time-out Apple-sessie
service-inactive-error Apple-service niet-geïnitialiseerd

Onbekende mislukking

De aanmeldtaak is mislukt en de reden was onbekend. In het geval van een taakstoring met deze code, moeten klanten contact opnemen met het ondersteuningsteam .

Account gedeactiveerd

Dit betekent dat het account is gedeactiveerd met behulp van de opdracht voor het deactiveren van accounts. Het zal niet toegankelijk zijn tenzij een handmatige activeringsopdracht wordt verzonden.

Apparaat gedeactiveerd

Dit betekent dat het apparaat is gedeactiveerd met behulp van de opdracht voor het deactiveren van het apparaat. Het zal niet toegankelijk zijn tenzij een handmatige activeringsopdracht wordt verzonden.

API-token uitgeschakeld

Het token dat wordt gebruikt om toegang te krijgen tot de API is uitgeschakeld. Neem contact op met het ondersteuningsteam.

Interne time-out

Als de API-sessie verloopt tijdens het uitvoeren van andere serviceactiviteiten, ontvangen clients de foutcode: push-api-timeout en moeten ze opnieuw inloggen.

{ "message": "Unable to recover the session. Please re-login and try again",
  "error": "push-api-timeout"
}

iCloud ongeautoriseerd

Als de sessie met Apple al eerder is verlopen of ongeldig is tijdens een actie, moet de actie worden afgebroken en moet de sessie opnieuw worden ingesteld door opnieuw te verifiëren via een nieuwe log-in . Het gebruik van refresh-session werkt in dit geval niet, omdat het token dat voor deze aanroep wordt gebruikt, gekoppeld is aan de sessie met Apple die nu is verlopen.

In bepaalde gevallen kan een sessie gedeeltelijk verlopen zijn. Bijvoorbeeld, list-devices nog steeds geeft een geldige, up-to-date lijst met apparaten, maar fetch-data mislukt met icloud-unauthorised . In dit geval kan de sessie worden voortgezet voor toegankelijke gegevens, maar moet deze volledig worden vernieuwd met behulp van een log-in om meer gegevens te verkrijgen.

Service inactieve fout

Dit antwoord wordt geretourneerd als de API een service probeert te initialiseren maar een reactie van Apple heeft ontvangen die aangeeft dat het niet is geïnactiveerd in het account van de gebruiker. Controleer de bijbehorende instelling voor het gegevenstype dat wordt opgevraagd en zorg ervoor dat het wordt geactiveerd en geïnitialiseerd.

Aanmeldingsreacties

De volgende tabel toont de foutcodes die de log-in en submit-2fa-challenge acties kunnen verhogen in aanvulling op de algemene codes hierboven.

antwoord Samenvatting
unable-to-login Inloggegevens zijn onjuist
2fa-required 2FA vereist
invalid-2fa-code Ongeldige 2FA-code
too-many-2fa-requests 2FA-tarief beperkt
account-locked Account geblokkeerd
account-credentials-blocked Account vergrendeld en beveiligd
terms-of-service-update-client Servicevoorwaarden niet geaccepteerd
session-creation-error Herstelbare fout tijdens sessie-initialisatie
session-corrupt-error Niet-herstelbare fout tijdens sessie-initialisatie

Inloggegevens zijn onjuist

De inloggegevens voor het account waren onjuist en verificatie is niet mogelijk.

2FA vereist

Aanmelden bij accounts die gebruikmaken van tweefactorauthenticatie (2FA) of tweestapsverificatie (2SV) vereist enkele extra stappen. Zie de secties "2FA en 2SV" hieronder.

Ongeldige 2FA-code

Er is een ongeldige of anderszins onjuiste 2FA-code verzonden als reactie op de 2FA-uitdaging.

2FA-tarief beperkt

Er zijn recent te veel 2FA-verzoeken verzonden voor het account: het is tariefbeperkt. Probeer het na 30 minuten opnieuw.

Account geblokkeerd

Het iCloud-account is vergrendeld door Apple. Als er in een korte tijd een andere poging wordt gedaan om toegang tot het account te krijgen, wordt in plaats daarvan een account-credentials-blocked fout geretourneerd.

Account vergrendeld en beveiligd

Het iCloud-account is geblokkeerd door Apple en ricloud heeft de klant al op de hoogte gebracht met account-locked . Dit bericht is vervangen om aan te geven dat de service het verzoek niet doorgeeft aan Apple.

Servicevoorwaarden niet geaccepteerd

Het iCloud-account is uitgeschakeld in afwachting van de acceptatie van de nieuwste iCloud-voorwaarden. De gebruiker kan deze op zijn apparaat accepteren of door in te loggen op icloud.com.

Fout bij maken van sessie

De iCloud-back-end reageerde met een fout tijdens de initialisatie van de sessie, maar een nieuwe poging zal het probleem waarschijnlijk oplossen en slagen.

Session corrupte fout

De iCloud-back-end reageerde met een fout tijdens de initialisatie van de sessie en opnieuw proberen zal niet resulteren in een ander resultaat. Neem contact op met de ondersteuning (bij voorkeur met accountreferenties) zodat deze edge-case kan worden onderzocht.

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 3:46 PM 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

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