Apple iCloud 서비스 (v2)

업데이트 됨

ricloud API의 icloud 서비스는 iOS 장치 백업의 일괄 형식과 다른 소스의 실시간 및 근 시간 모두에서 iCloud에 저장된 정보에 액세스하는 기능을 제공합니다. API는 최초 출시 이후 iCloud에 대한 액세스를 지원합니다.

클라이언트가 iCloud 서비스를 수행하는 데 필요한 4 가지 핵심 작업이 있습니다.

  • 인증 : log-in , perform-2fa-challenge , submit-2fa-challenge
  • 장치 열거 : list-devices
  • 피드 요청 : fetch-data
  • 원시 파일 요청 : download-file

API에서 가짜 데이터로 작업하기

API와의 통합 개발을 지원하기 위해 일련의 풍부한 데이터로 구성된 모의 계정을 사용할 수 있습니다. 이를 통해 클라이언트는 실제 사용자 데이터로 작업하지 않고도 많은 ricloud API의 기능을 테스트 할 수 있습니다.

모의 계정 이름은 Jonny Appleseed이며, iCloud 계정 ID 인 john.appleseed@reincubate.com 과 암호 joshua 를 사용하여 액세스 할 수 있습니다.

입증

로그인 : log-in

icloud 서비스와 상호 작용하는 첫 번째 단계는 로그인하는 것입니다.

요청에 대해 다음을 지정해야합니다.

  • 상호 작용할 service : icloud
  • action 수행 할 수 있습니다 log-in
  • john.appleseed@reincubate.com 과 같은 iCloud 계정 ID를 나타내는 매개 변수 account
  • 작업에 필요한 작업 매개 변수 (이 경우 password
  • 또한 /account/ endpoint가 나열한 선택적 동작 매개 변수를 지정할 수도 있습니다.
$ curl \
    -X POST \
    -H "Authorization: Token <TOKEN>"
    -d "service=icloud" \
    -d "action=log-in" \
    -d "account=<ACCOUNT>" \
    -d "password=<PASSWORD>" \
    <TASK_SUBMISSION_ENDPOINT>

asapi 엔드 포인트는 JSON 형식으로 응답합니다.

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

당신이 aschannel 엔드 포인트의 올바른 stream_endpoint에 연결되어있는 경우, 당신은 그 결과가 일치 올 보게 될 <TASK_ID_1> 당신은 ASAPI 엔드 포인트로부터 받았다.

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

결과에는 로그인 작업이 성공하면 success 매개 변수가 포함되고 메시지 및 다른 서비스 작업에 사용되는 Apple 인증 토큰이 포함됩니다.

로그인 문제 해결

오류 정의 및 솔루션에 대한 로그인 오류 응답 섹션을 참조하십시오.

2FA 및 2SV

2SV 또는 2FA로 설정된 iCloud 계정에 로그인을 시도하면 일반 로그인이 실패하고 아래의 것과 유사한 오류 메시지가 표시됩니다.

{ "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"
}

data 딕셔너리에는 device_id 키가 지정된 목록 장치가 포함됩니다. 다음 인증 단계를 수행하기 위해 iCloud 계정에서 신뢰하는 장치입니다.

2 단계 인증 (2 단계)

2SV의 경우 trustedDevices 목록에 하나 이상의 장치가 포함됩니다. 클라이언트는 도전 할 나열된 장치를 선택해야합니다.

이를 수행함으로써 이루어진다 perform-2fa-challenge 가진 challenge 으로부터 선택된 장치 키의 설정 trustedDevices .

이중 인증 (2FA)

2FA의 경우 trustedDevices 의 목록은 ["Challenge all 2FA devices"] 으로 설정되어 해당 계정에 연결된 모든 iOS 기기로 챌린지를 보내야 함을 나타냅니다. 이를 수행함으로써 이루어진다 perform-2fa-challenge 가진 challenge 세트의 값 ["Challenge all 2FA devices"] .

perform-2fa-challenge

이 방법은 2FA의 경우 계정의 모든 장치에 실시간으로 요청을 보내거나 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 는 평상시처럼 회신합니다.

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

검색 끝점은 다음과 같이 응답합니다.

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

챌린지가 사용자 기기로 전송되면 submit-2fa-challenge 사용하여 2 요소 코드를 API로 다시 전달해야합니다. 아래 요청에서 <CODE> 는 최종 사용자가 제공 한 숫자 코드로 2FA / 2SV 로그인을 위해 장치로 전송 된 코드를 나타냅니다.

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

asapi 는 평상시처럼 회신합니다.

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

검색 끝점은 일반적인 로그인 메시지로 회신합니다.

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

인증 토큰을 사용하여 계정 로그인 새로 고침

ricloud 는 전체 iCloud 자격 증명을 사용할 필요없이 로그인을 새로 고치는 데 사용할 인증 토큰을 제공합니다. 토큰 화 메커니즘의 사용자는 사용자 자격 증명을 유지할 필요가 없습니다.

이렇게하려면 클라이언트가 로그인 중에 검색된 auth_token 필드를 사용해야합니다. 이는 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>

이 작업을 수행하면 모든 서비스 작업이 서비스에 대해 수행 될 수 있습니다.

장치 열거

장치 열거 : list-devices

하나는 계정에 로그인하고 클라이언트는 iCloud 계정과 연결된 장치 및 장치 백업을 열거 할 수 있습니다. 이 작업은 iCloud 서비스에 대해 list-devices 액션을 수행하여 수행됩니다.

이는 다른 서비스 작업과 동일한 방식으로 수행됩니다. 다음은이 작업에 대한 curl 요청 예입니다. 아래의 <ACCOUNT> 매개 변수는 john.appleseed@reincubate.com 과 같은 계정 ID로 john.appleseed@reincubate.com 있습니다.

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

asapi 엔드 포인트는 JSON 형식으로 응답합니다.

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

검색 결과는 곧 검색 끝점에 나타납니다. 아래는 예제 응답입니다.

{ "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"
    }
  }
}

