マッチメイキングのカスタマイゼーションを開始する

Last updated on September 15, 2026

注釈：本資料はAI技術を用いて翻訳されています。

注記

AGS CLI は AGS 向けの統一コマンドラインツールであり、Extend と AMS のツールも含まれるようになりました。このページの手順は現在も有効です。統合ツールの詳細は AGS CLI のドキュメントを参照してください。

Overview

AccelByte Gaming Services (AGS) では、マッチメイキングのカスタムロジックを実装できます。

この記事では、Extend Override アプリテンプレートを例に、シンプルなカスタムマッチメーカーをセットアップする手順を説明します。

前提条件

C#
Go
Java
Python

Windows 11 WSL2/Linux Ubuntu 22.04 または macOS 14+ に、以下のツールをインストールしてください。

a. Bash
- Windows WSL2 または Linux Ubuntu の場合:
```
bash --version

GNU bash, version 5.1.16(1)-release (x86_64-pc-linux-gnu)
...
```
- macOS の場合:
```
bash --version

GNU bash, version 3.2.57(1)-release (arm64-apple-darwin23)
...
```
b. Make
- Windows WSL2 または Linux Ubuntu の場合:
  
  Ubuntu リポジトリからインストールするには sudo apt update && sudo apt install make を実行します。
```
make --version

GNU Make 4.3
...
```
- macOS の場合:
```
make --version

GNU Make 3.81
...
```
c. Docker (Docker Desktop 4.30+/Docker Engine v23.0+)
- Linux Ubuntu の場合:
  1. Ubuntu リポジトリからインストールするには sudo apt update && sudo apt install docker.io docker-buildx docker-compose-v2 を実行します。
  2. ユーザーを docker グループに追加します: sudo usermod -aG docker $USER。
  3. 変更を反映させるには、ログアウトして再度ログインします。
- Windows または macOS の場合:
  
  Windows または macOS 向けの Docker Desktop のインストールについては、Docker のドキュメントを参照してください。
```
docker version

...
Server: Docker Desktop
   Engine:
   Version:          24.0.5
...
```
d. .NET 8 SDK
- Linux Ubuntu の場合:
  
  Ubuntu リポジトリからインストールするには sudo apt-get update && sudo apt-get install -y dotnet-sdk-8.0 を実行します。
- Windows または macOS の場合:
  
  Windows または macOS のドキュメントに従ってください。
```
dotnet --version

8.0.119
```
e. Postman
- Postman から提供されているバイナリを使用してください。
f. extend-helper-cli
- extend-helper-cli から提供されているバイナリを使用してください。
g. TCP フォワーディング機能を持つローカルトンネルサービス。例:
- Ngrok
  
  無料プランの利用には登録が必要です。クイックスタートについては ngrok のドキュメントを参照してください。
- Pinggy
  
  登録なしで無料で試せます。クイックスタートについては pinggy のドキュメントを参照してください。

Windows 11 WSL2/Linux Ubuntu 22.04 または macOS 14+ に、以下のツールをインストールしてください。

a. Bash
- Windows WSL2 または Linux Ubuntu の場合:
```
bash --version

GNU bash, version 5.1.16(1)-release (x86_64-pc-linux-gnu)
...
```
- macOS の場合:
```
bash --version

GNU bash, version 3.2.57(1)-release (arm64-apple-darwin23)
...
```
b. Make
- Windows WSL2 または Linux Ubuntu の場合:
  
  Ubuntu リポジトリからインストールするには sudo apt update && sudo apt install make を実行します。
```
make --version

GNU Make 4.3
...
```
- macOS の場合:
```
make --version

GNU Make 3.81
...
```
c. Docker (Docker Desktop 4.30+/Docker Engine v23.0+)
- Linux Ubuntu の場合:
  1. Ubuntu リポジトリからインストールするには sudo apt update && sudo apt install docker.io docker-buildx docker-compose-v2 を実行します。
  2. ユーザーを docker グループに追加します: sudo usermod -aG docker $USER。
  3. 変更を反映させるには、ログアウトして再度ログインします。
- Windows または macOS の場合:
  
  Windows または macOS 向けの Docker Desktop のインストールについては、Docker のドキュメントを参照してください。
```
docker version

...
Server: Docker Desktop
   Engine:
   Version:          24.0.5
...
```
d. Go v1.24
- Go をインストールするには、Go のインストールガイドに従ってください。
```
go version

go version go1.24.0 ...
```
e. Postman
- Postman から提供されているバイナリを使用してください。
f. extend-helper-cli
- extend-helper-cli から提供されているバイナリを使用してください。
g. TCP フォワーディング機能を持つローカルトンネルサービス。例:
- Ngrok
  
  無料プランの利用には登録が必要です。クイックスタートについては ngrok のドキュメントを参照してください。
- Pinggy
  
  登録なしで無料で試せます。クイックスタートについては pinggy のドキュメントを参照してください。

Windows 11 WSL2/Linux Ubuntu 22.04 または macOS 14+ に、以下のツールをインストールしてください。

a. Bash
- Windows WSL2 または Linux Ubuntu の場合:
```
bash --version

GNU bash, version 5.1.16(1)-release (x86_64-pc-linux-gnu)
...
```
- macOS の場合:
```
bash --version

GNU bash, version 3.2.57(1)-release (arm64-apple-darwin23)
...
```
b. Make
- Windows WSL2 または Linux Ubuntu の場合:
  
  Ubuntu リポジトリからインストールするには sudo apt update && sudo apt install make を実行します。
