Начиная

обновленный
Cover image for: Начиная

Чтобы начать использовать ricloud API, сначала нужно связаться с вами, чтобы настроить вашу организацию. Как только это будет завершено, у вас должен быть ваш начальный key_token который предоставит вам доступ к API.

Вызовы API в этом разделе выполняются с использованием cURL, но их можно легко заменить эквивалентными вызовами из ricloud-py .

Просмотр вашей организации

Сначала мы кратко рассмотрим вашу организацию.

curl 'https://ricloud-api.reincubate.com/organisation' \
  -H 'Authorization: Token <your key_token>'

Вы должны увидеть ответ, аналогичный приведенному ниже. Если вы получите ответ HTTP 401, проверьте значение key_token в заголовке 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"
}

Здесь вы можете увидеть некоторую информацию о вашей организации:

  • permissions отображает базовые разрешения для вашей организации.
  • storage_configs и storage_config_default пусты, так как мы еще не настроили их.
  • webhook_configs и webhook_config_default также пусты по той же причине.
  • state не unconfigured что отражает отсутствие допустимых конфигов хранилища.

Мы вернемся к этапам настройки позже, так как это не мешает вам получать доступ к службам через API.

Теперь, когда мы убедились, что ваша организация работает, давайте попробуем получить доступ к учетной записи iCloud.

Настройка сеанса

Сеанс представляет доступ к источнику. В этом случае нашим источником будет учетная запись iCloud, и создание сеанса будет эффективно «входить» в учетную запись. Затем сеанс будет следить за связью между API и системой iCloud для будущих запросов.

Создать пользователя

Перед установкой сеанса необходимо создать пользователя, чтобы определить, какой конечный пользователь хочет получить доступ к источнику. Это помогает в управлении сессиями и безопасности данных в 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>"
}'

Ответ будет содержать идентификатор пользователя, необходимый для следующего вызова.

{
  "id": "1",
  "resource": "user",
  "organisation": "1",
  "key": "1",
  "identifier": "<your user identifier>",
  "state": "active",
  "date_created": "2018-11-22T13:49:37.215516Z"
}

Создать сеанс

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

Ответ будет содержать ресурс сеанса, который первоначально будет находиться в состоянии pending пока API проходит процесс настройки связи со сторонней службой.

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

Вы можете проверить состояние сеанса через вызов извлечения.

curl 'https://ricloud-api.reincubate.com/sessions/ed855b07-f72b-4983-ac1d-980fafee8a0b' \
  -H 'Authorization: Token <your key_token>'

Если состояние становится failed , что-то пошло не так во время процесса инициализации. Проверьте значение атрибута error для более подробной информации. Если в вашей учетной записи включено 2FA - и вы правильно ввели пароль - обнаруженная ошибка, скорее всего, потребуется code-required . Вам будет предложено ввести код 2FA на одном из ваших устройств iOS, подключенных к учетной записи. Просто выполните вызов из шага (1) еще раз, но на этот раз включив код 2FA в полезную нагрузку.

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

Если произошла другая ошибка, пожалуйста, проверьте раздел ошибок для получения дополнительной информации.

Как только состояние становится active сеанс готов к использованию для извлечения данных и файлов из источника.

Однако, как мы видели ранее, ваша организация еще не настроена на получение каких-либо этих данных.

Извлечение данных и файлов

Прежде чем API сможет начать извлекать данные из источника, он должен знать, куда ему следует публиковать данные. В настоящее время API поддерживает публикацию в хранилища Google Cloud Storage и Amazon S3 (AWS) , которые необходимо настроить через конфигурацию хранилища, принадлежащую вашей организации. Следуйте инструкциям, приведенным в документации по настройке хранилища, чтобы получить собственную корзину, готовую для использования с API.

Если у вас есть конфигурация хранилища, вы можете попытаться восстановить свою организацию снова. Теперь state должно быть active , а не unconfigured .

Создать опрос для данных

Чтобы создать опрос, нам нужно предоставить только идентификатор активного сеанса и некоторые данные о данных или файлах, которые мы хотим получить.

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

Обратите внимание, что в приведенном выше вызове мы запрашиваем icpl.photos данных icpl.photos . Вас может заинтересовать получение данных другого типа, или у вас могут не быть разрешения для этого типа данных, в частности. Подставьте это значение по необходимости.

Это вернет ресурс опроса, state в state pending или processing . В фоновом режиме API также создал задачу, которая будет выполнять фактическую работу, необходимую для извлечения этой информации (ранее была также создана задача для настройки нашего сеанса).

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

Обратите внимание на атрибут results , который на данный момент пуст. Здесь мы увидим ссылки на любые данные или файлы, опубликованные в этом опросе. Результаты публикуются по мере их появления, поэтому их можно получить до завершения всего опроса.

Как только все запрошенные данные и файлы будут опубликованы в вашем хранилище, состояние опроса изменится на completed .

Получить информацию о результате

Это делается путем просмотра атрибута results опроса.

curl 'https://ricloud-api.reincubate.com/polls/f1447e76-59f1-486b-942f-6b90e3570c63' \
  -H 'Authorization: Token <your key_token>'

Ответ будет содержать необходимую нам информацию.

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

Атрибут url результата будет указывать на файл, хранящийся в вашей корзине.

Получение событий webhook

Определенные функции API запускаются автоматически либо в результате внешних триггеров, таких как приложение Reincubate Relay, для поиска новых данных, либо из-за подписки. В этих случаях API необходим способ сообщить вашей системе, что произошли изменения или что опубликованы новые данные, о которых вам следует знать.

Для этого API использует уведомления webhook. Прежде чем API сможет начать их отправку, и прежде чем вы сможете начать использовать службу Reincubate Relay или подписки, ваша организация должна быть настроена с допустимой конфигурацией webhook. Следуйте руководству по настройке webhook для более подробной информации.

Как мы можем помочь?

Наша служба поддержки здесь, чтобы помочь!

Наш офис работает с понедельника по пятницу с 9:00 до 17:00 по Гринвичу. Время в настоящее время 5:21 ДП с GMT.

Мы стремимся отвечать на все сообщения в течение одного рабочего дня.

Перейти в раздел поддержки › Связаться с командой предприятия ›
Наша отличная команда поддержки

Можем ли мы улучшить эту статью?

Нам нравится слышать от пользователей: почему бы не написать нам электронное письмо, оставить комментарий или написать в Твиттере @reincubate?

© 2008 - 2020 Reincubate Ltd. Все права защищены. Зарегистрировано в Англии и Уэльсе #5189175, VAT GB151788978. Reincubate и Camo являются товарными знаками. Политика конфиденциальности & условия. Мы рекомендуем 2FA. Построен с в Лондоне.