이 응답에는 지정된 계정의 iCloud 세션에 대한 auth_tokendevices 섹션의 해당 계정과 연결된 장치 목록이 포함됩니다. 모든 장치 항목에는 다음 키가 포함됩니다.

  • ios_version : 기기의 iOS 버전
  • colour : 16 진수 코드로 표시되는 기기의 색상
  • device_name : 사용자가 설정 한 장치 이름
  • latest-backup : 기기가 iCloud에 마지막으로 백업 된 날짜
  • model : 기기의 모델 번호
  • serial : 장치의 일련 번호
  • name : Apple에서 광고 한 기기의 제품 이름

피드 요청

피드 데이터 검색 : fetch-data

fetch-data 액션은 API에서 JSON 데이터의 피드에 액세스하는 데 사용됩니다. 다음 매개 변수가 필요합니다.

  • device : 데이터를 검색 할 장치
  • data : 요청 된 피드 모듈의 CSV

선택적 매개 변수는 다음과 같습니다.

  • since : 결과가 일치해야하는 기간

다음은 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.

예를 들어 위의 명령에서 <FEED_MODULES> 의 값 sms 를 사용하면 백업의 SMS, MMS 및 iMessage에 액세스 할 수 있습니다. 명령의 <FEED_MODULES> 에있는 sms,whatsapp_messages,snapchat_messages 값을 사용하여 동일한 JSON 결과에있는 SMS, MMS 및 iMessages, WhatsApp 메시지 및 Snapchat 메시지에 액세스 할 수 있습니다.

asapi 는 다음과 같이 응답합니다.

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

잠시 후 같은 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
    }
  ]
}

다른 피드 모듈은 다른 형식의 컨텐츠에 액세스하는 데 사용할 수있는 정보를 제공합니다. 예를 들어, 주어진 디바이스에 대해 'photos'를 <FEED_MODULES> 로 사용하는 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=photos" \
    <TASK_SUBMISSION_ENDPOINT>