```
make --version

GNU Make 4.3
...
```
- macOS の場合:
```
make --version

GNU Make 3.81
...
```
c. Docker (Docker Desktop 4.30+/Docker Engine v23.0+)
- Linux Ubuntu の場合:
  1. Ubuntu リポジトリからインストールするには sudo apt update && sudo apt install docker.io docker-buildx docker-compose-v2 を実行します。
  2. ユーザーを docker グループに追加します: sudo usermod -aG docker $USER。
  3. 変更を反映させるには、ログアウトして再度ログインします。
- Windows または macOS の場合:
  
  Windows または macOS 向けの Docker Desktop のインストールについては、Docker のドキュメントを参照してください。
```
docker version

...
Server: Docker Desktop
   Engine:
   Version:          24.0.5
...
```
d. JDK 17
- Linux Ubuntu の場合:
  
  Ubuntu リポジトリからインストールするには次を実行します: sudo apt update && sudo apt install openjdk-17-jdk。
- Windows または macOS の場合:
  
  こちらのドキュメントに従ってください。
```
java --version

openjdk 17.0.10 2024-01-16
...
```
e. Postman
- Postman から提供されているバイナリを使用してください。
f. extend-helper-cli
- extend-helper-cli から提供されているバイナリを使用してください。
g. TCP フォワーディング機能を持つローカルトンネルサービス。例:
- Ngrok
  
  無料プランの利用には登録が必要です。クイックスタートについては ngrok のドキュメントを参照してください。
- Pinggy
  
  登録なしで無料で試せます。クイックスタートについては pinggy のドキュメントを参照してください。

Windows 11 WSL2/Linux Ubuntu 22.04 または macOS 14+ に、以下のツールをインストールしてください。

a. Bash
- Windows WSL2 または Linux Ubuntu の場合:
```
bash --version

GNU bash, version 5.1.16(1)-release (x86_64-pc-linux-gnu)
...
```
- macOS の場合:
```
bash --version

GNU bash, version 3.2.57(1)-release (arm64-apple-darwin23)
...
```
b. Make
- Windows WSL2 または Linux Ubuntu の場合:
  
  Ubuntu リポジトリからインストールするには sudo apt update && sudo apt install make を実行します。
```
make --version

GNU Make 4.3
...
```
- macOS の場合:
```
make --version

GNU Make 3.81
...
```
c. Docker (Docker Desktop 4.30+/Docker Engine v23.0+)
- Linux Ubuntu の場合:
  1. Ubuntu リポジトリからインストールするには sudo apt update && sudo apt install docker.io docker-buildx docker-compose-v2 を実行します。
  2. ユーザーを docker グループに追加します: sudo usermod -aG docker $USER。
  3. 変更を反映させるには、ログアウトして再度ログインします。
- Windows または macOS の場合:
  
  Windows または macOS 向けの Docker Desktop のインストールについては、Docker のドキュメントを参照してください。
```
docker version

...
Server: Docker Desktop
   Engine:
   Version:          24.0.5
...
```
d. Python 3.10
- Linux Ubuntu の場合:
  
  Ubuntu リポジトリからインストールするには sudo apt update && sudo apt install python3 python3-venv を実行します。
- Windows または macOS の場合:
  
  こちらから利用可能なインストーラーを使用してください。
```
python3 --version

Python 3.10.12
```
e. Postman
- Postman から提供されているバイナリを使用してください。
f. extend-helper-cli
- extend-helper-cli から提供されているバイナリを使用してください。
g. TCP フォワーディング機能を持つローカルトンネルサービス。例:
- Ngrok
  
  無料プランの利用には登録が必要です。クイックスタートについては ngrok のドキュメントを参照してください。
- Pinggy
  
  登録なしで無料で試せます。クイックスタートについては pinggy のドキュメントを参照してください。

AGS Admin Portal 環境へのアクセス権。
- ベース URL: <自分の環境のドメイン URL>
  - AGS Public Cloud カスタマーの例: https://spaceshooter.prod.gamingservices.accelbyte.io
  - AGS Private Cloud カスタマーの例: https://dev.customer.accelbyte.io
- まだ持っていない場合は、ゲームネームスペースを作成します。ネームスペース ID をメモしておいてください。
- confidential クライアントタイプで OAuth クライアントを作成します。Client ID と Client Secret を保管してください。

アプリテンプレートをクローンする

C#
Go
Java
Python

git clone https://github.com/AccelByte/matchmaking-function-grpc-plugin-server-csharp.git

git clone https://github.com/AccelByte/matchmaking-function-grpc-plugin-server-go.git

git clone https://github.com/AccelByte/matchmaking-function-grpc-plugin-server-java.git

git clone https://github.com/AccelByte/matchmaking-function-grpc-plugin-server-python.git

Extend アプリをセットアップ、実行、テストする

このセクションでは、Extend アプリのセットアップ、ビルド、実行、テストの方法を説明します。

Extend アプリをセットアップする

このアプリを実行できるようにするには、次のセットアップ手順に従います。

.env.template ファイルの内容をコピーして、docker compose の .env ファイルを作成します。

