Установка и использование платформы

gRPC: работа с конфиденциальными данными

Для работы с конфиденциальными данными (privacy) предусмотрены gRPC сервисы PrivacyEventsService и PrivacyPublicService.

:opticon:`report, size=24` Авторизация методов PrivacyEventsService и PrivacyPublicService:

Для использования методов gRPC API сервисов PrivacyEventsService и PrivacyPublicService требуется авторизация по api-key или JWT-токену. Авторизация методов реализована следующим образом:

  • в случае api-key авторизации требуется PrivacyApiKey;

  • в случае OAuth2 авторизации требуется наличие роли Privacy в JWT токене.

Для каждого из методов необходимо передавать следующие данные:

  • Recipients — userAuth;

  • Owners — userAuth;

  • Hashes — userAuth;

  • GetPolicyItemData — privacyAuth;

  • GetPolicyItemInfo — privacyAuth;

  • SendData — privacyAuth;

  • SendLargeData — privacyAuth,

  • forceSync — privacyAuth.

где

  • userAuth — api-key пользователя, передаваемый в заголовке „X-Api-Key“ к запросу ИЛИ передача JWT токена с ролью user в заголовке „Authorization“;

  • privacyAuth — api-key privacy пользователя в заголовке „X-Api-Key“ к запросу ИЛИ передача JWT токена с ролью privacy в заголовке „Authorization“.

PrivacyEventsService

У сервиса PrivacyEventsService есть один метод SubscribeOn, описанный в protobuf-файле privacy_events_service.proto. Используйте этот метод для получения потока (стрима) событий по получению или удалению конфиденциальных данных, которые поступают в gRPC-интерфейс ноды. Для этого отправьте запрос SubscribeOn (SubscribeOnRequest), который инициализирует подписку на стрим.

Информация о получении или удалении конфиденциальных данных

После успешной отправки запроса на gRPC-интерфейс будут приходить следующие данные:

  • policy_id – идентификатор группы доступа к конфиденциальным данным;

  • data_hash – идентификационный хэш конфиденциальных данных;

  • event_type – тип события; доступны следующие типы:

    • DATA_ACQUIRED – данные сохранены в БД;

    • DATA_INVALIDATED – данные помечены на удаление в связи с отсутствием активности по ним или при роллбэке (откате).

PrivacyPublicService

У сервиса PrivacyPublicService есть следующие методы, описанные в protobuf-файле privacy_public_service.proto:

Важно

Типы данных полей для запросов и ответов указаны в protobuf-файле.

Получение хэш-суммы конфиденциальных данных

Используйте метод GetPolicyItemData для получения пакета конфиденциальных данных группы доступа по идентификационному хэшу. Метод требует ввода параметров запроса policy_id (идентификатор группы доступа) и data_hash (идентификационный хэш). После успешной отправки запроса на gRPC-интерфейс возвращается хэш-сумма конфиденциальных данных.

Скачивание из ноды больших данных

Используйте метод GetDataLarge для скачивания из ноды больших данных, которые были отправлены с помощью метода SendLargeData. Метод требует ввода параметров запроса policy_id (идентификатор группы доступа) и data_hash (идентификационный хэш). После успешной отправки запроса на gRPC-интерфейс возвращается поток PolicyItemDataResponse с данными.

Получение метаданных для пакета конфиденциальных данных

Используйте метод GetPolicyItemInfo для получения метаданных для пакета конфиденциальных данных группы по идентификационному хэшу. Метод требует ввода параметров запроса policy_id (идентификатор группы доступа) и data_hash (идентификационный хэш). После успешной отправки запроса на gRPC-интерфейс возвращаются следующие данные:

  • sender – адрес отправителя конфиденциальных данных;

  • policy_id – идентификатор группы доступа;

  • type – тип конфиденциальных данных (file);

  • info – массив данных о файле:

    • filename – имя файла;

    • size – размер файла;

    • timestamp – временная метка размещения файла в формате Unix Timestamp (в миллисекундах);

    • author – автор файла;

    • comment – опциональный комментарий к файлу;

  • hash – идентификационный хэш конфиденциальных данных.

Проверка существования пакета конфиденциальных данных

