Поиск и маскирование сущностей в файлах

С помощью API Jay Guard вы можете проверять файлы на наличие сущностей и маскировать их — в зависимости от формата файла:

Настройте фильтр с правилами обработки сущностей.
Привяжите ваш фильтр к ключу доступа.
Используйте ключ доступа для отправки запросов к API Jay Guard.

Методы

Управление файлами в хранилище

Метод	Назначение	Спецификация
`POST /api/dataguard/public/files`	Загрузка файла в хранилище.	Перейти
`GET /api/dataguard/public/files/{fileId}`	Скачивание файла из хранилища по идентификатору файла.	Перейти
`DELETE /api/dataguard/public/files/{fileId}`	Удаление файла из хранилища по идентификатору файла.	Перейти

Маскирование сущностей в файлах

Метод	Назначение	Спецификация
`PUT /api/dataguard/public/user-masking/storage/mask`	Маскирование сущностей в файле, ранее загруженном в хранилище.	Перейти
`POST /api/dataguard/public/user-masking/files/mask`	Загрузка файла в хранилище и запуск маскирования файла.	Перейти
`GET /api/dataguard/public/user-masking/files/result`	Получение результата маскирования файла.	Перейти

Особенности обработки файлов

Файлы обрабатываются в зависимости от их формата.
Если в файле есть сущности, к которым должны применяться разные действия, применяются правила с самым приоритетным действием. Приоритетность действий (от меньшего к большему): allow, redact, deny. Правила с менее приоритетными действиями игнорируются.

Например, если для сущности Личность задано действие deny, а для сущности Телефон — redact, то к сущности Личность применится действие deny, при этом правило для сущности Телефон будет проигнорировано.
Если к сущностям применяется действие redact, запрос GET /api/dataguard/public/user-masking/files/result для простых текстовых файлов возвращает идентификатор файла с маскированными сущностями.

Используйте его в запросе GET /api/dataguard/public/files/{fileId}, чтобы скачать файл.

предупреждение

Сейчас нельзя обработать один и тот же файл в хранилище несколько раз, применяя разные фильтры. Запоминается только первый результат обработки. Если вы хотите обработать файл повторно, загрузите его заново.
Срабатывания при проверке и маскировании сущностей в файлах не логируются в аудите.

Доступные форматы файлов

В зависимости от расширения Jay Guard обрабатывает файл и сущности по-разному:

Расширения Размер файла Действия Jay Guard

.c, .cpp, .css, .csv, .html, .java, .js, .json, .md, .php, .py, .rb, .tex, .ts, .txt, .xml

До 20 Мб

Расширения	Размер файла	Действия Jay Guard
.c, .cpp, .css, .csv, .html, .java, .js, .json, .md, .php, .py, .rb, .tex, .ts, .txt, .xml	До 20 Мб	Проверяет файл на наличие сущностей и применяет к ним правила с самым приоритетным действием. Запрос `GET /api/dataguard/public/user-masking/files/result` возвращает: для действий `allow` или `deny`: названия сущностей и действие; для действия `redact`: названия сущностей, действие и идентификатор файла с маскированными сущностями.
.docx, .pdf, .pptx, .xlsx	До 20 Мб	Проверяет файл на наличие сущностей и применяет к ним правила с самым приоритетным действием. Запрос `GET /api/dataguard/public/user-masking/files/result` всегда возвращает только названия сущностей и действие. Маскирование сущностей не выполняется.

Проверяет файл на наличие сущностей и применяет к ним правила с самым приоритетным действием.

Запрос GET /api/dataguard/public/user-masking/files/result возвращает:

для действий allow или deny: названия сущностей и действие;
для действия redact: названия сущностей, действие и идентификатор файла с маскированными сущностями.

.docx, .pdf, .pptx, .xlsx

До 20 Мб

Проверяет файл на наличие сущностей и применяет к ним правила с самым приоритетным действием.

Запрос GET /api/dataguard/public/user-masking/files/result всегда возвращает только названия сущностей и действие. Маскирование сущностей не выполняется.

Примеры

Давайте рассмотрим маскирование файлов. Это будут файлы TXT и DOCX с одинаковым содержимым. В тексте будут сущности Личность, а также номера телефонов:

На еженедельном собрании отдела маркетинга в головном офисе компании царила напряженная атмосфера. Ольга Петровна Смирнова, руководитель отдела, строго смотрела на собравшихся. Доклад Ивана о продвижении новой линейки продуктов на зарубежном рынке явно не впечатлил Петра Ильича, финансового директора. Он нахмурил брови и покачал головой. Мария, молодая стажерка, приехавшая из другого города, нервно теребила ручку.

