Установка и использование платформы
REST API: обмен конфиденциальными данными и получение информации о группах доступа¶
Для работы с конфиденциальными данными при помощи REST API предназначен набор методов группы Privacy.
Подробнее об обмене конфиденциальными данными и группах доступа см. статью Обмен конфиденциальными данными.
Важно
Методы группы Privacy недоступны при использовании PKI, то есть когда в конфигурационном файле ноды параметру node.crypto.pki.mode присвоено значение ON. В тестовом режиме PKI (node.crypto.pki.mode = TEST) или при отключенном PKI (node.crypto.pki.mode = OFF) методы можно использовать.
Примечание
Для работы с конфиденциальными данными также можно использовать gRPC методы сервисов PrivacyEventsService и PrivacyPublicService.
Авторизация методов группы Privacy¶
POST /privacy/sendData¶
Метод предназначен для отправки в блокчейн конфиденциальных данных, доступных только для участников группы доступа, определенной для этих данных.
Примечание
Для отправки данных размером более 20 МБ используйте метод POST /privacy/sendLargeData.
Важно
Метод /privacy/sendData недоступен при использовании PKI, то есть когда в конфигурационном файле ноды параметру node.crypto.pki.mode присвоено значение ON. В тестовом режиме PKI (node.crypto.pki.mode = TEST) или при отключенном PKI (node.crypto.pki.mode = OFF) метод можно использовать.
Запрос метода POST /privacy/sendData должен содержать следующую информацию:
sender– блокчейн-адрес, от которого должны рассылаться данные (соответствуют значению параметраprivacy.owner-addressв конфигурационном файле ноды);policyId– идентификатор группы, которая будет иметь доступ к отправляемым данным;type– тип передаваемых данных, напримерfile;data– конфиденциальные данные в виде строки в формате base64;hash– sha256-хэш данных в формате base58;info– информация об отправляемых конфиденциальных данных:filename– имя файла данных,size– размер файла данных,timestamp– временная метка,author– электронный адрес автора отправляемых данных,comment– произвольный комментарий.
fee– комиссия за транзакцию PolicyDataHash;password– пароль для доступа к закрытому ключу keystore ноды – необязательный параметр;timestamp– параметр не используется – необязательный параметр;atomicBadge– информация, необходимая для отправки атомарной транзакции – необязательный параметр:trustedSender– доверенный адрес отправителя транзакции для добавления в контейнер атомарной транзакции.
certificates– цепочка сертификатов байтами в формате DER; параметр является обязательным при одновременном соблюдении следующих условий:используется тестовый режим PKI (то есть в конфигурационном файле ноды параметру node.crypto.pki.mode присвоено значение
TEST),новый пользователь, который не является владельцем ноды (node-owner), делает свою первую транзакцию.
В этом случае необходимо в запросе в поле
certificatesпередать цепочку сертификатов пользователя; в других случаях полеcertificatesявляется необязательным.
Примечание
При отправке файлов через Amazon S3/Minio в полях comment, author, filename должны быть ascii символы. Это ограничение Java SDK AWS.
В результате отправки запроса будет сформирована транзакция 114 PolicyDataHash, которая отправит хэш конфиденциальных данных в блокчейн.
Параметр broadcast¶
Помимо параметров, которые передаются в теле запроса, методу POST /privacy/sendData может быть передан query-параметр broadcast. Он может принимать следующие значения:
true– в этом случае созданная транзакция PolicyDataHash отправляется в блокчейн;false– транзакция PolicyDataHash и сообщение о наличии данных (Privacy Inventory) не отправляется в блокчейн.
Для снижения вероятности ошибок доставки данных рекомендуется установить для параметра broadcast значение false, если после отправки данных с помощью API метода sendData отправляется атомарная транзакция, которая содержит транзакцию CreatePolicy и транзакцию PolicyDataHash.
Важно
Если в поле broadcast передано значение false, то последующая отправка в блокчейн (бродкаст) полученной транзакции должна выполняться через ту же ноду, на которую был отправлен запрос sendData. Как следствие, это ограничивает применение непустого atomicBadge для PolicyDataHash Transaction.
Примеры запроса и ответа:
Примечание
Для отправки в блокчейн конфиденциальных данных также можно использовать gRPC метод SendData.
POST /privacy/sendDataV2¶
Метод POST /privacy/sendDataV2 аналогичен методу POST /privacy/sendData, однако позволяет приложить файл в окне Swagger, не прибегая к его конверсии в формат base64. Метод предоставляет возможность потоковой передачи данных.
Поле Data в этой версии метода отсутствует.
Примечание
Для отправки данных размером более 20 МБ используйте метод POST /privacy/sendLargeData.
Примечание
При отправке файлов через Amazon S3/Minio в полях comment, author, filename должны быть ascii символы. Это ограничение Java SDK AWS.
Важно
Метод /privacy/sendDataV2 недоступен при использовании PKI, то есть когда в конфигурационном файле ноды параметру node.crypto.pki.mode присвоено значение ON. В тестовом режиме PKI (node.crypto.pki.mode = TEST) или при отключенном PKI (node.crypto.pki.mode = OFF) метод можно использовать.
Примечание
В тестовом режиме PKI (параметру node.crypto.pki.mode присвоено значение TEST) когда новый пользователь, который не является владельцем ноды (node-owner), делает свою первую транзакцию, ему необходимо в запросе приложить цепочку своих сертификатов. Для этого предназначено поле certificates. В других случаях поле certificates является необязательным.
Примеры запроса и ответа:
Примечание
Для отправки в блокчейн потока конфиденциальных данных также можно использовать gRPC метод SendLargeData.
POST /privacy/sendLargeData¶
Метод POST /privacy/sendLargeData аналогичен методу POST /privacy/sendDataV2, но используется для отправки данных размером не менее 20 МБ.
Примечание
Для отправки данных размером менее 20 МБ используйте методы POST /privacy/sendData и POST /privacy/sendDataV2.
В конфигурационном файле ноды в секции node.privacy.service можно настроить обратное давление на входящие фрагменты данных: задать максимальный размер для буфера в памяти (по умолчанию – 100 МБ).
Примечание
При отправке файлов через Amazon S3/Minio в полях comment, author, filename должны быть ascii символы. Это ограничение Java SDK AWS.
Важно
Метод /privacy/sendLargeData недоступен при использовании PKI, то есть когда в конфигурационном файле ноды параметру node.crypto.pki.mode присвоено значение ON. В тестовом режиме PKI (node.crypto.pki.mode = TEST) или при отключенном PKI (node.crypto.pki.mode = OFF) метод можно использовать.
Примечание
В тестовом режиме PKI (параметру node.crypto.pki.mode присвоено значение TEST) когда новый пользователь, который не является владельцем ноды (node-owner), делает свою первую транзакцию, ему необходимо в запросе приложить цепочку своих сертификатов. Для этого предназначено поле certificates. В других случаях поле certificates является необязательным.
Примеры запроса и ответа:
Примечание
Для отправки в блокчейн потока конфиденциальных данных также можно использовать gRPC метод SendLargeData.
GET /privacy/{policy-id}/recipients¶
Метод предназначен для получения адресов всех участников, записанных в группу {policy-id}.
В ответе метода возвращается массив строк с адресами участников группы доступа.
Пример ответа:
Важно
Метод GET /privacy/{policy-id}/recipients недоступен при использовании PKI, то есть когда в конфигурационном файле ноды параметру node.crypto.pki.mode присвоено значение ON. В тестовом режиме PKI (node.crypto.pki.mode = TEST) или при отключенном PKI (node.crypto.pki.mode = OFF) метод можно использовать.
Примечание
Для получения адресов всех участников группы доступа к конфиденциальным данным также можно использовать gRPC метод Recipients.
GET /privacy/{policy-id}/owners¶
Метод предназначен для получения адресов владельцев группы доступа {policy-id}.
В ответе метода возвращается массив строк с адресами владельцев группы доступа.
Пример ответа:
Важно
Метод GET /privacy/{policy-id}/owners недоступен при использовании PKI, то есть когда в конфигурационном файле ноды параметру node.crypto.pki.mode присвоено значение ON. В тестовом режиме PKI (node.crypto.pki.mode = TEST) или при отключенном PKI (node.crypto.pki.mode = OFF) метод можно использовать.
Примечание
Для получения адресов владельцев группы доступа к конфиденциальным данным также можно использовать gRPC метод Owners.
GET /privacy/{policy-id}/hashes¶
Метод предназначен для получения массива идентификационных хэшей данных, которые привязаны к группе доступа {policy-id}.
В ответе метода возвращается массив строк с идентификационными хэшами данных группы доступа.
Пример ответа:
Важно
Метод GET /privacy/{policy-id}/hashes недоступен при использовании PKI, то есть когда в конфигурационном файле ноды параметру node.crypto.pki.mode присвоено значение ON. В тестовом режиме PKI (node.crypto.pki.mode = TEST) или при отключенном PKI (node.crypto.pki.mode = OFF) метод можно использовать.
Примечание
Для получения пакета конфиденциальных данных группы доступа по идентификационному хэшу можно использовать gRPC метод GetPolicyItemData.
GET /privacy/{policyId}/getData/{policyItemHash}¶
Метод предназначен для получения пакета конфиденциальных данных группы доступа {policyId} по идентификационному хэшу {policyItemHash}.
В ответе метода возвращается хэш-сумма конфиденциальных данных.
Пример ответа:
Важно
Метод GET /privacy/{policyId}/getData/{policyItemHash} недоступен при использовании PKI, то есть когда в конфигурационном файле ноды параметру node.crypto.pki.mode присвоено значение ON. В тестовом режиме PKI (node.crypto.pki.mode = TEST) или при отключенном PKI (node.crypto.pki.mode = OFF) метод можно использовать.
GET /privacy/{policyId}/getLargeData/{policyItemHash}¶
Метод предназначен для получения пакета конфиденциальных данных группы доступа {policyId} по идентификационному хэшу {policyItemHash}.
Метод возвращает стрим, что позволяет пользователю скачать файл с данными неограниченного объёма.
Важно
Метод GET /privacy/{policyId}/getLargeData/{policyItemHash} недоступен при использовании PKI, то есть когда в конфигурационном файле ноды параметру node.crypto.pki.mode присвоено значение ON. В тестовом режиме PKI (node.crypto.pki.mode = TEST) или при отключенном PKI (node.crypto.pki.mode = OFF) метод можно использовать.
GET /privacy/%policyId%/transactions¶
Метод предназначен для получения транзакций группы доступа {policyId}.
Метод возвращает список идентификаторов транзакций типа 114 PolicyDataHash, содержащихся в указанной в запросе группе доступа.
GET /privacy/{policyId}/getInfo/{policyItemHash}¶
Метод предназначен для получения метаданных для пакета конфиденциальных данных группы {policyId} по идентификационному хэшу {policyItemHash}.
В ответе метода возвращаются следующие данные:
sender– адрес отправителя конфиденциальных данных;policy_id– идентификатор группы доступа;type– тип конфиденциальных данных (file);info– массив данных о файле:filename– имя файла;size– размер файла;timestamp– временная метка размещения файла в формате Unix Timestamp (в миллисекундах);author– автор файла;comment– опциональный комментарий к файлу;
hash– идентификационный хэш конфиденциальных данных.
Пример ответа:
Важно
Метод GET /privacy/{policyId}/getInfo/{policyItemHash} недоступен при использовании PKI, то есть когда в конфигурационном файле ноды параметру node.crypto.pki.mode присвоено значение ON. В тестовом режиме PKI (node.crypto.pki.mode = TEST) или при отключенном PKI (node.crypto.pki.mode = OFF) метод можно использовать.
POST /privacy/forceSync¶
Метод предназначен для принудительного получения пакета конфиденциальных данных. Применяется в случае, если транзакция с конфиденциальными данными для группы доступа присутствует в блокчейне, но по какой-либо причине эти данные не были записаны в хранилище конфиденциальных данных ноды. В этом случае метод позволяет принудительно скачать отсутствующие данные. Метод синхронизирует данные по всем группам доступа к конфиденциальным данным.
Запрос метода содержит следующие данные:
sender– адрес ноды-участника группы доступа, отправляющей запрос;policy– идентификатор группы доступа;source– адрес ноды, с которой должны скачиваться отсутствующие данные. В случае, если нода неизвестна, установите параметр наnullили оставьте поле пустым: в этом случае скачивание файла будет произведено из хранилища первой ноды из списка группы доступа.
Ответ метода содержит поле result с результатом получения данных и поле message с текстом возможной ошибки.
В случае успешного получения возвращается значение success, конфиденциальные данные записываются в хранилище ноды.
В случае возникновения ошибки возвращается значение error, в поле message приводится описание ошибки.
Примеры запроса и ответа:
Важно
Метод POST /privacy/forceSync недоступен при использовании PKI, то есть когда в конфигурационном файле ноды параметру node.crypto.pki.mode присвоено значение ON. В тестовом режиме PKI (node.crypto.pki.mode = TEST) или при отключенном PKI (node.crypto.pki.mode = OFF) метод можно использовать.
Примечание
Для синхронизации данных по указанной группе доступа к конфиденциальным данным также можно использовать gRPC метод forceSync.
GET /privacy/forceSync/{policyId}¶
Метод аналогичен методу POST /privacy/forceSync с той разницей, что синхронизирует данные по указанной группе доступа к конфиденциальным данным (policyId).
Важно
Метод GET /privacy/forceSync/{policyId} недоступен при использовании PKI, то есть когда в конфигурационном файле ноды параметру node.crypto.pki.mode присвоено значение ON. В тестовом режиме PKI (node.crypto.pki.mode = TEST) или при отключенном PKI (node.crypto.pki.mode = OFF) метод можно использовать.
Примечание
Для синхронизации данных по указанной группе доступа к конфиденциальным данным также можно использовать gRPC метод forceSync.
POST /privacy/getInfos¶
Метод предназначен для получения массива метаданных конфиденциальных данных по идентификатору группы доступа и идентификационному хэшу.
Запрос метода содержит следующие данные:
policiesDataHashes– массив данных с двумя элементами для каждой отдельной группы доступа:policyId– идентификатор группы доступа,datahashes– массив хэшей конфиденциальных данных для получения метаданных по каждому из них.
В ответе метода для каждого отдельного хэша конфиденциальных данных возвращается массив данных, аналогичный ответу метода GET /privacy/{policyId}/getInfo/{policyItemHash}.
Примеры запроса и ответа:
Важно
Метод POST /privacy/getInfos недоступен при использовании PKI, то есть когда в конфигурационном файле ноды параметру node.crypto.pki.mode присвоено значение ON. В тестовом режиме PKI (node.crypto.pki.mode = TEST) или при отключенном PKI (node.crypto.pki.mode = OFF) метод можно использовать.