WebSocket API

WebSocket API используется для реального времени совместной работы. Когда пользователь вносит изменения, например, создает новое приложение базы данных, то бэкенд транслирует сообщение, содержащее это приложение, всем пользователям в связанном рабочем пространстве, которые подключены к WebSocket. Веб-фронтенд использует WebSocket для обновления уже загруженных данных в реальном времени, когда они изменяются. Это обеспечивает, что пользователь всегда работает с самыми актуальными данными без перезагрузки страницы.

Подключение

Чтобы подключиться к WebSocket, сначала нужно аутентифицироваться через REST API и получить JSON Web Token. После этого вы можете подключиться к следующему URL, предоставив ваш JWT в качестве параметра запроса: wss://api.baserow.io/ws/core/?jwt_token=YOUR_JWT_TOKEN. Если вы размещаете систему самостоятельно, вам нужно заменить api.baserow.io на свой URL бэкенда. Соединение WebSocket получает только сообщения, предназначенные для рабочих пространств, к которым принадлежит аутентифицированный пользователь. Пример подключения к WebSocket на JavaScript приведен ниже.

const socket = new WebSocket('wss://api.baserow.io/ws/core/?jwt_token=YOUR_JWT_TOKEN')
socket.onopen = () => {
    console.log('Соединение установлено')
}
socket.onmessage = (message) => {
    console.log('Получено', message)
}

Сообщения

Транслируемые сообщения, содержащие обновления в реальном времени, всегда являются JSON и всегда содержат ключ type, указывающий, что изменилось. Например, значение create_application может быть значением типа, и в этом случае будет предоставлен дополнительный ключ application, содержащий новое созданное приложение в сериализованной форме.

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

{
   "type": "application_created",
   "application": {
      "id": 123,
      "name": "Test",
      "order": 8,
      "type": "database",
      "workspace": {
         "id": 1,
         "name": "Bram's workspace"
      },
      "tables": []
   }
}

WebSocket ID

После установления соединения вы получите сообщение authentication, указывающее на успешность аутентификации JWT токена. Если аутентификация успешна, сообщение также будет содержать web_socket_id. При внесении изменений через API, например, при создании нового приложения, вы можете предоставить этот идентификатор в заголовке WebSocketId: {YOUR_WEB_SOCKET_ID}, чтобы исключить себя из сообщения, содержащего уже выполненные изменения. Пример сообщения аутентификации с web_socket_id и пример HTTP-запроса с заголовком WebSocketId приведены ниже.

{
  "type": "authentication",
  "success": true,
  "web_socket_id": "934254ab-0c87-4dbc-9d71-7eeab029296c"
}

PATCH /api/applications/1/
Host: api.baserow.io
Content-Type: application/json
WebSocketId: 934254ab-0c87-4dbc-9d71-7eeab029296c

{
  "name": "Test",
}

Подписка на страницу

Пользователь по умолчанию получает все основные сообщения, связанные с рабочими пространствами и приложениями, но у нас также есть сообщения, связанные с определенными страницами, например, со страницей таблицы. Чтобы не вызывать перегрузку сообщений, вы можете подписаться на страницу интересующую вас. Также возможно быть подписанным на несколько страниц. Если подписка успешна, вы будете получать сообщения, связанные с этой страницей. Чтобы прекратить получение обновлений, вам нужно вручную отписаться от страницы.

Страница таблицы

Подписка на страницу таблицы запрашивает обновления, связанные с таблицей Baserow, что даст вам информацию о новых строках, обновлениях строк и другой релевантной информации.

Страница таблицы ожидает параметр table_id. Пример подписки на эту страницу приведен ниже.

{
  "page": "table",
  "table_id": 1
}

После успешной подписки вы получите подтверждающее сообщение, указывающее на то, что вы подписаны на страницу.

{
    "type": "page_add",
    "page": "table",
    "parameters": {
        "table_id": 1
    }
}

Страница строки

Подписка на страницу строки запрашивает дополнительные обновления, связанные с определенной строкой таблицы Baserow, что даст вам информацию о таких событиях как обновление истории строки. Обратите внимание, что для получения обновлений, таких как удаление строк и подобные события, следует использовать страницу таблицы, описанную выше.

Страница строки ожидает параметры table_id и row_id. Пример подписки на эту страницу приведен ниже.

{
  "page": "row",
  "table_id": 1,
  "row_id": 1
}

После успешной подписки вы получите подтверждающее сообщение, указывающее на то, что вы подписаны на страницу.

{
    "type": "page_add",
    "page": "row",
    "parameters": {
        "table_id": 1,
        "row_id": 1
    }
}

Отписка от страницы

Чтобы прекратить получение обновлений, связанных с страницей, на которую вы подписаны, вам нужно отправить сообщение remove_page с теми же параметрами страницы, которые привели к подписке:

{
  "remove_page": "row",
  "table_id": 1,
  "row_id": 1
}

Типы сообщений

• authentication
• page_add
• page_discard
• before_group_deleted
• user_updated
• user_deleted
• user_restored
• user_permanently_deleted
• group_created
• group_updated
• group_deleted
• group_restored
• group_user_added
• group_user_updated
• group_user_deleted
• application_created
• application_updated
• application_deleted
• applications_reordered

Типы сообщений базы данных

• table_created
• table_updated
• table_deleted
• tables_re_ordered
• field_created
• field_updated
• field_deleted
• field_restored
• rows_created
• rows_updated
• rows_deleted
• before_rows_update
• before_rows_delete
• row_history_updated
• view_created
• view_updated
• view_deleted
• view_filter_created
• view_filter_updated
• view_filter_deleted
• view_filter_group_created
• view_filter_group_updated
• view_filter_group_deleted
• view_sort_created
• view_sort_updated
• view_sort_deleted
• view_decoration_created
• view_decoration_updated
• view_decoration_deleted
• view_field_options_updated
• views_reordered

Типы сообщений премиум

• row_comment_created
• row_comment_updated
• row_comment_deleted