Motimate: Як генерувати звіти за допомогою публічного API

На додаток до обміну даними про завершення курсу через Motimate xAPIми також підтримуємо вивантаження Excel-файлів з Motimate Public API. Ці Excel-звіти базуються на шаблонах звітів, які були раніше створені в розділі Створювати звіти в розділі Інсайти в Motimate.

Перш ніж ми почнемо, пропонуємо вам ознайомитися з деякою корисною інформацією:

Три відповідні функції Motimate Public API:

• GET /insights/learnings/report_templates
   
• POST /insights/learnings/report_requests
   
• GET /insights/learnings/report_requests/{id}

Перш ніж створювати звіт за допомогою Публічного API, переконайтеся, що шаблон звіту вже створено в розділі Створення звітів(див. інструкцію тут), і ви знаєте, на основі якого шаблону (шаблонів) ви будете створювати звіт (звіти). За умови, що це буде готово, процес створення звіту вимагатиме трьох кроків:

Крок 1: Отримайте список шаблонів звітів:

Команда: GET /insights/learnings/report_templates

Приклад відповіді:

{
  "data": [
    {
      **"id": "abc86b82-029a-4b74-9690-4ab607f3eafe "**,
      "name": "Report Test",
      "description": "Тестування для публічного API",
      "last_status": "uploading",
      "last_generated_at": null,
      "created_at": "2022-03-01T15:36:42.99789+01:00",
      "updated_at": "2022-03-01T15:41:26.98349+01:00",
      "user": {
        "name": "John Doe"
      }
    }
  ]
}

Запишіть ідентифікатор шаблону, який вам знадобиться на наступному кроці, в даному випадку: abc86b82-029a-4b74-9690-4ab607f3eafe

Крок 2: Створіть новий звіт на основі обраного шаблону

Командний: POST /insights/learnings/report_requests

У цьому прикладі переконайтеся, що в якості template_id у запиті вказано abc86b82-029a-4b74-9690-4ab607f3eafe.

Приклад відповіді:

{
  "data": {
    **"id": "abc23922-940d-4d6d-a6f0-ecaed00810c4"**,
    "status": "started",
    "created_at": "2022-03-03T08:48:46.051Z",
    "updated_at": "2022-03-03T08:48:46.051Z",
    "url": null,
    "template": {
      "id": "abc86b82-029a-4b74-9690-4ab607f3eafe",
      "name": "Report Test",
      "description": "Тестування для публічного API", "created_at":
      "created_at": "2022-03-01T15:36:42.99789+01:00",
      "updated_at": "2022-03-03T09:48:46.06885+01:00"
    }
  }
}

Зверніть увагу, що значення для url поки що недоступне. Залежно від обсягу даних, що потрапляють до звіту, його створення може зайняти кілька хвилин. На наступному кроці ви отримаєте запит на URL-адресу вашого звіту.

Крок 3: Отримайте URL-адресу файлу звіту в Excel

Командний: GET /insights/learnings/report_requests/{id}

Переконайтеся, що ви використовуєте ідентифікатор даних у відповіді з кроку 2, а не ідентифікатор шаблону!

Приклад відповіді:

{
  "data": {
    "id": "abc23922-940d-4d6d-a6f0-ecaed00810c4",
    "status": "done",
    "created_at": "2022-03-03T08:48:46.051Z",
    "updated_at": "2022-03-03T08:48:46.839Z",
    **"url": "<https://motimate-reports-production.s3.eu-west-1.amazonaws.com/abc883af5017bcb49a6b99e71b01a0660b8f5204/report-test_1646297326.xlsx?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ABCAYLEQ6WVKO52OZP5X%2F20220303%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20220303T085426Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=abc3806250e855b83fc121ea181764cc6df64481c63371004a27229acbaf98de>"**,
    "template": {
      "id": "abc86b82-029a-4b74-9690-4ab607f3eafe",
      "name": "Report Test",
      "description": "Тестування для публічного API", "created_at":
      "created_at": "2022-03-01T15:36:42.99789+01:00",
      "updated_at": "2022-03-03T09:48:46.70689+01:00"
    }
  }
}

Можливо, вам доведеться повторювати цей запит кожні 30 секунд, поки не отримаєте відповідь, яка містить значення url. Скільки часу це займе, залежить від обсягу даних, необхідних для створення звіту.

У цьому прикладі URL буде https://motimate-reports-production.s3.eu-west-1.amazonaws.com/abc883af5017bcb49a6b99e71b01a0660b8f5204/report-test_1646297326.xlsx?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ABCAYLEQ6WVKO52OZP5X%2F20220303%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20220303T085426Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=abc3806250e855b83fc121ea181764cc6df64481c63371004a27229acbaf98de

Перейшовши за цією URL-адресою, ви завантажите ваші звіти у форматі .xlxs Excel. Наразі неможливо витягти дані в інших форматах файлів, таких як, наприклад, .csv.

Будь ласка, зверніть увагу: термін дії файлу закінчується через 10 хвилин, і його необхідно завантажити до цього часу.

ℹ️ Якщо шаблон звіту був створений адміністратором групи, який має лише обмежений доступ до даних про вибрані групи та користувачів, це обмеження буде діяти і при використанні Motimate Public API.