Запрос данных с помощью asapi (v2)

обновленный

asapi - это асинхронный механизм управления API ricloud . Это позволяет пользователям:

  • Узнайте об услугах , действиях и конечных точках, которые им разрешено использовать
  • Зарегистрируйтесь, отмените регистрацию и узнайте об аккаунтах
  • Отправить асинхронные задачи
  • Запрос статуса задач

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

Методы с первого взгляда

Сервис, действие и обнаружение конечной точки

/account/

Используя /account/ endpoint, клиенты могут получить информацию о:

  • Доступные услуги
  • Доступные действия и их параметры и разрешения
  • Конечные точки доступны для отправки и извлечения задач

Для этого делается запрос на обнаружение:

$ curl \
    -X GET \
    -H 'Authorization: Token <TOKEN>' \
    https://asapi.reincubate.com/account/ -D -

Это вернет набор JSON с описанием доступных сервисов, действий и конечных точек. Пример ниже сокращен:

{ "services": [{
    "name": "iCloud",
    "actions": [{
      "description": "",
      "parameters": [{
        "type": "string",
        "description": "",
        "optional": false,
        "name": "Device",
        "slug": "device"
      }, {
        "type": "date",
        "description": "",
        "optional": true,
        "name": "Since",
        "slug": "since"
      }],
      "name": "Fetch Data",
      "execution": "Asynchronous",
      "slug": "fetch-data",
      "permissions": {
        "data": ["sms"]
      }
    }],
    "slug": "icloud"
  }],
  "task_submission_endpoint": {
    "host": "asapi.reincubate.com",
    "protocol": "https",
    "uri": "/submit-task/"
  },
  "stream_endpoints": [{
    "host": "aschannel.reincubate.com",
    "protocol": "https",
    "uri": "/stream/"
  }]
}

В этом случае клиент будет иметь доступ к службе icloud и действию fetch-data . Они должны представить device и data параметров при его использовании, а также необязательно since .

Этот последний параметр data должен быть в формате списка; этот параметр может содержать любые значения , указанные в permissions > data о fetch-data секции.

task_submission_endpoint определен в этом ответе, и он информирует клиентов, где действия могут быть переданы для выполнения.

Точка stream_endpoint в приведенном выше примере определяется как aschannel.reincubate.com , что означает, что aschannel настроен как конечная точка результатов. В качестве альтернативы это может привести к тому , что клиенты будут загружаться в зависимости от конфигурации их токена.

Регистрация и снятие с учета

register-account

Чтобы отправлять действия, нам нужно сообщить asapi о тех учетных записях, в отношении которых могут быть выполнены действия против них. Для этого мы будем использовать /register-account/ endpoint:

$ curl \
    -X POST \
    -H 'Authorization: Token <TOKEN>' \
    -d "service=<SERVICE>" \
    -d "username=<USERNAME>" \
    https://asapi.reincubate.com/register-account/ -D -

В этом запросе <SERVICE> является службой, которой принадлежит определенное действие, тогда как <USERNAME> представляет для учетной записи, которая будет использоваться в действиях.

deregister-account

Если учетная запись больше не будет использоваться, она может быть отменена. Для отмены регистрации учетной записи аналогичный запрос можно отправить в /deregister-account/ endpoint:

$ curl \
    -X POST \
    -H 'Authorization: Token <TOKEN>' \
    -d "service=<SERVICE>" \
    -d "username=<USERNAME>" \
    https://asapi.reincubate.com/deregister-account/ -D -

Оба метода в случае успеха вернут 200 ответ с

{ "success": true
}

Возможные ошибки включают в себя:

  • unique_together : «Учетная запись с этой службой, клиентом и unique_together пользователя уже существует»

Представление задачи

[TASK-SUBMISSION]

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

Для отправки задачи используется следующая команда:

$ curl \
    -X POST \
    -H "Authorization: Token <TOKEN>" \
    -d "service=<SERVICE>" \
    -d "action=<ACTION>" \
    -d "account=<ACCOUNT>" \
    -d "param1=<VALUE1>" \
    -d "param2=<VALUE2>" \
    <TASK_SUBMISSION_ENDPOINT> -D -

По этому запросу:

В случае успеха запрос вернет 200 с:

{ "task_id": "<TASK_ID>",
  "retrieval_protocol": "<RETRIEVAL_PROTOCOL>",
  "stream": "<STREAM>",
  "success": true
}

