# Браузер серверов
Быстро начните работу с Server Browser и изучите примеры сценариев для разных жанров.
Server Browser — это управляемый сервис для [Развертывания](/ru/learn/orkestraciya/deployments.md#match-bound) и [постоянных](/ru/learn/orkestraciya/postoyanstvo.md) серверов:
* **помогать игрокам искать подходящие серверы и подключаться к ним** на основе вместимости, задержки или игровых параметров;
* **предварительно прогревать новые серверы** чтобы обслуживать глобальную аудиторию в масштабе и предотвращать раздражающие очереди;
* **упрощать управление серверами** включая обновления, перезапуски, постоянство, mesh-сети и многое другое.
{% hint style="success" %}
Хотите подбирать игроков по строгим правилам, не позволяя им выбирать сервер? Рассмотрите [Подбор соперников](/ru/learn/podbor-sopernikov.md).
{% endhint %}
## ✔️ Подготовка
### Функции и поток
Server Browser: поток и иерархия
Server Browser предлагает две основные функции:
[#start-browsing](#start-browsing "mention") с игровыми клиентами, чтобы:
* находить подходящие экземпляры серверов, просматривать слоты и резервировать доступную вместимость.
* резервировать места в слоте экземпляра, получать данные для подключения и подключаться к серверам.
* аутентифицировать подключения игроков в развертываниях с использованием [федеративной идентификации](#user-content-fn-1)[^1].
* обновлять доступную вместимость и/или метаданные слотов экземпляра, чтобы изменять критерии обнаружения.
[#automated-scaling](#automated-scaling "mention") (необязательно) с политиками масштабирования, чтобы:
* отслеживать доступные экземпляры серверов, слоты, вместимость — по регионам и/или другим критериям.
* развертывать серверы для увеличения вместимости с помощью предварительного прогрева или масштабирования just-in-time.
* автоматизировать операции с помощью специальных политик для демо, обновлений, тестирования, QA, турниров и многого другого.
{% hint style="info" %}
После релиза **ваш серверный браузер должен работать 24/7** чтобы игроки по всему миру могли подключаться к серверам.
{% endhint %}
## ▶️ Начать просмотр
Узнайте о жизненном цикле сервера/игрока и их обязанностях, чтобы обеспечить эффективное использование серверов.
### Аутентификация
Server Browser автоматически генерирует два типа токенов:
* **Токен сервера** - требуется для [методов Server API](#server-lifecycle) может быть [внедрён как переменная версии приложения](/ru/learn/orkestraciya/application-and-versions.md#injected-variables).
* Даёт доступ ко всем методам API и удобен для тестирования, DevOps или пользовательской оркестрации.
* **Токен клиента** - требуется для [Monitor API и Seat Reservation API](#player-lifecycle) используется игровыми клиентами.
* Мы рекомендуем хранить этот токен в стороннем хранилище секретов, чтобы упростить ротацию токена.
### Обнаружение экземпляра
{% hint style="warning" %}
**Новый** [Развертывания](/ru/learn/orkestraciya/deployments.md) **должен создать новый экземпляр** при инициализации, чтобы отслеживать добавленную вместимость.
{% endhint %}
{% hint style="info" %}
См. [#automated-scaling](#automated-scaling "mention") чтобы узнать о политиках масштабирования и автоматически запускать развертывания.
{% endhint %}
**Обязательная информация** для каждого экземпляра сервера включает:
* как минимум один слот, определённый при инициализации экземпляра,
* данные подключения к серверу — URL, IP, информация о порте и местоположение.
**Необязательные пользовательские параметры метаданных** для фильтрации, сортировки и просмотра игроками; например:
* информация о слоте — вместимость команды и специфичные для команды метаданные (например, название команды),
* название и теги — настраиваемые, уникальные, читаемые человеком и доступные для поиска метки;
* данные совместимости — версия сервера или поддерживаемые версии клиента;
* квалификаторы задержки — идентификаторы города и региона, и назначенные [Пинг-маяки](/ru/learn/orkestraciya/ping-beacons.md) сведения;
* игровые параметры — уровень/сцена/карта, режим игры, сложность, используемые моды;
* любые другие пользовательские параметры, которые помогут игрокам фильтровать и находить подходящий сервер.
{% hint style="info" %}
Параметры метаданных выше — лишь примеры, вы можете определить любое количество параметров по необходимости.
{% endhint %}
{% hint style="success" %}
Чтобы сериализовать вложенные объекты, попробуйте кодировать путь доступа к ним в ключе как `"object.child.property"`.
{% endhint %}
Серверы могут **обновлять метаданные экземпляра или слота в любое время** чтобы изменить критерии обнаружения. При обновлении метаданных все индексированные ключи должны быть указаны с корректными значениями (даже если они не изменялись).
**Экземпляры сервера должны периодически отправлять heartbeat keep-alive** чтобы подтверждать свою доступность и предотвращать подключение игроков к упавшим или офлайн-серверам. Отсутствие heartbeat в течение настроенного срока истечения автоматически удалит экземпляр и любые ожидающие резервации мест.
{% hint style="info" %}
См. [Постоянство](/ru/learn/orkestraciya/postoyanstvo.md) для управления постоянным состоянием мира и [Приложения и версии](/ru/learn/orkestraciya/application-and-versions.md#active-caching) для более быстрых развертываний.
{% endhint %}
### Выделение вместимости
Вместимость экземпляра и слота может выделяться двумя способами, по отдельности или в сочетании:
* [#auto-assigned-reservation](#auto-assigned-reservation "mention") чтобы выбрать сервер, запущенный с определённой политикой масштабирования,
* [#search-and-browse](#search-and-browse "mention") чтобы дать игроку возможность задавать фильтры и просматривать подходящие серверы для выбора.
{% hint style="success" %}
Мы рекомендуем начать с [#auto-assigned-reservation](#auto-assigned-reservation "mention") как с более простого варианта.
{% endhint %}
#### Автоназначаемая резервация
{% hint style="info" %}
Реализуйте эту функцию, если хотите **автоматически выбирать сервер**, на основе региональной вместимости.
{% endhint %}
Игроки могут создать автоназначаемую резервацию, указав только ID игроков и имя политики масштабирования. Server Browser автоматически найдёт экземпляр со слотом, предлагающим достаточную доступную для подключения вместимость, зарезервирует места и сразу ответит данными для подключения к экземпляру.
Если для этой резервации нет подходящего слота экземпляра, ответ:
* **код статуса указывает, масштабируется ли политика вверх** и будет добавлена дополнительная вместимость,
* **заголовок `Retry-After` указывает период ожидания (в секундах) перед повторной попыткой**, если повтор возможен.
После завершения резервации вы можете перейти к [#connect-to-server](#connect-to-server "mention").
#### Поиск и просмотр
{% hint style="info" %}
Реализуйте эту функцию, если хотите **показывать пользователям список серверов и разрешать пользовательские резервации**.
{% endhint %}
Игроки могут перечислять экземпляры серверов и [пагинировать результаты](#pagination) чтобы найти сервер, к которому они хотят присоединиться.
Экземпляры и слоты могут фильтроваться и сортироваться с помощью встроенных параметров или [индексированных метаданных](#configuration):
Свойство
Тип данных
Экземпляр
Слот
request_id
string
✅
❌
total_joinable_seats, total_available_seats
int
✅
❌
name
string
❌
✅
available_seats, reserved_seats
int
❌
✅
created_at, updated_at
string
✅
✅
metadata.{index} (пользовательский)
string, int, float, bool
✅
✅
Доступные операторы фильтрации зависят от типа данных фильтруемого свойства:
?$filter=metadata.custom_name contains 'my game'
and metadata.server_version le '1.1.0'
and metadata.server_version ge '1.0.0'
&$order=metadata.custom_name asc
{% hint style="success" %}
Фильтруйте по метаданным регионов и/или городов, чтобы сузить выбор перед измерением задержки до серверов.
{% endhint %}
{% hint style="info" %}
Узнайте о курсорной [#pagination](#pagination "mention") чтобы позволить пользователям получать больше результатов.
{% endhint %}
#### Резервирование мест
Перед подключением к серверу требуется резервирование места, чтобы убедиться, что экземпляр предлагает достаточную доступную вместимость. Резервации могут включать группу игроков или одного человека.
Федеративная идентификация: игроки должны указать уникальный ID игрока стороннего сервиса в своей резервации. Отправка того же ID после того, как они [#connect-to-server](#connect-to-server "mention") позволит серверу подтвердить их личность.
После успешного создания резервации ([200 OK](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/200)), игрокам следует немедленно попытаться подключиться. Ожидающие **резервации истекают через 30 секунд (настраиваемо), если не подтверждены** вашим сервером.
**Резервации, превышающие доступную для подключения вместимость слота, будут автоматически отклонены** ([409 Conflict](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/409)). Доступными для подключения местами являются любые доступные места, которые ещё не зарезервированы другими игроками.
{% hint style="info" %}
Сервер может принудительно изменить вместимость любого слота, добавить, удалить или обновить любые слоты. **Все резервации для данного слота будут удалены, если любые ожидающие резервации превышают новую доступную вместимость слота.**
{% endhint %}
### Подключение к серверу
После того как игрок нашёл подходящий экземпляр, он **получает необходимые данные для подключения из** (URL или IP, [внешний порт](/ru/learn/orkestraciya/application-and-versions.md#port-mapping)). Как только резервирование места выполнено, **игроки могут подключаться к игровому серверу вашего развертывания и передавать свой ID игрока**.
{% tabs %}
{% tab title="Unreal Engine" %}
Чтобы **подключиться из PIE (Editor)** во время разработки и тестирования нажмите клавишу тильды `~` и введите `open {URL}:{port}` и дождитесь загрузки карты в редакторе.
{% hint style="success" %}
В случае неудачного подключения или чёрного экрана обратитесь к нашему [руководству по устранению неполадок](/ru/unreal-engine.md#troubleshooting-and-faq-1).
{% endhint %}
{% endtab %}
{% tab title="Unity" %}
Чтобы **подключите ваш Unity Editor** или **игровой клиент** к вашему облачному развертыванию, укажите:
* **Развертывание** **URL** указывающий на IP сервера, обычно в `NetworkManager` компоненте.
* **Внешний порт** соответствующий [внутреннему порту прослушивания сервера](https://docs.edgegap.com/learn/advanced-features/application-and-versions#port-mapping), обычно в компоненте Transport.
{% hint style="success" %}
В случае тайм-аута подключения или других проблем обратитесь к нашему [руководству по устранению неполадок](/ru/unity.md#troubleshooting-and-faq-4).
{% endhint %}
{% endtab %}
{% endtabs %}
Для аутентификации новых подключений **ваш сервер должен отправить массовый запрос подтверждения резервации** со всеми ID новых игроков, получив информацию в ответе подтверждения:
* назначение принятых резерваций игроков в их предпочтительный слот,
* назначение просроченных резерваций игроков в их предпочтительный слот,
* список неизвестных ID игроков.
Ваш **сервер может решать, как обрабатывать каждую группу игроков** и разрешать ли или кикать/банить просроченных или отклонённых пользователей. Каждый из **слотов экземпляра должен быть немедленно обновлён с новым количеством доступных мест** чтобы гарантировать, что будущие резервации не превысят вместимость слота.
### Покинуть сервер
Когда игроки уходят, ваш сервер должен увеличить доступную вместимость мест для назначенного слота.
{% hint style="success" %}
Если дизайн вашей игры допускает период повторного подключения, ваш сервер может подождать перед обновлением слотов.
{% endhint %}
Прочитайте о [Постоянство](/ru/learn/orkestraciya/postoyanstvo.md#recovery-objectives) чтобы предотвратить раздражающие откаты постоянного сервера.
## 🚀 Автоматическое масштабирование
Server Browser совместим с несколькими различными методами автоскейлинга:
* **метод предварительного прогрева** - запуск серверов строго с политиками масштабирования Server Browser,
* **метод just-in-time** - запуск через [Подбор соперников](/ru/learn/podbor-sopernikov.md) и [заполнение через Server Browser](#allocate-capacity),
* **пользовательский автоскейлер** - запуск через пользовательский игровой backend и [заполнение через Server Browser](#allocate-capacity).
Следующее руководство будет сосредоточено на **предварительном прогреве с политиками масштабирования** как на основном методе.
{% hint style="success" %}
Узнайте, как останавливать развертывания в [Unreal Engine](/ru/unreal-engine.md#stop-deployments), [Unity](/ru/unity.md#stop-deployments), или [с API](/ru/docs/api/vydelennye-servery.md#delete-v1-self-stop-request_id-access_point_id) для надёжного управления жизненным циклом.
{% endhint %}
### Мониторинг вместимости
Политики масштабирования непрерывно обновляют список ваших экземпляров серверов (обнаруженных развертываний), повторяя это каждые [`monitoring_interval`](#user-content-fn-8)[^8] . Каждая политика требует фильтр с тем же [синтаксисом фильтрации](#search-and-browse) что и у игроков при поиске экземпляров — по региону, вместимости или другим критериям.
Ваш настроенный [`minimum_active_instances`](#user-content-fn-9)[^9] объём можно рассматривать либо как:
* **фиксированную вместимость** развертываний, которые вы хотите поддерживать запущенными постоянно,
* **буфер резервных** развертываний для скрытия задержек инициализации.
#### Фиксированная вместимость
Держите фиксированное количество активных серверов для игр с [Постоянство](/ru/learn/orkestraciya/postoyanstvo.md), особенно когда такие игры предоставляют игрокам возможность выделять [Постоянство](/ru/learn/orkestraciya/postoyanstvo.md#community-servers).
Этот тип конфигурации политики также иногда используется для обеспечения качества, турниров, закрытых альф, демо издателя или других событий и операций с ограниченной вместимостью.
{% hint style="info" %}
Политика масштабирования помогает автоматически перезапускать и перерабатывать упавшие серверы на лету.
{% endhint %}
#### Буфер предварительного прогрева
Запускайте серверы заранее до появления спроса, если:
* вы запускаете крупный релиз и ожидаете быстрый приток игроков за короткий промежуток времени,
* или инициализация сервера занимает более 30 секунд ([не включая время развертывания](#user-content-fn-10)[^10]),
* или игра использует стратегии mesh-сети, требующие многоуровневых или кольцевых сетевых зависимостей.
### Развертывание серверов
Новые развертывания будут запускаться автоматически, когда количество отслеживаемых экземпляров сервера*s* опускается ниже настроенного минимума активных экземпляров. Все развертывания запрашиваются немедленно и повторяются бесконечно каждый интервал мониторинга после того, как [`deployment_registration_period`](#user-content-fn-8)[^8] истечёт.
{% hint style="warning" %}
Убедитесь, что новые развертывания [выполняют автообнаружение и создают экземпляры](#discover-instance) корректно соответствующие фильтру вашей политики, или **ваша политика может бесконечно зацикливаться и создавать большое количество неиспользуемых развертываний**!
{% endhint %}
Политики запускают развертывания с [Частные парки](/ru/learn/orkestraciya/chastnye-parki.md) (с Overflow to Cloud) или напрямую в Cloud.
Доступные параметры включают ([см. спецификацию API](/ru/docs/api/vydelennye-servery.md#private-fleets)):
* [**приложение и версию**](/ru/learn/orkestraciya/application-and-versions.md) - версия сборки, ресурсы и другие параметры оркестрации,
* **пользователи** - один набор географических координат для предпочтительного [размещения сервера](/ru/learn/orkestraciya/deployments.md#regional-standby),
* [**идентификаторы частных хостов**](/ru/learn/orkestraciya/chastnye-parki.md) - оставьте пустым для облака или укажите хосты в нужном регионе,
* [**теги**](/ru/learn/orkestraciya/deployments.md#dashboard-monitoring) - пометьте именем политики, чтобы потом найти развертывания, запущенные с этой политикой,
* [**переменные окружения**](/ru/learn/orkestraciya/deployments.md#custom-variables) - передавайте серверам пользовательские параметры и секреты,
* [**webhook-ы**](/ru/learn/orkestraciya/deployments.md#webhooks-and-postbacks) - уведомляйте ваш игровой backend (или матчмейкер) о событиях жизненного цикла развертывания,
* [**требовать кэшированные местоположения**](/ru/learn/orkestraciya/application-and-versions.md#active-caching) - если вы предпочитаете более быстрые развертывания только в кэшированных локациях.
### Примеры политик
Тестируйте и изменяйте любую из этих политик по необходимости. Большинство игр будут использовать несколько политик.
{% tabs %}
{% tab title="🍀 QA Pool" %}
Простая политика, чтобы один сервер всегда был развернут для тестирования.
{% endtab %}
{% tab title="🌡️ Предварительный прогрев" %}
Запускайте развертывания в 10 раз раньше релиза в ожидании спроса. Копируйте для каждого региона.
{% endtab %}
{% tab title="🔑 Сообщество" %}
Одна политика на каждого владельца сервера, с передачей пользовательского пароля, используемого для аутентификации сервера.
{% endtab %}
{% tab title="❄️ Mesh Group" %}
Одна политика на каждую группу серверов. Игровой backend запускает основной узел, который создаёт реплики. Каждый узел считывает внедрённый ID mesh-группы и ищет другие узлы для сетевого взаимодействия.
{% endtab %}
{% endtabs %}
## ⚙️ Конфигурация
API Server Browser генерируется из JSON-конфигурации, указанной при создании нового (или при быстром перезапуске) Server Browser. Вы можете указать истечение срока жизни сервера и слота, а также пользовательские метаданные:
{% tabs %}
{% tab title="🍀 Простой пример" %}
{% endtab %}
{% endtabs %}
{% hint style="info" %}
Для наилучшей производительности избегайте указания индексов для метаданных, не используемых для фильтрации или сортировки. Неиндексируемые параметры всё равно можно задавать и читать с помощью методов API деталей экземпляра сервера или слота, см. [#api](#api "mention").
{% endhint %}
## ☁️ Хостинг-кластер
Server Browser удобно размещается и управляется Edgegap 24/7 без перерывов.
Выберите вариант хостинга, лучше всего подходящий для вашей цели:
### Уровни приватного кластера
Обновите до приватного кластера в один клик, чтобы воспользоваться высокодоступным хостингом, поддерживаемым командой Edgegap, с круглосуточной живой поддержкой для публично выпущенных игр.
Требования к ресурсам для вашего экземпляра будут зависеть от факторов:
* **количество игроков** - большее количество игроков приводит к большему числу API-запросов,
* **количество запросов на игрока** - более быстрые повторы увеличивают нагрузку на сервис и потребляют ресурсы,
* **количество серверов** - большее количество серверов приводит к большему объёму хранимых данных и большему числу API-запросов,
* **логика fallback-повторов на клиенте** - повторные попытки с jittered backoff помогают распределить пиковые всплески трафика,
* **средняя продолжительность матча** - более короткие сессии требуют более частого взаимодействия с браузером серверов.
## 📗 API
**Рассмотрите возможность использования нашего SDK для** [**Unreal Engine**](/ru/unreal-engine/developer-tools.md) **или** [**Unity**](/ru/unity/brauzer-serverov.md) **чтобы быстро начать работу с готовыми примерами.**
Игровые клиенты и выделенные серверы отправляют API-запросы на протяжении всего своего жизненного цикла в Server Browser.
{% file src="/files/597d4677aa9cdc5bddec091a1d4093cf7b7cb0d0" %}
Импортируйте спецификацию API в [Scalar API Web Client](https://client.scalar.com/workspace/default/request/default) или [Swagger Editor](https://editor.swagger.io/) чтобы просмотреть подробности.
### Пагинация
**Server Browser предоставляет курсорную пагинацию для постепенного получения отфильтрованных данных в определённом порядке.** Этот подход требует отправки курсора (начальной точки) и размера страницы (количества элементов ответа) при каждом запросе дополнительных результатов, в отличие от традиционной пагинации limit-offset.
{% hint style="info" %}
В сочетании с нашей фирменной системой индексации базы данных, разработанной для метаданных игровых серверов, курсорная пагинация обеспечивает быстрый, стабильный и гибкий пользовательский опыт при фильтрации очень динамичных данных.
{% endhint %}
Наша цель — чтобы пользователи находили подходящий сервер уже на первой странице. Для наилучшего опыта мы рекомендуем показывать кэшированные результаты для предыдущих страниц и обновлять результаты только тогда, когда пользователь нажимает «Поиск».
## 🔖 Журнал изменений
{% hint style="info" %}
**Последняя версия server browser — `1.0.0`** . Следите за [обновлениями и объявлениями](/ru/docs/release-notes.md).
{% endhint %}
[^1]: идентификаторов игроков сторонних сервисов
[^2]: равно
[^3]: не равно
[^4]: меньше чем
[^5]: меньше или равно
[^6]: больше чем
[^7]: больше или равно
[^8]: см. Конфигурация
[^9]: см. Примеры политик
[^10]: используйте активное кэширование, чтобы легко сократить время развертывания
[^11]: * фиксированную вместимость
* предполагает, что экземпляры передают имя политики в метаданных из внедрённой переменной
[^12]: замените на собственное имя приложения
[^13]: замените на собственную версию приложения
[^14]: координаты Чикаго
[^15]: * развертывается, когда найдено менее 10 экземпляров, доступных для подключения
* предполагает, что экземпляры передают имя политики в метаданных из внедрённой переменной
[^16]: мы ожидаем как минимум 10 развертываний в регионе Чикаго
[^17]: * развертывается, когда найдено менее 3 экземпляров с 5 или менее местами, доступными для подключения
* предполагает, что экземпляры передают имя политики в метаданных из внедрённой переменной
[^18]: предпочитать частный флот, если вместимость доступна
[^19]: уведомлять игровой backend при перезапуске сервера
[^20]: * не отслеживает вместимость
* предполагает, что экземпляры передают имя политики в метаданных из внедрённой переменной
[^21]: уведомлять игровой backend, когда всё готово
[^22]: уведомлять игровой backend, когда развертывание завершается с ошибкой
[^23]: уведомлять игровой backend при остановке
[^24]: сетка 3x3 = 9 серверов на мир
[^25]: индексы содержат ваши пользовательские параметры метаданных, используемые для фильтрации или сортировки
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.edgegap.com/ru/learn/brauzer-serverov.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.