Установка и использование платформы
gRPC: работа с конфиденциальными данными¶
Для работы с конфиденциальными данными (privacy) предусмотрены gRPC сервисы PrivacyEventsService и PrivacyPublicService.
Важно
Методы для работы с конфиденциальными данными недоступны при использовании PKI, то есть когда в конфигурационном файле ноды параметру node.crypto.pki.mode присвоено значение ON
. В тестовом режиме PKI (node.crypto.pki.mode = TEST
) или при отключенном PKI (node.crypto.pki.mode = OFF
) методы можно использовать.
Примечание
Для работы с конфиденциальными данными также можно использовать REST методы группы Privacy.
Авторизация методов PrivacyEventsService и PrivacyPublicService¶
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-файле.
Примечание
Для работы с конфиденциальными данными также можно использовать REST методы группы Privacy.
Получение хэш-суммы конфиденциальных данных¶
Используйте метод GetPolicyItemData для получения пакета конфиденциальных данных группы доступа по идентификационному хэшу. Метод требует ввода параметров запроса policy_id
(идентификатор группы доступа) и data_hash
(идентификационный хэш). После успешной отправки запроса на gRPC-интерфейс возвращается хэш-сумма конфиденциальных данных.
Примечание
Для получения массива идентификационных хэшей данных, которые привязаны к группе доступа {policy-id}
, можно использовать REST метод GET /privacy/{policy-id}/hashes.
Скачивание из ноды больших данных¶
Используйте метод 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.
Важно
Метод SendData недоступен при использовании PKI, то есть когда в конфигурационном файле ноды параметру node.crypto.pki.mode присвоено значение ON
. Метод можно использовать в тестовом режиме PKI (node.crypto.pki.mode = TEST
) или при отключенном PKI (node.crypto.pki.mode = OFF
).
Метод требует ввода следующих параметров запроса:
sender_address
– блокчейн-адрес, от которого должны рассылаться данные (соответствуют значению параметраprivacy.owner-address
в конфигурационном файле ноды);policy_id
– идентификатор группы доступа к конфиденциальным данным, которая будет иметь доступ к отправляемым данным;data_hash
– идентификационный sha256-хэш конфиденциальных данных в формате base58;info
– информация об отправляемых данных:filename
– имя файла данных,size
– размер файла данных,timestamp
– временная метка,author
– электронный адрес автора отправляемых данных,comment
– произвольный комментарий.
fee
– комиссия за транзакции;fee_asset_id
– поле опционально и используется только для смарт-контрактов;atomic_badge
– поле-метка, указывающая, что транзакция поддерживается атомарной транзакцией;password
– пароль для доступа к закрытому ключу keystore ноды;broadcast_tx
– если передается значениеtrue
, то созданная транзакция PolicyDataHash отправляется в блокчейн; еслиfalse
, то транзакция и сообщение о наличии данных (Privacy Inventory) не отправляется; подробнее см. ниже;data
– строка, содержащая данные в формате base64.
certificates
– цепочка сертификатов байтами в формате DER; параметр является обязательным при одновременном соблюдении следующих условий:используется тестовый режим PKI (то есть в конфигурационном файле ноды параметру node.crypto.pki.mode присвоено значение
TEST
),новый пользователь, который не является владельцем ноды (node-owner), делает свою первую транзакцию.
В этом случае необходимо в запросе в поле
certificates
передать цепочку сертификатов пользователя; в других случаях полеcertificates
является необязательным.
Примечание
При отправке файлов через Amazon S3/Minio в полях comment
, author
, filename
должны быть ascii символы. Это ограничение Java SDK AWS.
После успешной отправки запроса на gRPC-интерфейс будут приходить следующие данные:
tx_version
– версия транзакции;tx
– созданная PolicyDataHash транзакция.
Параметр broadcast_tx
¶
Для снижения вероятности ошибок доставки данных рекомендуется установить для параметра broadcast_tx
значение false
, если после отправки данных с помощью API метода SendData отправляется атомарная транзакция, которая содержит транзакцию CreatePolicy и транзакцию PolicyDataHash.
Важно
Если в поле broadcast_tx
передано значение false
, то последующая отправка в блокчейн (бродкаст) полученной транзакции должна выполняться через ту же ноду, на которую был отправлен запрос sendData. Как следствие, это ограничивает применение непустого atomicBadge
для транзакции PolicyDataHash.
Примечание
Для отправки в блокчейн конфиденциальных данных также можно использовать REST метод POST /privacy/sendData.
Отправка в блокчейн потока конфиденциальных данных¶
Используйте метод SendLargeData для отправки в блокчейн потока конфиденциальных данных. Данные будут доступны только для участников группы доступа, определенной для этих данных.
Примечание
Для отправки данных размером менее 20 МБ используйте метод SendData.
Важно
Метод SendLargeData недоступен при использовании PKI, то есть когда в конфигурационном файле ноды параметру node.crypto.pki.mode присвоено значение ON
. Метод можно использовать в тестовом режиме PKI (node.crypto.pki.mode = TEST
) или при отключенном PKI (node.crypto.pki.mode = OFF
).
Метод принимает в запросе поток данных в следующем формате:
metadata
– метаданные для пакета конфиденциальных данных, аналогичные входным данным метода SendData;content
– массив байт, представляющих собой пакет конфиденциальных данных.
После успешной отправки запроса на gRPC-интерфейс будут приходить те же данные, что и для метода SendData.
Примечание
Для отправки в блокчейн потока конфиденциальных данных или данных размером более 20 МБ также можно использовать REST методы POST /privacy/sendDataV2 и POST /privacy/sendLargeData.
Получение адресов всех участников группы доступа к конфиденциальным данным¶
Используйте метод Recipients для получения адресов всех участников группы доступа к конфиденциальным данным. Метод требует ввода параметра запроса policy_id
– идентификатор группы доступа.
В ответе метод возвращает массив строк с адресами участников группы доступа.
Примечание
Для получения адресов всех участников группы доступа к конфиденциальным данным также можно использовать REST метод GET /privacy/{policy-id}/recipients.
Получение адресов владельцев группы доступа к конфиденциальным данным¶
Используйте метод Owners для получения адресов владельцев группы доступа к конфиденциальным данным. Метод требует ввода параметра запроса policy_id
(идентификатор группы доступа).
В ответе метод возвращает массив строк с адресами владельцев группы доступа.
Примечание
Для получения адресов владельцев группы доступа к конфиденциальным данным также можно использовать REST метод GET /privacy/{policy-id}/owners.
Получение массива идентификационных хэшей данных¶
Используйте метод Hashes для получения массива идентификационных хэшей данных, которые привязаны к группе доступа к конфиденциальным данным. Метод требует ввода параметра запроса policy_id
(идентификатор группы доступа).
В ответе метод возвращает массив строк с идентификационными хэшами данных группы доступа.
Синхронизация данных по указанной группе доступа к конфиденциальным данным¶
Используйте метод forceSync для синхронизации данных по указанной группе доступа к конфиденциальным данным. Метод требует ввода параметра запроса policy_id
(идентификатор группы доступа).
В результате выполнения метода нода запускает процесс синхронизации и возвращает размер конфиденциальных данных в Мб. Если синхронизацию не удалось запустить, нода возвращает и описание ошибки.
Примечание
Для принудительного получения пакета конфиденциальных данных также можно использовать REST методы POST /privacy/forceSync и GET /privacy/forceSync/{policyId}.