В этих ответах: <TASK_ID> предоставляет идентификатор задачи, который можно использовать для запроса ее состояния и получения результата задачи, если используется инструмент <RETRIEVAL_PROTOCOL> указывает метод, используемый для получения результатов задачи, и может принимать значение aschannel или asstore. <STREAM> - идентификатор потока для использования при получении результатов задачи, если используется aschannel *.

Если запрос был искажен, свойство success будет иметь значение false, а ответ будет содержать раздел «ошибки» с обратной связью. Например:

{ "errors": {
    "service": [
      ["[u'Invalid service name']", "invalid_service"]
    ]
  },
  "success": false
}

Возможные ошибки включают в себя: * invalid_service : «Неверное имя службы» * invalid_parameter_value : «Значение не допускается для параметра» * no_such_account : «Нет такого счета» * invalid : «Недопустимое значение» * limit_exceeded : «Слишком много идентификаторов задач представляется» * invalid_action : «Недопустимое действие» * missing-param : «Параметр пропал, отсутствует'

Запрос статуса задачи

/task-status/

Для каждой задачи, отправляемой в конечную точку asapi , предоставляется task_id . Клиент может периодически отправлять этот task_id в конечную точку asapi , чтобы узнать состояние задачи. Его состояние может быть запрошено с помощью запроса POST в /task-status/ endpoint. Клиенты могут запрашивать статус до 10 000 задач одновременно.

$ curl \
    -X POST \
    -H "Authorization: Token <TOKEN>" \
    -d "task_ids=<TASK_ID_1>,<TASK_ID_2>,<TASK_ID_3>,<TASK_ID_4>,<TASK_ID_5>,<TASK_ID_6>,<TASK_ID_7>" \
    https://asapi.reincubate.com/task-status/

Если <TASK_ID> хотя бы один правильный <TASK_ID> , ответ будет 200 в следующем формате:

{ "<TASK_ID_1>": {
    "status": "<TASK_STATUS>",
    "retrieval_protocol": "<RETRIEVAL_PROTOCOL>",
    "result_retrieved": "<RETRIEVAL_STATUS>",
    "success": "<TASK_SUCCESS>"
  },
  "success": "<CHECK_SUCCESS>"
}

Если <TASK_SUCCESS> равно «True», то результаты немедленно доступны в соответствующей конечной точке.

Свойство status может принимать следующие значения:

  • Pending
  • In progress
  • Work complete
  • Publish ongoing, with result available
  • Publish complete (в этом случае значение success будет "true")
  • Publish failed (в этом случае значение success будет "false")
  • Task did not complete successfully. (в этом случае значение success будет "ложным")

<RETRIEVAL_PROTOCOL> indicates the method used to retrieve the task results and can take the value of aschannel or asstore depending on the token.

<RETRIEVAL_STATUS> is a boolean, indicating whether the task's results have already been consumed by a client. If <RETRIEVAL_STATUS> is "True", then the results have already been consumed and are no longer available.

Параметр <CHECK_SUCCESS> расположенный в корне дерева JSON, относится к успешной проверке состояния. Если это «ложь», ответ будет содержать дополнительную запись «ошибки».

Возможные ошибки включают в себя:

  • invalid : "Неверное значение task_id: "
  • limit_exceeded : " limit_exceeded слишком много идентификаторов задач, предел "

Пример вывода показан ниже:

{
  "<TASK_ID_1>": {
    "success": false,
    "error": "No task with this ID was found."
  },
  "<TASK_ID_2>": {
    "status": "Publish complete",
    "retrieval_protocol": "aschannel",
    "result_retrieved": false,
    "success": true
  },
  "<TASK_ID_3>": {
    "status": "Publish complete",
    "retrieval_protocol": "asstore",
    "retrieval_endpoint": "https://asstore.reincubate.com/fetch/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/",
    "result_retrieved": true,
    "success": true
  },
  "<TASK_ID_4>": {
    "status": "Publish failed",
    "retrieval_endpoint": "https://asstore.reincubate.com/fetch/1111111-2222-3333-4444-555555555555/",
    "success": false,
    "error": "Task did not complete successfully.",
    "retrieval_protocol": "asstore",
    "result_retrieved": false
  },
  "<TASK_ID_5>": {
    "status": "Pending",
    "result_retrieved": false,
    "success": false
  },
  "<TASK_ID_6>": {
    "status": "In progress",
    "result_retrieved": false,
    "success": false
  },
  "<TASK_ID_7>": {
    "status": "Work complete",
    "result_retrieved": false,
    "success": false
  },
  "success": true,
}

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

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

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

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

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

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