Платформа 3V/Соединение с источником/Импорт через Mongo: различия между версиями

Материал из 3v-wiki
Перейти к навигации Перейти к поиску
 
(не показано 16 промежуточных версий 3 участников)
Строка 16: Строка 16:
 
Пример настройки подключения в Compass:<br>
 
Пример настройки подключения в Compass:<br>
 
[[Файл:compass connection.jpg|Строка соединения в MongoDB Compass]]
 
[[Файл:compass connection.jpg|Строка соединения в MongoDB Compass]]
 +
 +
== Доступ к сваггеру ==
 +
Доступ к методам сервиса импорта из монго можно получить либо через агрегированый сваггер по адресу ''<адрес_сервера>/swagger/index.html''<br>
 +
Либо, если по каким-то причинам агрегированный сваггер не настроен на конкретном стенде, то адрес сваггера сервиса импорта из монго ''<адрес_сервера>/mongodictionaries/swagger/index.html''
  
 
== Метод Import ==
 
== Метод Import ==
Строка 37: Строка 41:
 
== Метод ImportWithAttributes ==
 
== Метод ImportWithAttributes ==
 
Импортирует коллекцию из БД монго в справочник, выбирая из документов указанные поля и записывая их в соответствующие атрибуты справочника.
 
Импортирует коллекцию из БД монго в справочник, выбирая из документов указанные поля и записывая их в соответствующие атрибуты справочника.
 +
Параметр метода, это JSON следующего вида:
 +
 +
<syntaxhighlight lang="JSON">
 +
{
 +
"connectionId": 18761,
 +
"dbName": "trv",
 +
"collectionName": "TestCollection",
 +
"parentId": 18760,
 +
"attributes": [
 +
{
 +
"name": "Last_name",
 +
"dataType": "String",
 +
"innerAttributePath": "field1"
 +
},
 +
{
 +
"name": "Birthday",
 +
"dataType": "DateTime",
 +
"innerAttributePath": "birthdayAsString.birthday"
 +
},
 +
{
 +
"name": "Element_of_array",
 +
"dataType": "String",
 +
"innerAttributePath": "field4[0].field1"
 +
}
 +
]
 +
}
 +
</syntaxhighlight>
 +
 +
Здесь '''connectionId''', '''dbName''', '''collectionName''' и '''parentId''' - имеют тот же смысл, что и параметры метода Import.
 +
 +
Далее идет перечень импортируемых атрибутов.
 +
 +
<syntaxhighlight lang="JSON">
 +
"attributes": [
 +
{
 +
"name": "Last_name",
 +
"dataType": "String",
 +
"innerAttributePath": "field1"
 +
},
 +
        ...
 +
    ]
 +
</syntaxhighlight>
 +
 +
'''name''' - это имя атрибута в создаваемом справочнике. Имя не должно сопадать с зарезервироваными именами для служебных атрибутов (id, name, code, parent_id и ord). Так же имя не может содержать пробелы.
 +
 +
'''dataType''' - тип данных создаваемого атрибута. Допустимые типы данных: String, Integer, Double, DateTime, Boolean. Для того, чтобы посмотреть какой тип данных у поля документа в монго, необходимо зайти в режим редактирования документа (см. скриншот ниже).
 +
 +
[[Файл:compass edit document btn.jpg]]
 +
 +
[[Файл:compass fields data types.jpg]]
 +
 +
Указываемый тип загружаемого атрибута должен совпадать с типом поля в монго. Есть два исключения: если в документах монго поле строковое, но в нем содержаться целые числа (причем '''во всех документах в загружаемой коллекции''' - это важно), его можно загрузить как Integer. А также, если в документах поле строковое, но в нем содержится дата, то такое поле можно загрузить в атрибут типа DateTime.
 +
 +
'''innerAttributePath''' - путь (в формате JSONPath) к значению атрибута в структуре документа из загружаемой коллекции монго. JSONPath позволяет ссылаться на конкретное значение свойства в документе. Каждый документ в монго можно представить в формате JSON (см. скриншот ниже).
 +
 +
[[Файл:compass document as json.jpg]]
 +
 +
Таким образом, если мы хотим импортировать значения из поля field1, которое является дочерним для поля field4, то innerAttributePath будет "field4.field1". Подробнее про синтаксис JSONPath можно прочитать здесь - https://support.smartbear.com/alertsite/docs/monitors/api/endpoint/jsonpath.html
  
 
== Метод ImportWithAttributesBackground ==
 
== Метод ImportWithAttributesBackground ==
 
Делает тоже самое, что и метод ImportWithAttributes, но импорт делается в фоновом режиме. Этот метод надо использовать для импорта больших коллекций (если их не удалось импортировать с помощью ImportWithAttributes, т.к. он упал по таймауту).
 
