Установка и использование платформы
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
) метод можно использовать.