> For the complete documentation index, see [llms.txt](https://docs.edgegap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.edgegap.com/ru/docs/tools-and-integrations/playfab-bridge.md).

# Развертывание из PlayFab

Сохраните PlayFab Matchmaking и запускайте выделенный сервер Edgegap рядом с игроками для каждого матча с помощью двух функций Azure.

Используйте **PlayFab** для учётных записей игроков и очередей подбора матчей, а каждый матч запускайте на отдельном **Edgegap** выделенном сервере, расположенном рядом с подобранными игроками. Их связывают две функции Azure:

* Когда PlayFab находит матч, `StartEdgegapDeployment` запрашивает у Edgegap сервер рядом с игроками и сразу возвращает управление.
* Когда сервер готов, Edgegap вызывает `EdgegapDeploymentReady`, которая записывает адрес сервера и **токен подключения** в данные PlayFab каждого игрока, доступные только для чтения. **только для чтения** PlayFab.

Токен API Edgegap и секретный ключ заголовка PlayFab хранятся в настройках приложения Function App. Игровой клиент содержит только идентификатор заголовка, а на игровом сервере вообще нет секретов. Он допускает только игроков, которых подобрал PlayFab.

```
Клиент --LoginWithCustomID / CreateMatchmakingTicket--> очередь PlayFab (выделение сервера отключено)
PlayFab --правило для match_found--> функция Azure StartEdgegapDeployment
             GetMatch + местоположение игроков --POST /v2/deployments--> Edgegap
Edgegap --webhook_on_ready--> функция Azure EdgegapDeploymentReady
             считывает данные о развёртывании и матче --UpdateUserReadOnlyData "EdgegapServer"--> для каждого игрока
                                              (хост, порт, токен подключения)
Клиент опрашивает GetUserReadOnlyData --> подключается к host:port, отправляет токен подключения --> сервер останавливает себя, когда игроков не остаётся
```

Пример проекта **SpaceEdge**доступен на [GitHub](https://github.com/edgegap/backend-game-sample-unity-playfab-matchmaker-fishnet-spaceedge). Полный цикл был протестирован 21 октября 2026 года с Unity 2021.3.45f2, FishNet 3.11.14 (Tugboat, UDP 7770), Node.js 22 в Azure Functions (Flex Consumption) и очередью PlayFab на 2 игроков: PlayFab подобрал двух клиентов, и примерно через 8 секунд после вызова функции оба получили адрес сервера. Токены подключения и сборка с плагином Edgegap для Unity появились после этого запуска; их проверили модульными тестами и в локальном контейнере сервера.

{% hint style="info" %}
**Используете агент для написания кода?** Навык `edgegap-playfab` на [MCP-сервере Edgegap](https://docs.edgegap.com/ru/docs/integraciya-mcp.md) включает те же функции Azure, скрипты для их развёртывания и создания очереди, код клиента и сервера для Unity, а также сквозной тест, который нужно запустить до добавления правила.
{% endhint %}

## 🚀 Начало работы

Перед началом вам понадобятся:

* Рабочая **версия приложения Edgegap** с сервером вашей игры: сервер, который вы развернули и к которому подключились хотя бы один раз. См. разделы для [Unity](https://docs.edgegap.com/ru/unity.md), [Unreal Engine](https://docs.edgegap.com/ru/unreal-engine.md) или [Godot](https://docs.edgegap.com/ru/godot.md). Назовите игровой порт `gameport`. Серверу не нужны настройки или секреты PlayFab.
* Заголовок **PlayFab** с функцией Matchmaking, его идентификатор и секретный ключ.
* Один **Подписка Azure** и [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli). Тестирование укладывается в ежемесячный бесплатный лимит плана Flex Consumption.
* Токен **API Edgegap**, из раздела [Панель управления → Настройки пользователя → Токены](https://app.edgegap.com/user-settings?tab=tokens). Он указывается только в настройках Function App.

{% hint style="warning" %}
В более ранних версиях этого руководства использовался JavaScript CloudScript, а секрет заголовка PlayFab передавался игровому серверу. Теперь Microsoft называет JavaScript CloudScript «классическим» и рекомендует для новых проектов [CloudScript с использованием Azure Functions](https://learn.microsoft.com/en-us/gaming/playfab/live-service-management/service-gateway/automation/cloudscript-af/quickstart). Используйте приведенные ниже Azure Functions и удалите секрет PlayFab с сервера.
{% endhint %}

## 1. Игровой сервер

Сервер должен прослушивать свой порт, допускать только игроков, участвующих в матче, и завершать работу по окончании матча.

* **Прослушивайте фиксированный порт**, указанный как `gameport` в версии приложения. В примере сервер прослушивает UDP-порт 7770.
* **Останавливайте собственное развертывание** если никто не подключился или после выхода последнего игрока: отправьте запрос `DELETE` на `ARBITRIUM_DELETE_URL` с заголовком `authorization: <ARBITRIUM_DELETE_TOKEN>`. Оба значения [добавляются в каждое развертывание](https://docs.edgegap.com/ru/learn/orkestraciya/deployments.md#injected-environment-variables). В примере сервер останавливается через 120 секунд, если никто не подключился, или через 30 секунд после выхода последнего игрока.
* **Допускайте только игроков, участвующих в матче.** `StartEdgegapDeployment` передает токены подключения к матчу в скрытой переменной `EDGEGAP_JOIN_TOKENS` (список значений, разделенных запятыми); каждый клиент получает собственный токен вместе с адресом сервера. Пусть каждый клиент отправляет свой токен сразу после подключения, а клиенты с токеном, которого нет в списке, отключаются. Разрешите новому подключению с известным токеном заменять старое, чтобы игрок, у которого произошел сбой игры, мог подключиться снова до истечения времени ожидания старого подключения.
* Удалите все вызовы PlayFab GSDK. PlayFab Multiplayer Servers не используются.

`StartEdgegapDeployment` также передает `PLAYFAB_MATCH_ID` и `PLAYFAB_QUEUE_NAME` как переменные среды — для журналов или игровой логики.

{% hint style="info" %}
В примере `EdgegapServer.cs` делает все это и добавляет себя во время выполнения в сборках сервера, не требуя настройки сцены. `JoinTokenAuthenticator.cs` проверяет токены с помощью аутентификатора FishNet; при использовании другого сетевого кода воспользуйтесь его механизмом подтверждения подключения или первым сообщением. Если вы используете FishNet, отключите параметр **Start On Headless** в `ServerManager`: `EdgegapServer.cs` запускает сервер на известном порту.
{% endhint %}

Соберите сервер, создайте для него контейнер и отправьте его, как обычно, затем создайте версию приложения: один порт с именем `gameport` (в примере — UDP 7770), 0,5 vCPU и 1 ГБ, максимальная длительность — 60 минут. Для версии переменные окружения не нужны: функция передаёт их для каждого матча.

{% hint style="warning" %}
В стандартном Dockerfile плагина Edgegap для Unity (до версии 3.2.1 включительно) перед сервером запускается команда `env` поэтому в журналах развёртывания перечислены его переменные, включая токены для подключения и токен для самостоятельной остановки. Если вы делитесь журналами, удалите `env;` из команды `CMD` в Dockerfile.
{% endhint %}

## 2. Очередь подбора игроков PlayFab

1. В Game Manager откройте раздел **Multiplayer → Matchmaking** и создайте очередь (в примере используется `edgegap-fishnet`). Для первого теста задайте размер матча 2 и не добавляйте правил — так смогут объединиться любые два игрока.
2. Отключите параметр **Enable server allocation** **(положение «Выкл.»)**: PlayFab будет только формировать матчи, а сервер будет размещаться в Edgegap.
3. Если игроки входят в систему с помощью `LoginWithCustomID` или идентификатора устройства, откройте раздел **Title settings → API Features** и снимите флажок **Disable player creation using Client/LoginWithCustomId**. Для новых игр этот флажок установлен, и вход завершается ошибкой `PlayerCreationDisabled`.
4. В разделе **Title settings → Secret Keys**создайте секретный ключ для Azure Functions.

{% hint style="warning" %}
**Переносите действующую очередь с PlayFab Multiplayer Servers?** Уже выпущенные клиенты получают данные о сервере через `GetMatch`, который перестанет возвращать эти данные после отключения распределения серверов. Проверьте всё на копии очереди и выпустите обновлённый клиент до переключения.
{% endhint %}

## 3. Azure Functions

Создайте группу ресурсов, учётную запись хранения и приложение Function App с планом Flex Consumption на Node.js 22. PlayFab рекомендует регион US West:

```bash
az group create -n rg-edgegap-playfab -l westus2
az storage account create -n <storageaccount> -g rg-edgegap-playfab -l westus2 --sku Standard_LRS
az functionapp create -g rg-edgegap-playfab -n <function-app> --storage-account <storageaccount> \
  --flexconsumption-location westus2 --runtime node --runtime-version 22
```

Разверните папку `azure-functions` из примера (Node.js 22, без SDK PlayFab и Edgegap):

```bash
cd azure-functions
npm ci --omit=dev
# упакуйте host.json, package.json, src/ и node_modules/ в bridge.zip, затем выполните:
az functionapp deployment source config-zip -g rg-edgegap-playfab -n <function-app> --src bridge.zip
```

Добавьте параметры приложения (Function App → Settings → Environment variables):

| Параметр                                   | Значение                                                                                                                                                                  |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PLAYFAB_TITLE_ID`                         | Идентификатор вашей игры.                                                                                                                                                 |
| `PLAYFAB_SECRET_KEY`                       | Секретный ключ игры.                                                                                                                                                      |
| `EDGEGAP_API_TOKEN`                        | Токен API Edgegap без префикса `token` .                                                                                                                                  |
| `EDGEGAP_APP_NAME` / `EDGEGAP_APP_VERSION` | Названия приложения и версии.                                                                                                                                             |
| `EDGEGAP_READY_WEBHOOK_URL`                | `https://<function-app>.azurewebsites.net/api/EdgegapDeploymentReady?code=<function key>`                                                                                 |
| `EDGEGAP_PORT_NAME`                        | Необязательный параметр; по умолчанию используется `gameport`.                                                                                                            |
| `EDGEGAP_QUEUES`                           | Необязательный параметр, значения разделяются запятыми. `match_found` срабатывает для каждой очереди вашей игры; сервер Edgegap выделяется только для указанных очередей. |
| `FALLBACK_LATITUDE` / `FALLBACK_LONGITUDE` | Необязательные параметры. Используются, если PlayFab не располагает данными о местоположении ни одного игрока.                                                            |

Получите ключ для каждой функции с помощью команды `az functionapp function keys list -g rg-edgegap-playfab -n <function-app> --function-name <name>`.

{% hint style="danger" %}
Ключи функций — это секреты: они входят в URL-адреса функций, поэтому не добавляйте эти URL-адреса в репозиторий и не передавайте их другим. Никогда не помещайте токен Edgegap или секретный ключ PlayFab в клиент игры, на игровой сервер или в свой репозиторий.
{% endhint %}

### StartEdgegapDeployment

Запускается при событии PlayFab `match_found` :

1. Читает из события `MatchId` и `QueueName` .
2. Получает участников матча с помощью `Match/GetMatch`, а местоположение каждого игрока — с помощью `Server/GetPlayerProfile` (PlayFab определяет их местоположение по IP-адресу, с которого они вошли в систему).
3. Вычисляет отдельный токен подключения для каждого игрока: HMAC от идентификатора матча и PlayFab ID игрока с использованием секретного ключа игры. Таким образом, `EdgegapDeploymentReady` впоследствии может вычислить те же токены, не сохраняя их.
4. Отправляет запрос `POST https://api.edgegap.com/v2/deployments` с координатами игроков, тегом из первых 20 символов идентификатора матча, токенами подключения в скрытой переменной `EDGEGAP_JOIN_TOKENS`, а также вебхуками готовности и ошибки.
5. Возвращает результат примерно через секунду. Ожидания запуска сервера нет: вызов PlayFab завершается по тайм-ауту через 10 секунд, а подготовка сервера занимает от 5 до 30 секунд.

```javascript
// azure-functions/src/lib/edgegap.js
return call('POST', '/v2/deployments', {
  application: requireSetting('EDGEGAP_APP_NAME'),
  version: requireSetting('EDGEGAP_APP_VERSION'),
  users: locations.map((l) => ({ user_type: 'geo_coordinates', user_data: l })),
  tags: [matchTag(matchId), 'playfab'],
  environment_variables: [
    { key: 'PLAYFAB_MATCH_ID', value: matchId, is_hidden: false },
    { key: 'PLAYFAB_QUEUE_NAME', value: queueName, is_hidden: false },
    {
      key: join.ENV_KEY, // EDGEGAP_JOIN_TOKENS
      value: players.map((p) => join.joinToken(matchId, p.playFabId)).join(','),
      is_hidden: true,
    },
  ],
  webhook_on_ready: { url: webhook.toString() },
  webhook_on_error: { url: errorWebhook.toString() },
});
```

### EdgegapDeploymentReady

Вызывается Edgegap через вебхук готовности, а не PlayFab, поэтому не регистрируйте эту функцию в PlayFab.

1. Функция не доверяет телу вебхука: она получает сведения о развертывании через API Edgegap и проверяет, что к нему прикреплен тег этого матча.
2. Она повторно получает список участников матча из PlayFab.
3. Функция записывает `{"matchId", "status", "host", "port", "joinToken"}` в данные **только для чтения** каждого игрока под ключом `EdgegapServer`, используя `Server/UpdateUserReadOnlyData`. Клиенты могут читать эти данные, но не могут их изменять.
4. Если сервер не запустился, функция записывает `status: "error"`, чтобы клиенты перестали ждать.

### Зарегистрируйте функцию и добавьте правило

1. В разделе **Автоматизация → CloudScript → Функции → Зарегистрировать функцию**зарегистрируйте функцию `StartEdgegapDeployment` и укажите ее URL, включая `?code=<function key>`.
2. В разделе **Автоматизация → Правила → Новое правило**задайте тип события `playfab.matchmaking.match_found` и добавьте действие **Выполнить функцию Azure → StartEdgegapDeployment**.

{% hint style="info" %}
После создания правила ручной вызов `StartEdgegapDeployment` для того же матча запустит второй сервер. Протестируйте функции вручную, прежде чем добавлять правило.
{% endhint %}

## 4. Игровой клиент

1. Выполните вход игрока в PlayFab (в примере используется `LoginWithCustomID`; используйте способ входа в свою игру). Клиенту нужен только идентификатор вашего проекта.
2. Создайте заявку в очереди с помощью `Match/CreateMatchmakingTicket` и проверяйте его с помощью `Match/GetMatchmakingTicket` каждые 6 секунд, пока его статус не станет `Matched`. PlayFab разрешает проверять статус одного билета 10 раз в минуту.
3. Прочитайте `EdgegapServer` с помощью `Client/GetUserReadOnlyData` каждые 2–3 секунды. Игнорируйте значения, у которых `matchId` не совпадает с идентификатором текущего матча: это значение осталось от предыдущего матча.
4. Подключитесь к `host:port`и отправьте `joinToken` сразу после установления соединения. Если получено `status: "error"`, покажите сообщение об ошибке и разрешите игроку снова встать в очередь.

В примере `PlayFabMatchmakingClient.cs` это реализовано только с помощью `UnityWebRequest` и `JsonUtility` , без SDK PlayFab. Единственный фрагмент кода, зависящий от сетевого кода игры, — вызов подключения:

```csharp
// FishNet (Tugboat UDP); JoinTokenAuthenticator отправляет токен после подключения
JoinTokenAuthenticator.Install(InstanceFinder.NetworkManager).Token = joinToken;
InstanceFinder.TransportManager.Transport.SetClientAddress(host);
InstanceFinder.TransportManager.Transport.SetPort(port);
InstanceFinder.ClientManager.StartConnection();
```

Если ваша игра уже использует SDK PlayFab, выполните те же вызовы через него.

## 5. Тестирование

1. Убедитесь, что другие развёртывания не запущены: на бесплатном тарифе одновременно может работать только одно развёртывание.
2. Запустите два клиента от имени разных игроков PlayFab. На одном компьютере они используют общие PlayerPrefs, поэтому задайте каждому свой идентификатор: в примере используются `-playfabCustomId player-a` и `-playfabCustomId player-b`.
3. Запустите поиск матча на обоих клиентах. Когда PlayFab подберёт им матч, на панели управления [Edgegap](https://app.edgegap.com/deployment-management/deployments/list)появится развёртывание с тегом, начинающимся с идентификатора матча, и через несколько секунд оба клиента подключатся к нему.
4. Завершите работу обоих клиентов: сервер остановится автоматически.

| Симптом                                                 | Решение                                                                                                                                                                                  |
| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PlayerCreationDisabled` при входе                      | Снимите флажок **Disable player creation using Client/LoginWithCustomId** (шаг 2).                                                                                                       |
| Совпадение найдено, но адрес сервера отсутствует        | Проверьте журналы Function App (Application Insights или вкладку Monitor каждой функции), а также убедитесь, что тип события правила указан точно как `playfab.matchmaking.match_found`. |
| `Edgegap POST /v2/deployments failed (401)`             | `EDGEGAP_API_TOKEN` указан неверно или всё ещё содержит префикс `token` .                                                                                                                |
| Вебхук ничего не записывает                             | `EDGEGAP_READY_WEBHOOK_URL` должен содержать ключ `code=` для `EdgegapDeploymentReady`.                                                                                                  |
| Оба клиента входят в систему под одним и тем же игроком | Запустите их с разными значениями `-playfabCustomId` .                                                                                                                                   |
| Развёртывание запускается, но никто не подключается     | Проблема на стороне сервера: разверните свою версию вручную и подключитесь к ней напрямую.                                                                                               |
| Журнал сервера `rejected: not a player of this match`   | Клиент не отправил токен или отправил токен от другого матча. Убедитесь, что обе функции выполняют один и тот же код и используют один и тот же `PLAYFAB_SECRET_KEY`.                    |

Переходите с PlayFab Multiplayer Servers? См. [Переход с PlayFab](https://docs.edgegap.com/ru/docs/migraciya-khostinga/switch-from-playfab.md) — здесь описаны изменения.

Нужен размещённый сервис подбора игроков, для которого не нужно запускать функции? См. [Подбор игроков Edgegap](https://docs.edgegap.com/ru/learn/matchmeiking.md).
