# Работа c файлами
# Отправка файла
Отправка файла осуществляется в три этапа:
Создание задачи на загрузку файла. Клиент инициирует создание загрузки и получает необходимые идентификаторы.
Передача файла в файловое хранилище сервера. Файл загружается на сервер с помощью HTTP-запроса (см. пример ниже).
Отправка сообщения с прикреплённым файлом. В чате создаётся сообщение, в котором указывается идентификатор ранее загруженного файла.
# Создание задачи на загрузку файла
Запрос:
{
"type": 1,
"id": 5,
"method": "uploadFile",
"payload": {
"fileSize": 1487
}
}
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| type | uint32 | Да | Тип сообщения (по умолчанию 1). Соответствует MESSAGE_TYPE.REQUEST |
| id | uint32 | Да | Уникальный идентификатор запроса. Инкрементируемое значение, назначаемое отправляющей стороной, обязательное в каждом запросе для последующего связывания с ответом. Подробнее читайте тут |
| method | string | Да | Команда uploadFile |
| fileSize | number | Да | Размер файла в байтах |
Ответ:
{
"type": 2,
"id": 5,
"payload": {
"uploadTaskId": "2e9537c4-e82c-467c-a149-3c1b41326def"
}
}
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| type | uint32 | Да | Тип сообщения (по умолчанию 2). Соответствует MESSAGE_TYPE.RESPONSE |
| id | uint32 | Да | Идентификатор, совпадающий с числом, отправленным в исходном запросе, используемый для связывания запроса и ответа |
| uploadTaskId | string | Да | Идентификатор задачи на загрузку файла |
В случае возникновения ошибки возвращается сообщение, содержащее параметр errorCode. Список возможных значений доступен в соответствующем разделе документации.
# Загрузка файла в файловое хранилище
Для загрузки файла в хранилище необходимо выполнить HTTP-запрос к серверу. Перечисленные ниже параметры указываются в HTTP-заголовках, а не передаются в URL (query string):
POST /bridge/api/client/v1/files HTTP/1.1
Upload-Task-Id: 2e9537c4-e82c-467c-a149-3c1b41326def
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryQeFqWQPxCmHvCIyc
Content-Length: 2081
------WebKitFormBoundaryQeFqWQPxCmHvCIyc
Content-Disposition: form-data; name="file"; filename="some_image.png"
Content-Type: image/png
<file binary data>
------WebKitFormBoundaryQeFqWQPxCmHvCIyc
Content-Disposition: form-data; name="preview"; filename="d970f81f-d433-401c-8182-d33c59b96cd5"
Content-Type: image/webp
<preview binary data>
------WebKitFormBoundaryQeFqWQPxCmHvCIyc
| Заголовок | Обяз. | Описание |
|---|---|---|
| Upload-Task-Id | Да | Идентификатор задачи на загрузку файла, полученный ранее из команды uploadFile |
Тело запроса должно быть представлено в виде объекта FormData с типом multipart/form-data и содержать обязательное поле file, содержащее сам файл.
Если у файла есть превью, то оно должно быть помещено в форму в поле preview, название под которым помещается превью должно отличаться от названия самого файла.
И файл и превью помещаются в бинарном виде.
Ответ:
В случае успешной загрузки, HTTP-сервер ответит кодом 200 OK:
HTTP/1.1 200 OK
Allow: OPTIONS, GET, HEAD, POST
Server: TrueConf Bridge
Content-Type: application/json
Content-Length: 57
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: height,mime,request_id,preview,cid
{
"temporalFileId": "2e9537c4-e82c-467c-a149-3c1b41326def"
}
В теле ответа содержится поле temporalFileId – временный идентификатор файла, готового для отправки в сообщении.
После отправки этот идентификатор теряет какие-либо полезные свойства.
Ошибка:
В случае ошибки, HTTP-сервер ответит кодом 400 Bad Request:
HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 62
{
"error": 310,
"error_description": "No upload task ID provided",
}
# Отправка файла в сообщении
Запрос:
{
"type": 1,
"id": 6,
"method": "sendFile",
"payload": {
"chatId": "bea15543d971a83c8ba1f103104791762c6b4b8f",
"content": {
"temporalFileId": "32506b12-6a1a-4cd3-be24-373c7bcf9510"
}
}
}
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| type | uint32 | Да | Тип сообщения (по умолчанию 1). Соответствует MESSAGE_TYPE.REQUEST |
| id | uint32 | Да | Уникальный идентификатор запроса. Инкрементируемое значение, назначаемое отправляющей стороной, обязательное в каждом запросе для последующего связывания с ответом. Подробнее читайте тут |
| method | string | Да | Команда sendFile |
| chatId | string | Да | Идентификатор чата для отправки сообщения |
| temporalFileId | string | Да | Временный идентификатор файла, полученный в ответе на HTTP-запрос |
Ответ:
{
"type": 2,
"id": 6,
"payload": {
"chatId": "bea15543d971a83c8ba1f103104791762c6b4b8f",
"timestamp": 1735134222098,
"messageId": "c8c3eee8-9ad0-4638-9692-ad16391a4256",
"fileId": "e09dbd63a16bd8cd7bddda7193c1c4ff0d2f6de5"
}
}
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| type | uint32 | Да | Тип сообщения (по умолчанию 2). Соответствует MESSAGE_TYPE.RESPONSE |
| id | uint32 | Да | Идентификатор, совпадающий с числом, отправленным в исходном запросе, используемый для связывания запроса и ответа |
| chatId | string | Да | Идентификатор чата |
| timestamp | number | Да | Временная метка отправки сообщения в формате UNIX timestamp с точностью до миллисекунд |
| messageId | string | Да | Идентификатор отправленного сообщения |
| fileId | string | Да | Постоянный идентификатор отправленного файла для получения информации о нем |
В случае возникновения ошибки возвращается сообщение, содержащее параметр errorCode. Список возможных значений доступен в соответствующем разделе документации.
# Получение информации о файле и его скачивание
Для получения расширенной информации о входящем файле в чате необходимо использовать значение payload.content.id, полученное из входящего запроса о новом сообщении.
Запрос:
{
"method": "getFileInfo",
"id": 9,
"type": 1,
"payload": {
"fileId": "e09dbd63a16bd8cd7bddda7193c1c4ff0d2f6de5"
}
}
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| type | uint32 | Да | Тип сообщения (по умолчанию 1). Соответствует MESSAGE_TYPE.REQUEST |
| id | uint32 | Да | Уникальный идентификатор запроса. Инкрементируемое значение, назначаемое отправляющей стороной, обязательное в каждом запросе для последующего связывания с ответом. Подробнее читайте тут |
| method | string | Да | Команда getFileInfo |
| fileId | string | Да | Идентификатор файла из входящего запроса о новом сообщении |
Ответ:
{
"type": 2,
"id": 9,
"payload": {
"name": "AirHelp_Logo.webp",
"size": 3446,
"mimeType": "image/webp",
"downloadUrl": "https://10.111.15.116/bridge/api/client/v1/files?file_id=e09dbd63a16bd8cd7bddda7193c1c4ff0d2f6de5",
"readyState": 2,
"previews": [
{
"name": "preview-2278f47b821f72e4a44ab6b980180518.webp",
"mimeType": "image/webp",
"size": 1264,
"downloadUrl": "https://10.111.15.116/bridge/api/client/v1/files/preview?file_id=e09dbd63a16bd8cd7bddda7193c1c4ff0d2f6de5"
}
],
"infoHash": "e09dbd63a16bd8cd7bddda7193c1c4ff0d2f6de5"
}
}
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| type | uint32 | Да | Тип сообщения (по умолчанию 2). Соответствует MESSAGE_TYPE.RESPONSE |
| id | uint32 | Да | Идентификатор, совпадающий с числом, отправленным в исходном запросе, используемый для связывания запроса и ответа |
| name | string | Да | Имя файла |
| size | number | Да | Размер файла в байтах |
| mimeType | string | Да | MIME-тип файла |
| downloadUrl | string | Да | URL для скачивания файла |
| readyState | FileReadyStateEnum | Да | Состояние файла на сервере |
| infoHash | string | Да | Идентификатор файла на сервере |
| previews | Array | Да | Массив превью файла, повторяющий вышеописанные параметры |
Для скачивания файла или его превью необходимо отправить HTTP GET-запрос на адрес, указанный в downloadUrl.
В случае возникновения ошибки возвращается сообщение, содержащее параметр errorCode. Список возможных значений доступен в соответствующем разделе документации.
# Подписка на прогресс загрузки файла на сервер
Если файл находится в состоянии UPLOADING, то можно подписаться на процесс загрузки, чтобы узнать, когда файл станет доступен.
Запрос:
{
"method": "subscribeFileProgress",
"id": 10,
"type": 1,
"payload": {
"fileId": "e09dbd63a16bd8cd7bddda7193c1c4ff0d2f6de5"
}
}
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| type | uint32 | Да |
Тип сообщения (по умолчанию 1). Соответствует
MESSAGE_TYPE.REQUEST |
| id | uint32 | Да | Уникальный идентификатор запроса. Инкрементируемое значение, назначаемое отправляющей стороной, обязательное в каждом запросе для последующего связывания с ответом. Подробнее читайте тут |
| method | string | Да | Команда subscribeFileProgress |
| fileId | string | Да | Идентификатор файла на сервере |
Ответ:
{
"id": 10,
"type": 2,
"payload": {
"result": true
}
}
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| type | uint32 | Да |
Тип сообщения (по умолчанию 2). Соответствует
MESSAGE_TYPE.RESPONSE |
| id | uint32 | Да | Идентификатор, совпадающий с числом, отправленным в исходном запросе, используемый для связывания запроса и ответа |
| result | boolean | Да | Получилось ли подписаться на загрузку |
В случае возникновения ошибки возвращается сообщение, содержащее параметр errorCode. Список возможных значений доступен в соответствующем разделе документации.
# Получение событий загрузки файла
После подписки на загрузку по веб-сокету начнут приходить события uploadingProgress:
{
"id": 3,
"type": 1,
"method": "uploadingProgress",
"payload": {
"fileId": "e09dbd63a16bd8cd7bddda7193c1c4ff0d2f6de5",
"progress": 123
}
}
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| type | uint32 | Да |
Тип сообщения (по умолчанию 1). Соответствует
MESSAGE_TYPE.REQUEST от сервера
|
| id | uint32 | Да | Идентификатор, совпадающий с числом, отправленным в исходном запросе, используемый для связывания запроса и ответа |
| fileId | string | Да | Идентификатор файла на сервере |
| progress | number | Да | Количество байт, загруженных на сервер |
Когда придёт сообщение, в котором значение progress будет равно значению поля size из ответа getFileInfo, файл считается полностью загруженным и может быть получен с помощью GET-запроса. После этого события с обновлённым progress больше не поступают. Если файл уже был загружен ранее, будет отправлено только одно финальное событие, эквивалентное последнему.
# Отписка от получения события загрузки
При необходимости можно отписаться от получения событий загрузки файла на сервер.
Запрос:
{
"method": "unsubscribeFileProgress",
"id": 10,
"type": 1,
"payload": {
"fileId": "e09dbd63a16bd8cd7bddda7193c1c4ff0d2f6de5"
}
}
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| type | uint32 | Да |
Тип сообщения (по умолчанию 1). Соответствует
MESSAGE_TYPE.REQUEST |
| id | uint32 | Да | Уникальный идентификатор запроса. Инкрементируемое значение, назначаемое отправляющей стороной, обязательное в каждом запросе для последующего связывания с ответом. Подробнее читайте тут |
| method | string | Да | Команда unsubscribeFileProgress |
| fileId | string | Да | Идентификатор файла на сервере |
Ответ:
{
"id": 10,
"type": 2,
"payload": {
"result": true
}
}
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
| type | uint32 | Да |
Тип сообщения (по умолчанию 2). Соответствует
MESSAGE_TYPE.RESPONSE |
| id | uint32 | Да | Идентификатор, совпадающий с числом, отправленным в исходном запросе, используемый для связывания запроса и ответа |
| result | boolean | Да | Получилось ли отписаться от получения событий о загрузке файла |
В случае возникновения ошибки возвращается сообщение, содержащее параметр errorCode. Список возможных значений доступен в соответствующем разделе документации.