注記
ホスト OS の環境変数は .env ファイルの変数よりも優先されます。.env ファイル内の変数が正しく反映されていない場合は、同名のホスト OS 環境変数が存在するかどうかを確認してください。詳細については、docker compose の環境変数優先順位に関する Docker のドキュメントを参照してください。
以下のように、必要な環境変数を .env ファイルに入力します。
```
AB_BASE_URL=https://test.accelbyte.io     # AGS 環境のベース URL
AB_CLIENT_ID='xxxxxxxxxx'                 # 前提条件セクションの Client ID
AB_CLIENT_SECRET='xxxxxxxxxx'             # 前提条件セクションの Client Secret
AB_NAMESPACE='xxxxxxxxxx'                 # 前提条件セクションの Namespace ID
PLUGIN_GRPC_SERVER_AUTH_ENABLED=true      # アクセストークン検証を有効または無効にする
```
注記
このアプリでは、PLUGIN_GRPC_SERVER_AUTH_ENABLED はデフォルトで true になっています。false に設定すると、gRPC server は AccelByte Gaming Services のアクセストークンなしで呼び出せるようになります。このオプションは開発目的のみに提供されています。本番環境では gRPC server のアクセストークン検証を有効にすることを推奨します。

Extend アプリをビルドする

このアプリをビルドするには、次のコマンドを実行します。

make build

Extend アプリを実行する

このアプリをコンテナ内で(ビルドして)実行するには、次のコマンドを実行します。

docker compose up --build

Extend アプリをテストする

Extend アプリは、ローカル開発環境または AGS でテストできます。

ローカル開発環境でテストする

important

テストする前に、PLUGIN_GRPC_SERVER_AUTH_ENABLED が false に設定されていることを確認してください。そうしないと、gRPC リクエストが gRPC server によって拒否されます。

このアプリのカスタム関数は、Postman を使用してローカルでテストできます。Postman を使用して Extend アプリをテストするには、次の手順に従います。

次のコマンドを使用してこのアプリを実行します。
```
docker compose up --build
```
Postman で新しい gRPC リクエストを作成し、サーバー URL として localhost:6565 を入力します。詳細については、gRPC サポートに関する Postman のガイドを参照してください。

MakeMatches gRPC ストリームメソッドを選択し、Invoke ボタンをクリックします。これにより、gRPC サーバーへのストリーム接続が開始されます。

続いて、マッチ内のプレイヤー数を指定するパラメーターを送信します。以下のサンプル json をコピーし、Send をクリックします。
```
{
    "parameters": {
        "rules": {
            "json": "{\"shipCountMin\":1, \"shipCountMax\":2}"
        }
    }
}
```
次に、マッチメイキングを開始するためのマッチチケットを送信します。以下のサンプル json をコピーし、Postman のメッセージに置き換えます。Send をクリックします。プレイヤー数が満たされてマッチが作成されるまで、この手順を繰り返します。この例では、2 人のプレイヤーです。
```
{
    "ticket": {
        "players": [
            {
                "player_id": "playerA"
            }
        ]
    }
}
```

成功すると、Postman で以下のようなレスポンス(ダウンストリーム)を受信します。

{
    "match": {
        "tickets": [],
        "teams": [
            {
                "user_ids": [
                    "playerA",
                    "playerB"
                ]
            }
        ],
        "region_preferences": [ // result from the custom matchmaking, should an actual region(s) from the current active AMS (AccelByte Multiplayer Servers) fleet.
            "us-east-2",
            "us-west-2"
        ],
        "match_attributes": null
    }
}

BackfillMatches gRPC ストリームメソッドを選択し、Invoke ボタンをクリックします。これにより、gRPC サーバーへのストリーム接続が開始されます。

続いて、マッチ内のプレイヤー数を指定するパラメーターを送信します。以下のサンプル json をコピーし、Send をクリックします。
```
{
    "parameters": {
        "rules": {
            "json": "{\"shipCountMin\":1, \"shipCountMax\":2}"
        }
    }
}
```
次に、バックフィルマッチメイキングを開始するためのマッチチケットを送信します。以下のサンプル json をコピーし、Postman のメッセージに置き換えます。Send をクリックします。プレイヤー数が満たされてマッチが作成されるまで、この手順を繰り返します。この例では、2 人のプレイヤーです。
```
{
    "ticket": {
        "players": [
            {
                "player_id": "playerA"
            }
        ]
    }
}
```

次に、バックフィルマッチメイキングを開始するためのバックフィルセッションを送信します。以下のサンプル json をコピーし、Postman のメッセージに置き換えます。Send をクリックします。

{
    "backfill_ticket": {
        "CreatedAt": {
            "nanos": 701477177,
            "seconds": "884462191"
        },
        "match_pool": "test_pool",
        "match_session_id": "custom_session_id",
        "partial_match": {
            "backfill": true,
            "client_version": "1.2.3",
            "match_attributes": {
                "fields": {
                    "bigTeam": {
                        "string_value": "A"
                    },
                    "team_mmr": {
                        "number_value": 123
                    }
                }
            },
            "region_preferences": ["us-east-1"],
            "server_name": "custom_server_name",
            "teams": [
                {
                    "user_ids": ["user1"],
                    "parties": [
                        {
                            "party_id": "teamAlpha",
                            "user_ids": [
                                "user1"
                            ]
                        },
                        {
                            "party_id": "",
                            "user_ids": [
                                "user2"
                            ]
                        }
                    ],
                    "team_id": "team1"
                }
            ],
            "tickets": []
        },
        "ticket_id": "backfill_ticket_id"
    }
}

成功すると、Postman で以下のようなレスポンス(ダウンストリーム)を受信します。

