Методические рекомендации по интеграции шаблонов цифрового следа в информационные системы провайдера
Наиболее типичные ошибки отправки цифрового следа
1) Неверно сформированное тело http-запроса с точки зрения синтаксиса json (лишние кавычки, отсутствие скобок и тд);
2) Отсутствие, либо неверное размещение объектов в дереве json (не тот уровень вложенности), что ведет либо к ошибкам http 400 (bad request), либо к ошибкам обработки ( отсутствие связи с потоком, следом слушателя/методиста).
Наиболее простой способ застраховать себя от возникновения подобных ошибок нарушения структуры - переложить контроль формирования строки запроса и типизации значений атрибутов с конкатенации строки и программиста, реализующего интеграцию шаблонов в информационные системы, на уровень языка/компилятора/интерпретатора.
3) Игнорирование кода ответа.
Успешным считается только код ответа 200 (ОК), другие коды ответов, в том числе 201, 202, 204 и тд успешными не считаются.
1. Работа с шаблонами запросов в postman
Интерфейс postman позволяет выполнять запросы http и получать ответы, что позволяет удостовериться в корректности(или некорректности) предложенных примеров и отладить свои примеры без влияния промышленного контура информационных систем.
Postman позволяет автоматически генерировать код для выполнения запросов в разных языках программирования.
Для того, чтобы иметь возможность воспроизводить запросы из интерфейса postman Выполните Fork коллекции, нажав на многоточие возле названия коллекции (templates слева) и нажав Create a fork.
В случае необходимости указать {{baseUrl}} создайте новое окружение (New Environment) и укажите baseUrl lrs-external.u2035test.ru
Теперь вместо {{baseUrl}} будет подставляться lrs-external.u2035test.ru
После этого кнопка Send активна и будет выполнять запрос в соответствии с указанными значениями параметров, если они указаны - это можно использовать для отладки.
Подробнее о работе с Postman можно ознакомиться в официальной документации:
https://learning.postman.com/docs/getting-started/basics/navigating-postman/
https://learning.postman.com/docs/sending-requests/requests/
2. Генерация кода
Postman позволяет генерировать программный код на основании шаблонов запроса для использования в различных языках программирования.
1. Выберите запрос.
2. Нажмите Code (иконка в правом углу).
Вам станет доступно окно кодогенерации, причем сверху (под надписью code snippet) будет доступен выпадающий список языков.
3. На скриншоте представлен пример сгенерированного программного кода для языка PHP.
4. Обратите внимание, что с точки зрения программного кода вы можете использовать как строку, так и построенную вокруг нее объектную модель.
5. Скопируйте сгенерированный код.и вставьте в свою среду разработки – этот код позволит вам воспроизвести сеанс клиент-серверного взаимодействия и лучше понять ожидаемый результат.
6. Для отправки промышленных данных необходимо сформировать запрос, содержащий json, наполненный соответствующими промышленными актуальными значениями.
7. Например, для примера json[
{
"actor": {
"account": {
"homePage": "https://my.2035.university",
"name": "4828670"
},
"name": "Васильев Виталий Викторович",
"objectType": "Agent"
},
"verb": {
"id": "http://adlnet.gov/expapi/verbs/answered",
"display": {
"en": "answered",
"ru": "Ответил на вопрос"
}
},
"object": {
"id": "https://yourlms.ru/page",
"objectType": "Activity",
"definition": {
"type": "http://id.tincanapi.com/activitytype/survey",
"name": {
"ru-RU": "Чему были посвящены занятия в рамках пройденной недели и что было для вас новым?"
},
"description": {
"ru-RU": "Перечислите темы, чему были посвящены занятие, описывайте вседостаточно подробно"
},
"extensions": {
"https://id.2035.university/xapi/extension/refl_object": "week",
"https://id.2035.university/xapi/extension/refl_question": "refl_new"
}
}
},
"result": {
"response": "Ответ студента",
"completion": true
},
"context": {
"platform": "https://yourlms.ru",
"extensions": {
"http://id.tincanapi.com/extension/ip-address": "192.168.0.1",
"https://api.2035.university/actor_id": "https://yourlms.ru/users/user_id",
"https://api.2035.university/parent_course_id": 8538660,
"https://api.2035.university/flow_num": 1,
"https://api.2035.university/flow_id": 756,
"https://api.2035.university/module_num": 1,
"https://api.2035.university/module_id": 1423,
"https://api.2035.university/project": "Обучение БАС",
"https://api.2035.university/project_id": 50
}
}
}
]
Можно сформировать следующий набор классов (пример на PHP):
(Представлен как пример, провайдеру следует определить свой в соответствии с актуальными шаблонами)
class Account {
public string $homePage;
public string $name;
}
class Actor {
public Account $account;
public string $name;
public string $objectType;
}
class Verb {
public string $id;
public array $display;
}
class ObjectDefinition {
public string $type;
public array $name;
public array $description;
public array $extensions;
}
class XAPIObject {
public string $id;
public string $objectType;
public ObjectDefinition $definition;
}
class Result {
public string $response;
public bool $completion;
}
class Context {
public string $platform;
public array $extensions;
}
class XAPIStatement {
public Actor $actor;
public Verb $verb;
public XAPIObject $object;
public Result $result;
public Context $context;
}
Заполнить свойства объекта описанного выше класса
// Заполнение объекта
$statement = new XAPIStatement();
$statement->actor = new Actor();
$statement->actor->account = new Account();
$statement->actor->account->homePage = "https://my.2035.university";
$statement->actor->account->name = "4828670";
$statement->actor->name = "Васильев Виталий Викторович";
$statement->actor->objectType = "Agent";
$statement->verb = new Verb();
$statement->verb->id = "http://adlnet.gov/expapi/verbs/answered";
$statement->verb->display = ["en" => "answered", "ru" => "Ответил на вопрос"];
$statement->object = new XAPIObject();
$statement->object->id = "https://yourlms.ru/page";
$statement->object->objectType = "Activity";
$statement->object->definition = new ObjectDefinition();
$statement->object->definition->type = "http://id.tincanapi.com/activitytype/survey";
$statement->object->definition->name = ["ru-RU" => "Чему были посвящены занятия..."];
$statement->object->definition->description = ["ru-RU" => "Перечислите темы..."];
$statement->object->definition->extensions = [
"https://id.2035.university/xapi/extension/refl_object" => "week",
"https://id.2035.university/xapi/extension/refl_question" => "refl_new"
];
$statement->result = new Result();
$statement->result->response = "Ответ студента";
$statement->result->completion = true;
$statement->context = new Context();
$statement->context->platform = "https://yourlms.ru";
$statement->context->extensions = [
"http://id.tincanapi.com/extension/ip-address" => "192.168.0.1",
"https://api.2035.university/actor_id" => "https://yourlms.ru/users/user_id",
"https://api.2035.university/project" => "Цифровые профессии",
"https://api.2035.university/project_id" => 50
];
//И преобразовать объект в JSON
$json = json_encode([$statement], JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT);
echo $json;
Далее передать сформированную строку как тело http-запроса.
Аналогичный пример на языке c#:
using System;
using System.Collections.Generic;
using Newtonsoft.Json;
public class Account
{
public string homePage { get; set; }
public string name { get; set; }
}
public class Actor
{
public Account account { get; set; }
public string name { get; set; }
public string objectType { get; set; }
}
public class Verb
{
public string id { get; set; }
public Dictionary<string, string=""> display { get; set; }</string,>
}
public class ObjectDefinition
{
public string type { get; set; }
public Dictionary<string, string=""> name { get; set; }
public Dictionary<string, string=""> description { get; set; }
public Dictionary<string, string=""> extensions { get; set; }</string,></string,></string,>
}
public class XAPIObject
{
public string id { get; set; }
public string objectType { get; set; }
public ObjectDefinition definition { get; set; }
}
public class Result
{
public string response { get; set; }
public bool completion { get; set; }
}
public class Context
{
public string platform { get; set; }
public Dictionary<string, object=""> extensions { get; set; }</string,>
}
public class XAPIStatement
{
public Actor actor { get; set; }
public Verb verb { get; set; }
public XAPIObject @object { get; set; }
public Result result { get; set; }
public Context context { get; set; }
}
class Program
{
static void Main()
{
var statement = new XAPIStatement
{
actor = new Actor
{
account = new Account
{
homePage = "https://my.2035.university",
name = "4828670"
},
name = "Васильев Виталий Викторович",
objectType = "Agent"
},
verb = new Verb
{
id = "http://adlnet.gov/expapi/verbs/answered",
display = new Dictionary<string, string="">
{</string,>
{ "en", "answered" },
{ "ru", "Ответил на вопрос" }
}
},
@object = new XAPIObject
{
id = "https://yourlms.ru/page",
objectType = "Activity",
definition = new ObjectDefinition
{
type = "http://id.tincanapi.com/activitytype/survey",
name = new Dictionary<string, string=""> { { "ru-RU", "Чему были посвящены занятия..." } },
description = new Dictionary<string, string=""> { { "ru-RU", "Перечислите темы..." } },
extensions = new Dictionary<string, string="">
{</string,></string,></string,>
{ "https://id.2035.university/xapi/extension/refl_object", "week" },
{ "https://id.2035.university/xapi/extension/refl_question", "refl_new" }
}
}
},
result = new Result
{
response = "Ответ студента",
completion = true
},
context = new Context
{
platform = "https://yourlms.ru",
extensions = new Dictionary<string, object="">
{</string,>
{ "http://id.tincanapi.com/extension/ip-address", "192.168.0.1" },
{ "https://api.2035.university/actor_id", "https://yourlms.ru/users/user_id" },
{ "https://api.2035.university/project", "Обучение БАС" },
{ "https://api.2035.university/project_id", 50 }
}
}
};
// Преобразование в JSON
string json = JsonConvert.SerializeObject(new List<xapistatement> { statement }, Formatting.Indented);
Console.WriteLine(json);</xapistatement>
}
}
Классы на основе json можно сформировать автоматически при помощи различных инструментов, в том числе онлайн-сервисов.