"Иван, ваши цифры по продажам за границей неубедительны", - резко произнесла Ольга Петровна. - "Свяжитесь с нашим представителем в первой стране, его номер +7 916 123 45 67, он должен предоставить вам актуальную информацию. Андрей Сергеевич, вы как считаете?" Андрей Сергеевич Николаев, глава отдела продаж, только что вернувшийся из командировки, поддержал Петра Ильича: "Боюсь, Иван Алексеевич Иванов, нам нужны более весомые аргументы, особенно по второй стране. Позвоните нашему партнеру, +7 927 987 65 43, он владеет ситуацией на месте." Иван покраснел. Елизавета, менеджер по рекламе, пыталась спасти ситуацию: "Мы учтем ваши замечания, Петр Ильич. Иван Алексеевич Иванов уже разработал несколько новых стратегий, ориентированных на рынок третьей страны. Я уже связалась с коллегами, +7 965 456 78 90, они обещали поддержку".

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

Простой текстовый файл

Действие redact

Допустим, у нас настроено действие redact для сущностей Личность, и мы хотим отправить на проверку файл TXT.

Запустим проверку и возможное маскирование файла TXT. Поскольку мы уже загрузили файл в хранилище, воспользуемся методом PUT /api/dataguard/public/user-masking/storage/mask.

Отправим запрос:
```
curl -X 'PUT' \
'http://<base_URL>/api/dataguard/public/user-masking/storage/mask?file-id=615d7cfa-c611-4c33-8b6c-dcd6d48bd35a' \
-H 'accept: application/json' \
-H 'X-DATA-GUARD-API-KEY: <API_key_redact>'
```
В ответ нам придет идентификатор нашего файла:
```
{
  "fileId": "615d7cfa-c611-4c33-8b6c-dcd6d48bd35a"
}
```
Получим результат маскирования файла TXT. Для этого воспользуемся методом GET /api/dataguard/public/user-masking/files/result.

Отправим запрос:
```
curl -X 'GET' \
'http://<base_URL>/api/dataguard/public/user-masking/files/result?file-id=615d7cfa-c611-4c33-8b6c-dcd6d48bd35a' \
-H 'accept: application/json' \
-H 'X-DATA-GUARD-API-KEY: <API_key_redact>'
```
В ответ получим результат маскирования:
```
{
    "status": "READY",
    "action": "redact",
    "detectedEntities": [
        "person"
    ],
    "maskedFileId": "245d3b9e-758b-4e5a-86c5-654fbf3b6c79"
}
```
В этом ответе:
- status — статус выполнения операции;
- action — действие, примененное к сущностям;
- detectedEntities — обнаруженные сущности, для которых задано действие из action;
- maskedFileId — идентификатор файла с маскированными сущностями.

Скачаем TXT-файл с маскированными сущностями. Для этого воспользуемся методом GET /api/dataguard/public/files/{fileId}.

Отправим запрос:

curl -X 'GET' \
'http://<base_URL>/api/dataguard/public/files/245d3b9e-758b-4e5a-86c5-654fbf3b6c79' \
-H 'accept: application/json' \
-H 'X-DATA-GUARD-API-KEY: <API_key_redact>'

В ответ получим ссылку на скачивание файла. Скачаем его и посмотрим на результат:

На еженедельном собрании отдела маркетинга в головном офисе компании царила напряженная атмосфера. [jg:person_1], руководитель отдела, строго смотрела на собравшихся. Доклад [jg:person_2] о продвижении новой линейки продуктов на зарубежном рынке явно не впечатлил [jg:person_3], финансового директора. Он нахмурил брови и покачал головой. [jg:person_4], молодая стажерка, приехавшая из другого города, нервно теребила ручку.

"[jg:person_5], ваши цифры по продажам за границей неубедительны", - резко произнесла [jg:person_6]. - "Свяжитесь с нашим представителем в первой стране, его номер +7 916 123 45 67, он должен предоставить вам актуальную информацию. [jg:person_7], вы как считаете?" [jg:person_8], глава отдела продаж, только что вернувшийся из командировки, поддержал [jg:person_9]: "Боюсь, [jg:person_10], нам нужны более весомые аргументы, особенно по второй стране. Позвоните нашему партнеру, +7 927 987 65 43, он владеет ситуацией на месте." [jg:person_11] покраснел. [jg:person_12], менеджер по рекламе, пыталась спасти ситуацию: "Мы учтем ваши замечания, [jg:person_13]. [jg:person_14] уже разработал несколько новых стратегий, ориентированных на рынок третьей страны. Я уже связалась с коллегами, +7 965 456 78 90, они обещали поддержку".

Действия redact и deny

Допустим, у нас настроены действия redact для сущностей Личность и deny для сущностей Телефон, и мы хотим отправить на проверку файл TXT.

Запустим проверку и возможное маскирование файла TXT. Поскольку мы уже загрузили файл в хранилище, воспользуемся методом PUT /api/dataguard/public/user-masking/storage/mask.