Используйте метод PolicyItemDataExists для получения информации о наличии пакета конфиденциальных данных группы доступа по идентификационному хэшу. Метод требует ввода параметров запроса policy_id (идентификатор группы доступа) и data_hash (идентификационный хэш). После успешной отправки запроса на gRPC-интерфейс возвращается true, если данные в наличии, или false, если данные отсутствуют.

Отправка в блокчейн конфиденциальных данных

Используйте метод SendData для отправки в блокчейн конфиденциальных данных, доступных только для участников группы доступа, определенной для этих данных.

Примечание

Для отправки данных размером более 20 МБ используйте метод SendLargeData.

Примечание

Для отправки в блокчейн потока конфиденциальных данных используйте метод SendLargeData.

Метод требует ввода следующих параметров запроса:

  • sender_address – блокчейн-адрес, от которого должны рассылаться данные (соответствуют значению параметра privacy.owner-address в конфигурационном файле ноды);

  • policy_id – идентификатор группы доступа к конфиденциальным данным, которая будет иметь доступ к отправляемым данным;

  • data_hash – идентификационный sha256-хэш конфиденциальных данных в формате base58;

  • info – информация об отправляемых данных;

  • fee – комиссия за транзакции;

  • fee_asset_id – поле опционально и используется только для смарт-контрактов с поддержкой gRPC;

  • atomic_badge – поле-метка, указывающая, что транзакция поддерживается атомарной транзакцией;

  • password – пароль для доступа к закрытому ключу keystore ноды;

  • broadcast_tx – если передается значение true, то созданная PolicyDataHash транзакция отправляется в блокчейн, если false, то транзакция и сообщение о наличии данных (Privacy Inventory) не отправляется; подробнее см. ниже;

  • data – строка, содержащая данные в формате base64.

После успешной отправки запроса на gRPC-интерфейс будут приходить следующие данные:

  • tx_version – версия транзакции;

  • tx – созданная PolicyDataHash транзакция.

Параметр broadcast_tx

Для снижения вероятности ошибок доставки данных рекомендуется установить для параметра broadcast_tx значение false, если после отправки данных с помощью API метода SendData отправляется атомарная транзакция, которая содержит транзакцию CreatePolicy и транзакцию PolicyDataHash.

Отправка в блокчейн потока конфиденциальных данных

Используйте метод SendLargeData для отправки в блокчейн потока конфиденциальных данных. Данные будут доступны только для участников группы доступа, определенной для этих данных.

Примечание

Для отправки данных размером менее 20 МБ используйте метод SendData.

Метод принимает в запросе поток данных в следующем формате:

  • metadata – метаданные для пакета конфиденциальных данных, аналогичные входным данным метода SendData;

  • content – массив байт, представляющих собой пакет конфиденциальных данных.

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

Получение адресов всех участников группы доступа к конфиденциальным данным

Используйте метод Recipients для получения адресов всех участников группы доступа к конфиденциальным данным. Метод требует ввода параметра запроса policy_id – идентификатор группы доступа. В ответе метод возвращает массив строк с адресами участников группы доступа.

Получение адресов владельцев группы доступа к конфиденциальным данным

Используйте метод Owners для получения адресов владельцев группы доступа к конфиденциальным данным. Метод требует ввода параметра запроса policy_id (идентификатор группы доступа). В ответе метод возвращает массив строк с адресами владельцев группы доступа.

Получение массива идентификационных хэшей данных

Используйте метод Hashes для получения массива идентификационных хэшей данных, которые привязаны к группе доступа к конфиденциальным данным. Метод требует ввода параметра запроса policy_id (идентификатор группы доступа). В ответе метод возвращает массив строк с идентификационными хэшами данных группы доступа.

Синхронизация данных по указанной группе доступа к конфиденциальным данным

Используйте метод forceSync для синхронизации данных по указанной группе доступа к конфиденциальным данным. Метод требует ввода параметра запроса policy_id (идентификатор группы доступа).

В результате выполнения метода нода запускает процесс синхронизации и возвращает размер конфиденциальных данных в Мб. Если синхронизацию не удалось запустить, нода возвращает и описание ошибки.

Смотрите также