{
    "backfill_proposal": {
        "added_tickets": [
            {
                "players": [
                    {
                        "player_id": "playerA",
                        "attributes": {
                            "fields": {}
                        }
                    }
                ],
                "excluded_sessions": [],
                "latencies": {},
                "ticket_id": "",
                "match_pool": "",
                "CreatedAt": {
                    "seconds": "0",
                    "nanos": 0
                },
                "ticket_attributes": {},
                "party_session_id": "",
                "namespace": ""
            }
        ],
        "proposed_teams": [
            {
                "user_ids": [
                    "user1"
                ],
                "parties": [
                    {
                        "user_ids": [
                            "user1"
                        ],
                        "party_id": "teamAlpha"
                    },
                    {
                        "user_ids": [
                            "user2"
                        ],
                        "party_id": ""
                    }
                ],
                "team_id": "team1"
            },
            {
                "user_ids": [
                    "playerA"
                ],
                "parties": [
                    {
                        "user_ids": [
                            "playerA"
                        ],
                        "party_id": ""
                    }
                ],
                "team_id": "536aa1d855734bc191831158e8a4aa33"
            }
        ],
        "backfill_ticket_id": "backfill_ticket_id",
        "CreatedAt": {
            "seconds": "-62135596800",
            "nanos": 0
        },
        "proposal_id": "",
        "match_pool": "test_pool",
        "match_session_id": "custom_session_id"
    }
}

Make Matches の高度な設定と結果

より複雑なマッチメイキングのシナリオでは、高度なチケット属性やプレイヤー属性を使用できます。このセクションでは、包括的なチケット設定の作成方法と、期待できる詳細なマッチ結果について説明します。

高度なチケット設定

高度なチケット設定を使用すると、豊富なメタデータ、プレイヤー属性、マッチ固有の情報を含めることができます。

{
    "ticket": {
        "CreatedAt": {
            "nanos": 446183572,
            "seconds": "3"
        },
        "excluded_sessions": [
            "previousSessionID"
        ],
        "latencies": {
            "us-east-2": 50,
            "us-east-1": 10
        },
        "match_pool": "test_pool",
        "namespace": "laboris",
        "party_session_id": "party_id",
        "players": [
            {
                "player_id": "playerA",
                "attributes": {
                    "fields": {
                        "weapon": {
                            "string_value": "sword"
                        },
                        "armor": {
                            "string_value": "steel"
                        },
                        "mmr": {
                            "number_value": 111
                        }
                    }
                }
            }
        ],
        "ticket_attributes": {
            "fields": {
                "bigTeam": {
                    "string_value": "A"
                },
                "team_mmr": {
                    "number_value": 123
                }
            }
        },
        "ticket_id": "ticket_id_1234"
    }
}

この高度な設定には、以下が含まれます。

プレイヤー属性: 武器、防具、MMR (Matchmaking Rating) などのプレイヤー固有のカスタムデータ
チケット属性: チーム割り当てやチーム MMR などのマッチレベルの属性
レイテンシー情報: 最適なサーバー選択のためのリージョン別レイテンシーデータ
メタデータ: 作成タイムスタンプ、ネームスペース、パーティーセッション情報

高度なマッチ結果

高度なチケット設定を使用すると、包括的なチケット情報、チーム割り当て、マッチ属性を含む、より詳細なマッチ結果を受け取ります。