Делает тоже самое, что и метод ImportWithAttributes, но импорт делается в фоновом режиме. Этот метод надо использовать для импорта больших коллекций (если их не удалось импортировать с помощью ImportWithAttributes, т.к. он упал по таймауту).
 +
 +
Данный метод работает точно так же как и метод Import и принимает в качестве параметра точно такое же описание загружаемых атрибутов, но импорт справочника будет происходить в фоновом режиме. Метод возвращает GUID фоновой задачи импорта (см. скриншот ниже).
 +
 +
[[Файл:mongo background task guid.jpg]]
 +
 +
Для того, чтобы узнать, закончился ли импорт справочника, необходимо этот GUID использовать при вызове метода GetBackgroundImportStatus.
  
 
== Метод GetBackgroundImportStatus ==
 
== Метод GetBackgroundImportStatus ==
Контроль статуса ранее запущеных фоновых задач импорта.
+
Контроль статуса ранее запущеных фоновых задач импорта. Метод нужно вызывать, подставляя в него GUID (без кавычек) фоновой задачи импорта, который возвращается методом ImportWithAttributesBackground.
 +
Результатом выполнения метода является структура вида
 +
<syntaxhighlight lang="JSON">
 +
{
 +
  "isCompleted": true,
 +
  "status": "RanToCompletion"
 +
}
 +
</syntaxhighlight>
 +
 
 +
'''isCompleted''' - флаг завершенности задачи (true - задача импорта завершена, false - импорт справочника еще не завершен).<br>
 +
'''status''' - результат завершения задачи импорта. Из возможных значений статусов, нас интересуют два: RanToCompletion - задача завершена успешно и Faulted - задача завершилась с ошибкой.
 +
 
 +
== Метод Reload ==
 +
Полная перезагрузка ранее загруженного из монго справочника. Необходимо иметь ввиду, что при полной перезагрузке идентификаторы элементов не сохраняются и будут присвоены элементам заново и в произвольном порядке. Параметр метода - идентификатор перезагружаемого справочника.
 +
 
 +
== Метод Update ==
 +
Обновление ранее загруженного из монго справочника. При обновлении (в отличие от Reload), идентификаторы обновляемых элементов не изменяются. Параметр метода - идентификатор обновляемого справочника.
 +
 
 +
== Метод UpdateWithAttributes ==
 +
Обновление ранее загруженного из монго справочника с одновременным добавлением в справочник новых атрибутов.
 +
 
 +
Параметр метода:
 +
<syntaxhighlight lang="JSON">
 +
{
 +
  "dictionaryId": 18852,
 +
  "attributes": [
 +
    {
 +
      "name": "mongo_name",
 +
      "dataType": "String",
 +
      "innerAttributePath": "name"
 +
    }
 +
  ]
 +
}
 +
</syntaxhighlight>
  
== Метод
+
'''dictionaryId''' - идентификатор обновляемого справочника.<br>
 +
'''attributes''' - коллекция атрибутов, которые будут добавлены в справочник при обновлении. В результате выполнения метода произойдет обновление существующих атрибутов, плюс загрузятся атрибуты перечисленные в данной коллекции.

Текущая версия на 11:11, 21 сентября 2021

Импорт справочников из БД Mongo