asapi 가 다음과 같이 응답하게됩니다.

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

다음 결과가 해당 엔드 포인트에 표시됩니다.

{ "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 피드 형식

JSON 피드는 가능한 한 파싱하기 쉽도록 디자인되었습니다. 피드는 단일 응답 내에서 요청 된 모든 데이터 유형을 반환합니다.

모듈 플래그에 지정된 각 피드 모듈은 반환되는 최상위 JSON 사전에 자체 키를 갖습니다.

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

원시 파일 요청

원시 파일 검색 : download-file

download-file 작업은 iCloud에서 직접 파일 또는 메시지 첨부 파일을 다운로드 할 때 사용할 수 있습니다. 필요한 매개 변수는 대상 <DEVICE_ID><FILE_ID> 입니다.

file_list 및 photo 모듈을 포함한 일부 피드 모듈에는 다운로드 할 수있는 파일 또는 첨부 파일에 대한 참조가 들어 있습니다. 여기에는 파일을 식별하고 다운로드하는 데 사용되는 <FILE_ID> 포함되어 있으며 파일 filename , file_path , sizetype 과 같은 일부 추가 메타 데이터가 포함되어 있습니다. 자세한 내용은 정보 추출기 를 참조하십시오.

명령

$ 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 는 다음과 같이 응답합니다.

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

결과가 같은 task_id 가진 엔드 포인트에 나타나는 직후.

오류 응답 문제 해결

일반적인 오류 응답

다음 표는 조치가 제기 할 수있는 오류 코드를 표시합니다.

응답 개요
task-failed 알 수없는 오류
deactivated-account 계정이 비활성화되었습니다.
deactivated-device 기기가 비활성화되었습니다.
client-account-disabled API 토큰 사용 중지됨
account-locked 잠긴 계정
account-credentials-blocked 계정 잠금 및 보호
push-api-timeout 내부 시간 초과
icloud-unauthorised Apple 세션 시간 제한
service-inactive-error 초기화되지 않은 Apple 서비스

알 수없는 오류

로그인 태스크가 실패했으며 이유를 알 수 없습니다. 이 코드로 작업이 실패하는 경우 클라이언트는 지원 팀에 문의 해야합니다.

계정이 비활성화되었습니다.

이는 계정 비활성화 관리 명령을 사용하여 계정이 비활성화되었음을 나타냅니다. 수동 활성화 명령을 보내지 않으면 액세스 할 수 없습니다.

기기가 비활성화되었습니다.

이는 장치 비활성화 관리 명령을 사용하여 장치가 비활성화되었음을 나타냅니다. 수동 활성화 명령을 보내지 않으면 액세스 할 수 없습니다.

API 토큰 사용 중지됨

API에 액세스하는 데 사용되는 토큰이 사용 중지되었습니다. 지원 팀에 문의하십시오.

내부 시간 초과

다른 서비스 작업을 수행하는 동안 API 세션이 만료되면 클라이언트는 push-api-timeout 오류 코드를 수신하므로 다시 로그인해야합니다.

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

iCloud unauthorized

Apple과의 세션이 작업 중에 만료되었거나 무효화 된 경우 작업을 중단해야하며 새로운 log-in 작업을 통해 다시 인증하여 세션을 다시 설정해야합니다. 이 호출에 사용 된 토큰이 이제는 만료 된 Apple 세션에 연결되므로 refresh-session 사용은이 경우 작동하지 않습니다.

경우에 따라 세션이 부분적으로 만료 될 수 있습니다. 예를 들어 list-devices 여전히 유효한 최신 장치 목록을 반환하지만 fetch-dataicloud-unauthorised 실패합니다. 이 경우, 세션은 액세스 가능한 데이터에 대해 계속 사용될 수 있지만 추가 데이터를 얻으려면 log-in 태스크를 사용하여 완전히 새로 고쳐 져야합니다.

서비스 비활성 오류

이 응답은 API가 서비스를 초기화하려고 시도했지만 Apple의 응답이 사용자의 계정에서 비활성화되지 않았 음을 나타내는 경우 반환됩니다. 쿼리되는 데이터 유형에 해당하는 설정을 확인하고 활성화 및 초기화되었는지 확인하십시오.

로그인 오류 응답

다음 표는 위의 일반 코드 외에도 log-insubmit-2fa-challenge 액션에서 발생할 수있는 오류 코드를 보여줍니다.

응답 개요
unable-to-login 자격 증명이 잘못되었습니다.
2fa-required 2FA 필요
invalid-2fa-code 2FA 코드가 잘못되었습니다.
too-many-2fa-requests 2FA 속도 제한
account-locked 잠긴 계정
account-credentials-blocked 계정 잠금 및 보호
terms-of-service-update-client 서비스 약관이 허용되지 않습니다.
session-creation-error 세션 초기화 중 복구 가능한 오류가 발생했습니다.
session-corrupt-error 세션 초기화 중 복구 할 수없는 오류

자격 증명이 잘못되었습니다.

계정에 지정된 자격 증명이 잘못되어 인증이 불가능합니다.

2FA 필요

2 중 인증 (2FA) 또는 2 단계 인증 (2SV)을 사용하는 계정에 로그인하려면 몇 가지 추가 단계가 필요합니다. 아래의 "2FA 및 2SV"섹션을 참조하십시오.

2FA 코드가 잘못되었습니다.

올바르지 않거나 잘못된 2FA 코드가 2FA 챌린지에 대한 응답으로 발송되었습니다.

2FA 속도 제한

최근에 계정에 대한 2FA 요청이 너무 많아서 속도가 제한되었습니다. 30 분 후에 다시 시도하십시오.

잠긴 계정

iCloud 계정은 Apple에 의해 잠겨 있습니다. 단기간에 계정에 다시 액세스하려고 시도하면 account-credentials-blocked 오류가 대신 반환됩니다.

계정 잠금 및 보호

iCloud 계정은 Apple에 의해 잠겨졌으며 ricloud 는 이미 account-locked 클라이언트에게 알립니다. 이 메시지는 서비스가 Apple에 요청을 중계하지 않음을 나타 내기 위해 대체됩니다.

서비스 약관이 허용되지 않습니다.

iCloud 계정은 최신 iCloud 이용 약관이 수락 될 때까지 사용 중지됩니다. 사용자는 장치에서이를 수락하거나 icloud.com에 로그인하여이를 수락 할 수 있습니다.

세션 생성 오류

iCloud 백엔드는 세션 초기화 중 오류로 응답했지만 다시 시도하면 문제가 해결되어 성공할 수 있습니다.

세션 손상 오류

iCloud 백엔드는 세션 초기화 중 오류로 응답하고 다시 시도해도 다른 결과가 발생하지 않습니다. 이 최첨단 사례를 조사 할 수 있도록 지원부에 문의하십시오 (계정 자격 증명이있는 것이 바람직 함).

어떻게 도와 드릴까요?

지원 팀이 도와 드리겠습니다!

근무 시간은 월요일부터 금요일, 오전 9 시부 터 오후 5시 (그리니치 표준시)입니다. 시간은 현재 5:21 오후 GMT입니다.

우리는 1 일 이내에 모든 메시지에 답장하고자합니다.

지원 섹션으로 이동 › 엔터프라이즈 팀에 문의하십시오. ›
우리의 멋진 지원 팀

© 2008 - 2019 Reincubate Ltd. 판권 소유. 영국과 웨일즈에 등록 #5189175, VAT GB151788978. Reincubate®는 등록 상표입니다. 개인 정보 및 이용 약관. 우리는 2FA를 권장합니다. 런던에서 Built로 지어졌습니다.