{
    "match": {
        "tickets": [
            {
                "players": [
                    {
                        "player_id": "playerA",
                        "attributes": {
                            "fields": {
                                "mmr": {
                                    "number_value": 111
                                },
                                "weapon": {
                                    "string_value": "sword"
                                },
                                "armor": {
                                    "string_value": "steel"
                                }
                            }
                        }
                    }
                ],
                "excluded_sessions": [
                    "previousSessionID"
                ],
                "latencies": {
                    "us-east-2": "50",
                    "us-east-1": "10"
                },
                "ticket_id": "ticket_id_1234",
                "match_pool": "test_pool",
                "CreatedAt": {
                    "seconds": "3",
                    "nanos": 446183572
                },
                "ticket_attributes": {
                    "fields": {
                        "bigTeam": {
                            "string_value": "A"
                        },
                        "team_mmr": {
                            "number_value": 123
                        }
                    }
                },
                "party_session_id": "party_id",
                "namespace": "laboris"
            },
            {
                "players": [
                    {
                        "player_id": "playerA",
                        "attributes": {
                            "fields": {
                                "armor": {
                                    "string_value": "steel"
                                },
                                "mmr": {
                                    "number_value": 111
                                },
                                "weapon": {
                                    "string_value": "sword"
                                }
                            }
                        }
                    }
                ],
                "excluded_sessions": [
                    "previousSessionID"
                ],
                "latencies": {
                    "us-east-2": "50",
                    "us-east-1": "10"
                },
                "ticket_id": "ticket_id_1234",
                "match_pool": "test_pool",
                "CreatedAt": {
                    "seconds": "3",
                    "nanos": 446183572
                },
                "ticket_attributes": {
                    "fields": {
                        "bigTeam": {
                            "string_value": "A"
                        },
                        "team_mmr": {
                            "number_value": 123
                        }
                    }
                },
                "party_session_id": "party_id",
                "namespace": "laboris"
            }
        ],
        "teams": [
            {
                "user_ids": [
                    "playerA",
                    "playerA"
                ],
                "parties": [],
                "team_id": "e54edf33fa174ccc8a1162510087197c"
            }
        ],
        "region_preferences": [
            "us-east-2",
            "us-west-2"
        ],
        "match_attributes": {
            "fields": {
                "assignment": {
                    "struct_value": {
                        "fields": {
                            "small-team-1": {
                                "list_value": {
                                    "values": [
                                        {
                                            "string_value": "e54edf33fa174ccc8a1162510087197c"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                }
            }
        },
        "backfill": false,
        "server_name": "",
        "client_version": "",
        "server_pool": {
            "claim_keys": [],
            "server_provider": "",
            "deployment": ""
        }
    }
}

この高度なマッチ結果には、以下が含まれます。

詳細なチケット: すべてのプレイヤー属性、レイテンシー、メタデータを含む完全なチケット情報
チーム割り当て: チーム ID とパーティーの詳細を含む構造化されたチーム情報
マッチ属性: チーム割り当てや設定などのカスタムマッチレベルデータ
サーバー情報: サーバープールの詳細、バックフィルステータス、デプロイメント情報

Backfill Matches の高度な設定と結果

より複雑なマッチメイキングのシナリオでは、高度なチケット属性や高度なセッション属性を使用できます。このセクションでは、包括的なチケット設定の作成方法と、期待できる詳細なバックフィルマッチ結果について説明します。

高度なチケット設定

高度なチケット設定を使用すると、豊富なメタデータ、プレイヤー属性、マッチ固有の情報を含めることができます。

{
    "ticket": {
        "CreatedAt": {
            "nanos": 446183572,
            "seconds": "3"
        },
        "excluded_sessions": [
            "previousSessionID"
        ],
        "latencies": {
            "us-east-2": 50,
            "us-east-1": 10
        },
        "match_pool": "test_pool",
        "namespace": "laboris",
        "party_session_id": "party_id",
        "players": [
            {
                "player_id": "playerA",
                "attributes": {
                    "fields": {
                        "weapon": {
                            "string_value": "sword"
                        },
                        "armor": {
                            "string_value": "steel"
                        },
                        "mmr": {
                            "number_value": 111
                        }
                    }
                }
            }
        ],
        "ticket_attributes": {
            "fields": {
                "bigTeam": {
                    "string_value": "A"
                },
                "team_mmr": {
                    "number_value": 123
                }
            }
        },
        "ticket_id": "ticket_id_1234"
    }
}

この高度な設定には、以下が含まれます。

プレイヤー属性: 武器、防具、MMR (Matchmaking Rating) などのプレイヤー固有のカスタムデータ
チケット属性: チーム割り当てやチーム MMR などのマッチレベルの属性
レイテンシー情報: 最適なサーバー選択のためのリージョン別レイテンシーデータ
メタデータ: 作成タイムスタンプ、ネームスペース、パーティーセッション情報

高度なバックフィルセッション

高度なバックフィルセッション設定を使用すると、豊富な既存セッションのメタデータ、属性、マッチ固有の情報を含めることができます。

{
    "backfill_ticket": {
        "CreatedAt": {
            "nanos": 701477177,
            "seconds": "884462191"
        },
        "match_pool": "test_pool",
        "match_session_id": "custom_session_id",
        "partial_match": {
            "backfill": true,
            "client_version": "1.2.3",
            "match_attributes": {
                "fields": {
                    "bigTeam": {
                        "string_value": "A"
                    },
                    "team_mmr": {
                        "number_value": 123
                    }
                }
            },
            "region_preferences": [
                "us-east-1"
            ],
            "server_name": "custom_server_name",
            "teams": [
                {
                    "user_ids": [
                        "user1"
                    ],
                    "parties": [
                        {
                            "party_id": "teamAlpha",
                            "user_ids": [
                                "user1"
                            ]
                        },
                        {
                            "party_id": "",
                            "user_ids": [
                                "user2"
                            ]
                        }
                    ],
                    "team_id": "team1"
                }
            ],
            "tickets": []
        },
        "ticket_id": "backfill_ticket_id"
    }
}

この高度なバックフィルセッション設定には、以下のフィールドが含まれます。

backfill_ticket: バックフィルセッションを表すメインオブジェクト。
- CreatedAt: バックフィルチケットが作成された時刻のタイムスタンプ。
- match_pool: マッチプール名。
- match_session_id: マッチセッション識別子。
- partial_match: 現在の部分マッチ/セッションの詳細。以下を含みます。
  - backfill: これがバックフィルセッションであるかどうかを示すブール値。
  - client_version: クライアントのバージョン。
  - match_attributes: マッチのカスタム属性(例: bigTeam、team_mmr)。
  - region_preferences: マッチの優先リージョンの配列。
  - server_name: セッションを処理するサーバーの名前。
  - teams: チームオブジェクトの配列。それぞれ以下を含みます。
    - user_ids: チーム内のユーザー ID の配列。
    - parties: パーティーオブジェクトの配列。それぞれ以下を含みます。
      - party_id: パーティー識別子(空の場合もあります)。
      - user_ids: パーティー内のユーザー ID。
    - team_id: チームの一意の識別子。
  - tickets: 現在セッション内にあるチケットの配列(空の場合もあります)。
- ticket_id: バックフィルチケットの一意の識別子。

このスキーマにより、高度なバックフィルシナリオのための詳細なセッション、チーム、マッチ属性を指定できます。

高度なバックフィル提案結果

高度なチケットおよびバックフィルセッション設定を使用すると、詳細なバックフィル提案結果を受け取ります。この結果は、追加されたチケット、チーム割り当て、および高度なバックフィルシナリオに関連するすべてのメタデータを包括的に示します。

{
    "backfill_proposal": {
        "added_tickets": [
            {
                "players": [
                    {
                        "player_id": "playerA",
                        "attributes": {
                            "fields": {
                                "mmr": {
                                    "number_value": 111
                                },
                                "weapon": {
                                    "string_value": "sword"
                                },
                                "armor": {
                                    "string_value": "steel"
                                }
                            }
                        }
                    }
                ],
                "excluded_sessions": [
                    "previousSessionID"
                ],
                "latencies": {
                    "us-east-1": "10",
                    "us-east-2": "50"
                },
                "ticket_id": "ticket_id_1234",
                "match_pool": "test_pool",
                "CreatedAt": {
                    "seconds": "3",
                    "nanos": 446183572
                },
                "ticket_attributes": {
                    "fields": {
                        "team_mmr": {
                            "number_value": 123
                        },
                        "bigTeam": {
                            "string_value": "A"
                        }
                    }
                },
                "party_session_id": "party_id",
                "namespace": "laboris"
            }
        ],
        "proposed_teams": [
            {
                "user_ids": [
                    "user1"
                ],
                "parties": [
                    {
                        "user_ids": [
                            "user1"
                        ],
                        "party_id": "teamAlpha"
                    },
                    {
                        "user_ids": [
                            "user2"
                        ],
                        "party_id": ""
                    }
                ],
                "team_id": "team1"
            },
            {
                "user_ids": [
                    "playerA"
                ],
                "parties": [
                    {
                        "user_ids": [
                            "playerA"
                        ],
                        "party_id": ""
                    }
                ],
                "team_id": "3fb8e77febb84b66a79050e588cf8af7"
            }
        ],
        "backfill_ticket_id": "backfill_ticket_id",
        "CreatedAt": {
            "seconds": "-62135596800",
            "nanos": 0
        },
        "proposal_id": "8e8418a2c08d4107b0df2f93414d5197",
        "match_pool": "test_pool",
        "match_session_id": "custom_session_id",
        "attributes": {
            "fields": {
                "bigTeam": {
                    "string_value": "A"
                },
                "team_mmr": {
                    "number_value": 123
                },
                "generatedID": {
                    "string_value": "1b0e5580b3c3479fa8e270019bd5a345"
                }
            }
        }
    }
}

この高度なバックフィル提案マッチ結果には、以下が含まれます。

backfill_proposal: 提案の詳細を含むメインオブジェクト。
- added_tickets: セッションに追加されたチケットのリスト。各チケットには以下が含まれます。
  - players: プレイヤーオブジェクトの配列。それぞれ以下を含みます。
    - player_id: プレイヤーの一意の識別子。
    - attributes: カスタムプレイヤー属性(例: mmr、weapon、armor)。
  - excluded_sessions: ユーザーがマッチングを避けたい以前のセッション。
  - latencies: チケットのリージョン別レイテンシー情報。
  - ticket_id: チケットの一意の識別子。
  - match_pool: マッチプール名。
  - CreatedAt: チケットが作成された時刻のタイムスタンプ。
  - ticket_attributes: チケットのカスタム属性(例: team_mmr、bigTeam)。
  - party_session_id: パーティーセッション識別子。
  - namespace: チケットのネームスペース。
- proposed_teams: バックフィルで提案されたチームのリスト。各チームには以下が含まれます。
  - user_ids: チーム内のユーザー ID の配列。
  - parties: パーティーオブジェクトの配列。それぞれ以下を含みます。
    - user_ids: パーティー内のユーザー ID。
    - party_id: パーティー識別子(空の場合もあります)。
  - team_id: チームの一意の識別子。
- backfill_ticket_id: バックフィルチケットの一意の識別子。
- CreatedAt: 提案が作成された時刻のタイムスタンプ。
- proposal_id: 提案の一意の識別子。
- match_pool: マッチプール名。
- match_session_id: マッチセッション識別子。
- attributes: 提案の追加カスタム属性(例: bigTeam、team_mmr、generatedID)。

AGS でテストする

ローカルで実行しているアプリを AGS でテストするには、gRPC server をインターネットに接続する必要があります。パブリック IP を必要とせずにこれを行うには、ローカルトンネルサービスを使用できます。

次のコマンドを使用してこのアプリを実行します。
```
docker compose up --build
```
ローカル開発環境の gRPC server TCP ポート 6565 をインターネットに公開します。最も簡単な方法は、ローカルトンネルサービスプロバイダーを使用することです。
- ngrok にサインインして、ngrok ダッシュボードから authtoken を取得し、ローカル環境に設定します。そして、gRPC server を公開するには、次のコマンドを使用します。
```
ngrok tcp 6565
```
- または、代わりに pinggy を使用し、ssh コマンドラインのみでシンプルなトンネルを設定することもできます。その場合、gRPC server を公開するには次のコマンドを使用します。
```
ssh -p 443 -o StrictHostKeyChecking=no -o ServerAliveInterval=30 -R0:127.0.0.1:6565 tcp@a.pinggy.io
```
トンネルのフォワーディング URL、例: http://0.tcp.ap.ngrok.io:xxxxx や tcp://xxxxx-xxx-xxx-xxx-xxx.a.free.pinggy.link:xxxxx をメモしておいてください。

備考
gRPC サーバーポート (TCP) をインターネットに公開するために、他のローカルトンネルサービスや異なる方法を使用することもできます。
Admin Portal で、設定に適したネームスペースに移動し、以下を実行します。
1. サイドバーメニューで、Multiplayer > Matchmaking > Customization に移動します。
2. Register Function ボタンをクリックします。
3. 表示されたポップアップウィンドウで、関数の名前を入力します。次に、Locally hosted for testing purpose オプションを選択し、手順 3 のローカルトンネルフォワーディング URL を入力します。
4. Create をクリックします。
5. Multiplayer > Matchmaking > Matchmaking Configuration に移動し、Match Pools タブを選択します。既存のマッチプール設定を作成または編集します。Customization セクションで、カスタマイゼーション機能を有効にし、ドロップダウンメニューから登録したMatch Function アプリを選択します。
備考
マッチメイキング関数(Stat codes、Enrichment、Validation、Backfill Matches、Make Matches)ごとに、複数の Extend Override を登録できます。デフォルトのカスタム関数と特定のカスタム関数が同じマッチプールに登録されている場合、特定のカスタム関数がデフォルトのカスタム関数より優先されます。
以下の権限を含む confidential クライアントタイプで OAuth クライアントを作成します。
- AGS Private Cloud カスタマーの場合:
  - NAMESPACE:{namespace}:MATCHMAKING:RULES [CREATE,READ,UPDATE,DELETE]
  - NAMESPACE:{namespace}:MATCHMAKING:FUNCTIONS [CREATE,READ,UPDATE,DELETE]
  - NAMESPACE:{namespace}:MATCHMAKING:POOL [CREATE,READ,UPDATE,DELETE]
  - NAMESPACE:{namespace}:MATCHMAKING:TICKET [CREATE,READ,UPDATE,DELETE]
  - ADMIN:NAMESPACE:{namespace}:INFORMATION:USER:* [CREATE,READ,UPDATE,DELETE]
  - ADMIN:NAMESPACE:{namespace}:SESSION:CONFIGURATION:* [CREATE,READ,UPDATE,DELETE]
- AGS Public Cloud カスタマーの場合:
  - Matchmaking > Rule Sets (Read、Create、Update、Delete)
  - Matchmaking > Match Functions (Read、Create、Update、Delete)
  - Matchmaking > Match Pools (Read、Create、Update、Delete)
  - Matchmaking > Match Tickets (Read、Create、Update、Delete)
  - IAM > Users (Read、Create、Update、Delete)
  - Session > Configuration Template (Read、Create、Update、Delete)
important
- Client ID と Client Secret のコピーを保管してください。
- この手順で作成した OAuth クライアントは、前提条件セクションで述べたものとは異なります。これは次の手順の CLI デモアプリに必要です。
demo フォルダー内の Postman コレクションを Postman にインポートして、マッチメイキングフローをシミュレートします。Postman コレクションの概要にある手順に従い、前の手順で得た Client ID と Client Secret を使用して環境を設定します。マッチメイキングフローの実行中に、Extend アプリのコンソールログを監視します。マッチチケットを作成すると gRPC サーバーメソッドがトリガーされ、プレイヤーがペアにグループ化されるはずです。

AGS にデプロイする

AGS で Extend アプリをデプロイするには、Admin Portal で次の手順を実行します。

Extend アプリを作成する。
Extend アプリをアップロードする。
Extend アプリを設定する。
Extend アプリをデプロイする。
AGS に Extend アプリを使用させる。

Extend アプリを作成する

AGS Admin Portal で、Extend Override アプリを作成したいネームスペースに移動します。
サイドバーメニューの ADD-ONS で、Extend > Override に移動します。
Overridable Features ページで、+ Create New ボタンをクリックします。
Create App フォームで、Extend アプリの名前と説明(オプション)を入力します。
Create をクリックします。新しい Extend アプリが Overridable Features アプリリストに追加されます。

Extend アプリをアップロードする

extend-helper-cli 用の IAM クライアントを設定します。クライアントタイプ confidential で IAM クライアントを作成し、以下に示す必要な権限を割り当てます。Client ID と Client Secret のコピーを保管してください。
- AGS Private Cloud カスタマーの場合:
  - ADMIN:NAMESPACE:{namespace}:EXTEND:REPOCREDENTIALS [READ]
  - ADMIN:NAMESPACE:{namespace}:EXTEND:APP [READ]
- AGS Public Cloud カスタマーの場合:
  - Extend > Extend app image repository access (Read)
  - Extend > App (Read)

必要な環境変数をエクスポートし、extend-helper-cli を使用して Extend アプリのコンテナイメージをビルドして AGS にアップロードします。

<project-dir> が Extend アプリのプロジェクトディレクトリを指していることを確認してください
<namespace> と <app-name> の値は、Extend アプリの App Detail ページで確認できます
v0.0.1 などの適切なイメージタグを使用してください

Linux
Windows (WSL2)
macOS

# AGS 環境のベース URL(例: https://spaceshooter.prod.gamingservices.accelbyte.io、https://dev.accelbyte.io など)
export AB_BASE_URL='https://xxxxxxxxxx'
# extend-helper-cli 用 OAuth クライアントの Client ID(手順 1 より)
export AB_CLIENT_ID='xxxxxxxxxx'     
# extend-helper-cli 用 OAuth クライアントの Client Secret(手順 1 より)
export AB_CLIENT_SECRET='xxxxxxxxxx'

./extend-helper-cli-linux_amd64 image-upload --login --work-dir <project-dir> --namespace <namespace> --app <app-name> --image-tag v0.0.1   

# AGS 環境のベース URL(例: https://spaceshooter.prod.gamingservices.accelbyte.io、https://dev.accelbyte.io など)
export AB_BASE_URL='https://xxxxxxxxxx'
# extend-helper-cli 用 OAuth クライアントの Client ID(手順 1 より)
export AB_CLIENT_ID='xxxxxxxxxx'     
# extend-helper-cli 用 OAuth クライアントの Client Secret(手順 1 より)
export AB_CLIENT_SECRET='xxxxxxxxxx'

./extend-helper-cli-linux_amd64 image-upload --login --work-dir <project-dir> --namespace <namespace> --app <app-name> --image-tag v0.0.1  

# AGS 環境のベース URL(例: https://spaceshooter.prod.gamingservices.accelbyte.io、https://dev.accelbyte.io など)
export AB_BASE_URL='https://xxxxxxxxxx'
# extend-helper-cli 用 OAuth クライアントの Client ID(手順 1 より)
export AB_CLIENT_ID='xxxxxxxxxx'     
# extend-helper-cli 用 OAuth クライアントの Client Secret(手順 1 より)
export AB_CLIENT_SECRET='xxxxxxxxxx'

./extend-helper-cli-darwin_amd64 image-upload --login --work-dir <project-dir> --namespace <namespace> --app <app-name> --image-tag v0.0.1   

important

上記のコマンドは、Extend アプリのプロジェクトとは別のターミナルおよび別の作業ディレクトリから実行することを推奨します。これにより、extend-helper-cli が Extend アプリ用の環境変数を誤って使用することを防げます。

以下のエラーが発生した場合は、トラブルシューティング: Docker ログインの失敗を参照して解決してください。

Error saving credentials: error storing credentials - err: exit status 1, out: `error storing credentials - err: exit status 1, out: `The stub received bad data.`

イメージが正常にアップロードされると、Image Version History ページにバージョン v0.0.1 のイメージが表示されます。

AGS Admin Portal 内のイメージ履歴

Extend アプリを設定する

アップロードした Extend アプリをデプロイする前に、Extend アプリに必要な環境変数を設定する必要があります。アプリの詳細ページで、Extend アプリをローカルで実行およびテストするときに使用したものと同じ値で、以下の環境変数を設定します。

AB_CLIENT_ID
AB_CLIENT_SECRET

warning

Extend Override アプリがリリース v2024.02.13 より前のテンプレートに基づいている場合は、PLUGIN_GRPC_SERVER_AUTH_ENABLED 環境変数を必ず true に設定してください。設定しない場合、Extend アプリのアクセストークン検証が無効になり、有効なアクセストークンなしで Extend アプリにアクセスされる可能性があります。

リリース v2024.02.13 以降、Extend Override アプリテンプレートの PLUGIN_GRPC_SERVER_AUTH_ENABLED はデフォルトで true に設定されています。アクセストークン検証は、PLUGIN_GRPC_SERVER_AUTH_ENABLED が明示的に false に設定された場合にのみ無効にできます。これに合わせて、Admin Portal を通じて作成されるすべての新しい Extend アプリには、デフォルトで PLUGIN_GRPC_SERVER_AUTH_ENABLED 環境変数が設定されなくなりました。以前は、Admin Portal を通じて作成されるすべての新しい Extend アプリに PLUGIN_GRPC_SERVER_AUTH_ENABLED=false が追加されていました。

Extend アプリをデプロイする

Extend アプリをデプロイするには、Deploy Latest Image をクリックします。アプリのステータスが RUNNING に更新されるまで待ちます。これは、Extend アプリが正常にデプロイされたことを示します。

AGS に Extend アプリを使用させる

AGS Admin Portal に移動し、カスタム関数を作成する際に使用したいネームスペースを使用します。左側のパネルで、Game Management をクリックし、次に New Matchmaking、そして Custom Function をクリックします。次に、Register Function ボタンをクリックし、AccelByte Hosted を選択します。作成したExtend App 名を選択し、Save をクリックします。

AccelByte ホスト型カスタム設定

次に、使用したいマッチプール設定にマッチ関数を設定します。これを行うには、Game Management をクリックし、次に New Matchmaking、そして Matchmaking Configurations をクリックします。Match Pools タブをクリックし、マッチプールを新規作成するか既存のものを編集します。下部までスクロールし、ドロップダウンメニューからCustom Function を選択します。

カスタム関数の設定

次のステップ

Extend Override アプリテンプレートを変更して、独自のカスタムロジックを実装してください。詳細については、こちらを参照してください。

Overview​

前提条件​

アプリテンプレートをクローンする​

Extend アプリをセットアップ、実行、テストする​

Extend アプリをセットアップする​

Extend アプリをビルドする​

Extend アプリを実行する​

Extend アプリをテストする​

ローカル開発環境でテストする​

Make Matches の高度な設定と結果​

高度なチケット設定​

高度なマッチ結果​

Backfill Matches の高度な設定と結果​

高度なチケット設定​

高度なバックフィルセッション​

高度なバックフィル提案結果​

AGS でテストする​

AGS にデプロイする​

Extend アプリを作成する​

Extend アプリをアップロードする​

Extend アプリを設定する​

Extend アプリをデプロイする​

AGS に Extend アプリを使用させる​

次のステップ​

Overview

前提条件

アプリテンプレートをクローンする

Extend アプリをセットアップ、実行、テストする

Extend アプリをセットアップする

Extend アプリをビルドする

Extend アプリを実行する

Extend アプリをテストする

ローカル開発環境でテストする

Make Matches の高度な設定と結果

高度なチケット設定

高度なマッチ結果

Backfill Matches の高度な設定と結果

高度なチケット設定

高度なバックフィルセッション

高度なバックフィル提案結果

AGS でテストする

AGS にデプロイする

Extend アプリを作成する

Extend アプリをアップロードする

Extend アプリを設定する

Extend アプリをデプロイする

AGS に Extend アプリを使用させる

次のステップ