Для работы с монго желательно, помимо собственно платформы, установить какую-либо утилиту для подключения к серверам монго и просмотра их содержимого. Рекомендую пользоваться бесплатной MongoDB Compass (https://www.mongodb.com/try/download/compass).

Настройка соединения с монго

Создаем объект "Соединение с БД" в платформе. В json-редакторе созданного соединения прописываем строку соединения с монго.

Пример:

 {
   "dbType": "MongoDb",
   "connectionString": "mongodb://mongoadmin:mongoadmin@192.168.228.25:27017/?authSource=admin&readPreference=primary&appname=MongoDB%20Compass&ssl=false"
 }

Если в Compass подключение уже было настроено, то эту строку можно скопировать из настроек.
Пример настройки подключения в Compass:
Строка соединения в MongoDB Compass

Доступ к сваггеру

Доступ к методам сервиса импорта из монго можно получить либо через агрегированый сваггер по адресу <адрес_сервера>/swagger/index.html
Либо, если по каким-то причинам агрегированный сваггер не настроен на конкретном стенде, то адрес сваггера сервиса импорта из монго <адрес_сервера>/mongodictionaries/swagger/index.html

Метод Import

Импортирует коллекцию из БД монго в справочник.
Параметры:
connectionId - идентификатор ранее настроенного соединения с монго.
dbName - имя базы данных монго (это имя можно посмотреть, например, в Compass, подключившись к нужному серверу, см. рисунок ниже).

Строка соединения в MongoDB Compass

collectionName - имя импортируемой коллекции (список коллекций в конкретной БД смотрим в Compass).

Имена коллекций в монго

parentId - идентификатор родительской папки в которой будет создан импортируемый справочник.

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

Метод Import (атрибуты по умолчанию)

Метод ImportWithAttributes

Импортирует коллекцию из БД монго в справочник, выбирая из документов указанные поля и записывая их в соответствующие атрибуты справочника. Параметр метода, это JSON следующего вида:

 {
	"connectionId": 18761,
	"dbName": "trv",
	"collectionName": "TestCollection",
	"parentId": 18760,
	"attributes": [
		{
			"name": "Last_name",
			"dataType": "String",
			"innerAttributePath": "field1"
		},
		{
			"name": "Birthday",
			"dataType": "DateTime",
			"innerAttributePath": "birthdayAsString.birthday"
		},
		{
			"name": "Element_of_array",
			"dataType": "String",
			"innerAttributePath": "field4[0].field1"
		}
	]
 }

Здесь connectionId, dbName, collectionName и parentId - имеют тот же смысл, что и параметры метода Import.

Далее идет перечень импортируемых атрибутов.

	"attributes": [
		{
			"name": "Last_name",
			"dataType": "String",
			"innerAttributePath": "field1"
		},
        ...
     ]

name - это имя атрибута в создаваемом справочнике. Имя не должно сопадать с зарезервироваными именами для служебных атрибутов (id, name, code, parent_id и ord). Так же имя не может содержать пробелы.

dataType - тип данных создаваемого атрибута. Допустимые типы данных: String, Integer, Double, DateTime, Boolean. Для того, чтобы посмотреть какой тип данных у поля документа в монго, необходимо зайти в режим редактирования документа (см. скриншот ниже).

compass edit document btn.jpg

compass fields data types.jpg

Указываемый тип загружаемого атрибута должен совпадать с типом поля в монго. Есть два исключения: если в документах монго поле строковое, но в нем содержаться целые числа (причем во всех документах в загружаемой коллекции - это важно), его можно загрузить как Integer. А также, если в документах поле строковое, но в нем содержится дата, то такое поле можно загрузить в атрибут типа DateTime.

innerAttributePath - путь (в формате JSONPath) к значению атрибута в структуре документа из загружаемой коллекции монго. JSONPath позволяет ссылаться на конкретное значение свойства в документе. Каждый документ в монго можно представить в формате JSON (см. скриншот ниже).

compass document as json.jpg

Таким образом, если мы хотим импортировать значения из поля field1, которое является дочерним для поля field4, то innerAttributePath будет "field4.field1". Подробнее про синтаксис JSONPath можно прочитать здесь - https://support.smartbear.com/alertsite/docs/monitors/api/endpoint/jsonpath.html

Метод ImportWithAttributesBackground

Делает тоже самое, что и метод ImportWithAttributes, но импорт делается в фоновом режиме. Этот метод надо использовать для импорта больших коллекций (если их не удалось импортировать с помощью ImportWithAttributes, т.к. он упал по таймауту).

Данный метод работает точно так же как и метод Import и принимает в качестве параметра точно такое же описание загружаемых атрибутов, но импорт справочника будет происходить в фоновом режиме. Метод возвращает GUID фоновой задачи импорта (см. скриншот ниже).

mongo background task guid.jpg

Для того, чтобы узнать, закончился ли импорт справочника, необходимо этот GUID использовать при вызове метода GetBackgroundImportStatus.

Метод GetBackgroundImportStatus

Контроль статуса ранее запущеных фоновых задач импорта. Метод нужно вызывать, подставляя в него GUID (без кавычек) фоновой задачи импорта, который возвращается методом ImportWithAttributesBackground. Результатом выполнения метода является структура вида

 {
   "isCompleted": true,
   "status": "RanToCompletion"
 }

isCompleted - флаг завершенности задачи (true - задача импорта завершена, false - импорт справочника еще не завершен).
status - результат завершения задачи импорта. Из возможных значений статусов, нас интересуют два: RanToCompletion - задача завершена успешно и Faulted - задача завершилась с ошибкой.

Метод Reload

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

Метод Update

Обновление ранее загруженного из монго справочника. При обновлении (в отличие от Reload), идентификаторы обновляемых элементов не изменяются. Параметр метода - идентификатор обновляемого справочника.

Метод UpdateWithAttributes

Обновление ранее загруженного из монго справочника с одновременным добавлением в справочник новых атрибутов.

Параметр метода:

{
  "dictionaryId": 18852,
  "attributes": [
    {
      "name": "mongo_name",
      "dataType": "String",
      "innerAttributePath": "name"
    }
  ]
}

dictionaryId - идентификатор обновляемого справочника.
attributes - коллекция атрибутов, которые будут добавлены в справочник при обновлении. В результате выполнения метода произойдет обновление существующих атрибутов, плюс загрузятся атрибуты перечисленные в данной коллекции.