Отправим запрос:
```
curl -X 'PUT' \
'http://<base_URL>/api/dataguard/public/user-masking/storage/mask?file-id=77ba4d3d-b6ab-42f9-b4f2-0688346fba5c' \
-H 'accept: application/json' \
-H 'X-DATA-GUARD-API-KEY: <API_key_redact_deny>'
```
В ответ нам придет идентификатор нашего файла:
```
{
  "fileId": "77ba4d3d-b6ab-42f9-b4f2-0688346fba5c"
}
```
Получим результат маскирования файла TXT. Для этого воспользуемся методом GET /api/dataguard/public/user-masking/files/result.

Отправим запрос:
```
curl -X 'GET' \
'http://<base_URL>/api/dataguard/public/user-masking/files/result?file-id=77ba4d3d-b6ab-42f9-b4f2-0688346fba5c' \
-H 'accept: application/json' \
-H 'X-DATA-GUARD-API-KEY: <API_key_redact_deny>'
```
В ответ получим результат маскирования:
```
{
    "status": "READY",
    "action": "deny",
    "detectedEntities": [
        "phone"
    ]
}
```
Несмотря на то, что в файле есть сущности Личность, к ним не было применено действие redact, так как для сущностей Телефон задано действие deny, которое имеет более высокий приоритет. Также в ответе нет идентификатора файла с маскированными сущностями, так как маскирование не было выполнено.

Документ Word

Действие redact

Допустим, у нас настроены действия redact для сущностей Личность, и мы хотим отправить на проверку файл DOCX.

Запустим проверку и возможное маскирование файла DOCX. Поскольку мы уже загрузили файл в хранилище, воспользуемся методом PUT /api/dataguard/public/user-masking/storage/mask.

Отправим запрос:
```
curl -X 'PUT' \
'http://<base_URL>/api/dataguard/public/user-masking/storage/mask?file-id=0cd6e84f-a1fb-4f04-8ebb-8cd3254beba3' \
-H 'accept: application/json' \
-H 'X-DATA-GUARD-API-KEY: <API_key_redact>'
```
В ответ нам придет идентификатор нашего файла:
```
{
  "fileId": "0cd6e84f-a1fb-4f04-8ebb-8cd3254beba3"
}
```
Получим результат маскирования файла DOCX. Для этого воспользуемся методом GET /api/dataguard/public/user-masking/files/result.

Отправим запрос:
```
curl -X 'GET' \
'http://<base_URL>/api/dataguard/public/user-masking/files/result?file-id=0cd6e84f-a1fb-4f04-8ebb-8cd3254beba3' \
-H 'accept: application/json' \
-H 'X-DATA-GUARD-API-KEY: <API_key_redact>'
```
В ответ получим результат маскирования:
```
{
    "status": "READY",
    "action": "redact",
    "detectedEntities": [
        "person"
    ]
}
```
В ответе нет идентификатора файла с маскированными сущностями, так как маскирование не было выполнено. В сложных форматах файлов, таких как DOCX, маскирование не поддерживается.

Действия redact и deny

Допустим, у нас настроены действия redact для сущностей Личность и deny для сущностей Телефон, и мы хотим отправить на проверку файл DOCX.

Запустим проверку и возможное маскирование файла DOCX. Поскольку мы уже загрузили файл в хранилище, воспользуемся методом PUT /api/dataguard/public/user-masking/storage/mask.

Отправим запрос:
```
curl -X 'PUT' \
'http://<base_URL>/api/dataguard/public/user-masking/storage/mask?file-id=320ca915-baa5-428e-86a2-ad0a9c046bd2' \
-H 'accept: application/json' \
-H 'X-DATA-GUARD-API-KEY: <API_key_redact_deny>'
```
В ответ нам придет идентификатор нашего файла:
```
{
  "fileId": "320ca915-baa5-428e-86a2-ad0a9c046bd2"
}
```
Получим результат маскирования файла DOCX. Для этого воспользуемся методом GET /api/dataguard/public/user-masking/files/result.

Отправим запрос:
```
curl -X 'GET' \
'http://<base_URL>/api/dataguard/public/user-masking/files/result?file-id=320ca915-baa5-428e-86a2-ad0a9c046bd2' \
-H 'accept: application/json' \
-H 'X-DATA-GUARD-API-KEY: <API_key_redact_deny>'
```
В ответ получим результат маскирования:
```
{
    "status": "READY",
    "action": "deny",
    "detectedEntities": [
        "phone"
    ]
}
```
Несмотря на то, что в файле есть сущности Личность с действием redact, оно не указано в ответе, так как для сущностей Телефон задано действие deny, которое имеет более высокий приоритет.

Методы​

Управление файлами в хранилище​

Маскирование сущностей в файлах​

Особенности обработки файлов​

Доступные форматы файлов​

Примеры​

Простой текстовый файл​

Действие redact​

Действия redact и deny​

Документ Word​

Действие redact​

Действия redact и deny​

Методы

Управление файлами в хранилище

Маскирование сущностей в файлах

Особенности обработки файлов

Доступные форматы файлов

Примеры

Простой текстовый файл

Действие redact

Действия redact и deny

Документ Word

Действие redact

Действия redact и deny