Доступ до контенту файлів реєстру через зовнішні API

Загальний опис

У цій статті буде розглянута реалізація можливості віддавати контент файлів збережених у реєстрі через зовнішні API. Наразі ця можливість відсутня і контент файлів можливо отримати тільки з бізнес процесу який є частиною реєстру в якому зберігається файл.

Актори та ролі користувачів

Розробник регламенту
Зовнішні системи

Загальні принципи та положення

Поведінка і контракт існуючих критеріїв пошуку не змінюється.
Зберігається зворотна сумісність конфігурації критеріїв пошуку.
Отримання файлів відбувається окремим запитом.
Точки інтеграції створюються лише за наявності полів типу file або file[] в регламенті

Функціональні сценарії

Налаштування критеріїв пошуку
Генерація сервісів критеріїв пошуку
Доступ до контенту файлів через публічний АРІ
Доступ до контенту файлів через міжреєстрову взаємодію без Трембіти
Доступ до контенту файлів через міжреєстрову взаємодію через Трембіту
Доступ до контенту файлів для публічної форми (майбутня функціональність) з EditGrid

Поточна реалізація

В поточній реалізації доступ до файлів реалізований лише для підсистеми виконання бізнес-процесів. Працює він наступним чином:

Підсистема виконання бізнес-процесів робить виклик на registry-rest-api і окрім всього іншого передає в хедері запиту ідентифікатор бізнес-процесу
registry-rest-api по хедеру розуміє що запит прийшов з підсистеми виконання бізнес-процесів
registry-rest-api отримує дані що запитані з БД реєстру.
Якщо серед даних є дані типу type_file, тобто дані що містять ідентифікатори файлів в бакеті file-ceph-bucket, то всі ці файли копіюються у бакет lowcode-file-storage по шляху який дорівнює ідентифікатор бізнес-процесу та який є доступним для підсистеми виконання бізнес-процесів.
Підсистема виконання бізнес-процесів отримує відповідь з даними що запитані, включаючи ідентифікатори файлів.
Підсистема виконання бізнес-процесів читає вміст файлів з lowcode-file-storage

Всі інші запити до registry-rest-api та його копій (ext та pub) не отримують ідентифікатор бізнес-процесу в хедері та не повертають ідентифікатори файлів (замість них пусте поле) та не копіюють файли з file-ceph-bucket в lowcode-file-storage.

Таким чином для зовнішніх систем не передбачено жодного механізму для отримання контенту файлів що збережені в реєстрі.

Високорівневий дизайн рішення

Повернення інформації про файли які міститься в сутності

При запиті сутностей, що містять тип файл або масив файлів при відсутності заголовків з інформацією про бізнес-процес повертається структура з ідентифікатором файлу з кошика file-ceph-bucket. При цьому не відбувається копіювання файлів.

Приклад сутності

 <createTable tableName="user" ext:historyFlag="true">
            <column name="user_id" type="UUID" defaultValueComputed="uuid_generate_v4()">
                <constraints nullable="false" primaryKey="true" primaryKeyName="pk_koatuu_id"/>
            </column>
            <column name="name" type="TEXT">
                <constraints nullable="false"/>
            </column>
            <column name="photo" type="file">
                <constraints nullable="false"/>
            </column>
            <column name="documents" type="file[]">
                <constraints nullable="false"/>
            </column>
        </createTable>

Приклад відповіді на запит пошуку сутності за ідентифікатором

{
  "userId": "uuid1-user",
  "name": "Petro",
  "photo": {
    "id": "uuid2-photo",
    "checksum": "..."
  },
  "documents": [
    {
        "id": "uuid3-passport",
        "checksum": "..."
    },
    {
        "id": "uuid4-driver-licence",
        "checksum": "..."
    }]
}

Створення окремих точок інтеграції для отримання вмісту файлів.

Шаблон формування посилання до вмісту файлу

HTTP GET /api/data-factory/files/{entity}/{entityId}/{fieldName}/{fieldId}

Данна точка інтеграції наслідує всі правила застосування RBAC.

Така точка інтеграції доступна в rest-api якщо в моделі даних є хоча б одне поле типу file або file[].
В сервісах rest-api-ext та rest-api-public правила Istio налаштовані так, що доступ до цих посилань для користувачів з реалму external_systems є тільки за умови якщо хоча б один searchCondition що містить в собі тип file або file[] був виставлений через тег <exposeSearchCondition/>

Посилання для прикладу

HTTP GET /api/data-factory/files/user/uuid1-user/photo/uuid2-photo

Посилання для прикладу для доступу до конкретних документів в масиві

GET /api/data-factory/files/user/uuid1-user/documents/uuid3-passport
GET /api/data-factory/files/user/uuid1-user/documents/uuid4-driver-licence

Дане посилання підтримує запити двох типів контенту application/json і при такому запиті повертає структуру JSON, вміст файлу закодований у Base64 в якості значення поля content з мета інформацією про файл у checksum та fileName

Приклад запиту для отримання відповіді в JSON форматі

GET /api/data-factory/files/user/uuid1-user/documents/uuid3-passport
Accept: application/json

HTTP/1.1 200 OK
Content-Type: text/html; charset=UTF-8

{
    "contetn": "passport in Base64",
    "checksum": "..."
    "fileName": "petro_passport.pdf"
}

Запити між soap-api та rest-api для файлів відбуваються саме таким чином, а трансформація об’єкта для передачі по SOAP_Trembita відбувається безпосередньо на soap-api

Якщо в запиті не зазначено, що в якості відповіді очікується application/json, то типи визначаються динамічно в залежності від типу файлу. Додатково проставляються заголовки Content-Disposition із значенням attachment та вказанням атрибуту filename взятого з метаданих про файл. Такі посилання можна буде формувати в бізнес-процесах, та публікувати на користувацьких формах, для завантаження файлів безпосередньо з форм.

Приклад запиту для скачування файлу

GET /api/data-factory/files/user/uuid1-user/documents/uuid3-passport

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="petro_passport.pdf"

... (binary PDF data)

Виставлення точок інтеграції які повертають файли для публічного доступу

У випадку з наданням доступу до публічних даних, передбачено надання доступу до індивідуальних ресурсів з встановленням лімітів. Оскільки доступ надається індивідуально то в загальному вигляді заборонено використання wildcard * у шляхах. Разом з тим для файлів у відповідності до найкращих практик побудови REST API використовується path_variable, тому передбачено окремий тип точок інтеграції який дозволяє використовувати wildcard але строго в заздалегіть визначеному шаблоні.

GET /api/data-factory/files/${tableName}/*/${column}/*

Figure 1. Інтерфейс для надання публічного доступу до файлів

Високорівневий план розробки

Технічні експертизи

План розробки

Створення окремого сценарію при відсутності заголовків з інформацією про бізнес-процес
Створення точок інтеграції для отримання контенту в rest-api
Оновлення клієнту soap-api
Зміна правил Istio по наданню доступів до точок інтеграції повʼязаних з отриманнями вмісту файлів
Референтний процес