ベータ版 API 関連ドキュメント

note

Unity マッチメイキングは現在、クローズドベータテスト中です。このサービスの詳細については、マッチメイキングに関するドキュメントを参照してください。チュートリアル、FAQ、API 情報が含まれます。

Multiplay を使用してマルチプレイヤーゲームをホストすることに興味をお持ちですか？詳細についてはお問い合わせください。

パッケージ

Unity を使用している場合、クライアント SDK パッケージの詳細については、クイックスタートガイドを参照してください。この情報は、以下のセクションで詳しく説明しているチケット管理フローを簡素化するのに役立ちます。

承認

呼び出す API エンドポイントに応じて、3 種類の承認プロセスをすべて JWT トークン形式で利用できます。

JWT ベースの認証と承認の詳細については、JWT ウェブサイトを参照してください。

開発者

設定ファイルや関数の API は、そのプロジェクトの管理者による承認によって保護されています。設定ファイルや関数を管理するには、呼び出し元にそのプロジェクトに対する Unity 組織のマネージャーまたはオーナーのパーミッションのいずれかが必要です（詳細については、組織の役割に関する Unity ドキュメントを参照してください）。コマンドラインインターフェース（CLI）を使用している場合、このプロンプトが表示されユーザーの代わりに処理されます。

Authorization: Bearer JWT_FROM_UNITY_LOGIN

サーバー

バックフィルエンドポイントは、ある割り当てが発生するときに専用ゲームサーバー（DGS）がその設定内で受け取る JWT によって保護されます。JWT はリクエストの承認ヘッダーに次の形式で渡される必要があります。

Authorization: Bearer JWT_FROM_DGS_CONFIG

プレイヤー

チケットエンドポイントは、プレイヤー ID トークンによって保護されます。これも JWT 形式が使用されています。プレイヤー ID はホワイトラベルの ID トークン交換プロバイダーで、マッチメイキングを呼び出すために必要です。これは標準準拠であり、デフォルトで大多数の ID ソリューションと互換性があります。クライアントフロー、クライアント ID、補足ドキュメントは、Unity プレイヤー ID 関連ドキュメントに用意されています。

Authorization: Bearer JWT_FROM_PLAYER_IDENTITY_SERVICE

ベータ版 API

https://cloud.connected.unity3d.com/{unityProjectId}/matchmaking/api/v1

レート制限

レート制限は、一部のマッチメイキング API で使用されます。これらの制限は、高負荷な状況下でマッチメーカーの安定性を維持するのに役立ちます。制限は、通常の使用パターンで問題が生じないような高さに設定されます。マッチメーカーにレート制限がかけられている場合は、API は 429 ステータスコードを返します。詳細については、RFC 6585 に関する IETF ドキュメントを参照してください。

レート制限ヘッダー（retry-after など）を提供しない 429 ステータスコードによるレスポンスについては、次の指数バックオフポリシーを使用することをお勧めします。

• Y 秒後に再試行（Y = Jitter + 2^Attempt）
  • ジッターは、リクエストごとに -Attempt と Attempt の間のランダム値にする
• 試行回数は最大 5 回

チケット

チケットは 1 人以上のプレイヤー向けのマッチメイキングリクエストです。プレイヤーのマッチメイキングの意向と、マッチ関数で必要とされるその他のプレイヤーデータが含まれます。

チケットにはプレイヤーの承認が必要です。

チケットリクエストは、レート制限の対象にもなります。レート制限では、プレイヤーがリクエストを行う場合や、プレイヤーの代わりにリクエストを実行するプロキシサーバーを開発者が作成する場合などのシナリオが考慮に入れられます。前者の場合は、異なるクライアントから多数のリクエストが送られ、後者の場合は、同じクライアントから多数のリクエストが送られます。レート制限は現在のチケットプールサイズに基づいて適用されます。つまり、チケットのプールが一定のしきい値に達すると、プールをより効果的に開放するために、エンドポイントでチケット作成リクエストが拒否されるようになります。

POST /tickets
マッチメイキングチケットを作成し、マッチメイキングを実質的に開始します。
ヘッダー：x-on-behalf-of 値：player-id。プレイヤー認証 API ドキュメントを参照してください
本文：CreateTicket
レスポンス：201 (CreateTicketResponse), 400

GET /tickets?id={ticketId}
マッチメイキングチケットを取得します。割り当てが null 以外になるまで継続的にポーリングします。
レスポンス：200 (TicketResponse)

DELETE /tickets?id={ticketId}
マッチメイキングチケットを削除し、マッチメイキングを実質的に終了します。
レスポンス：200, 404 [not found]

設定ファイル

マッチメイキング設定は、マッチメイキング関数を実行するための命令です。実行する関数、使用する Multiplay サーバープロフィール、複数のモード、プレイリスト、マッチ設定の実行に必要なその他マッチ固有のパラメーターを指定します。

マッチメイキング設定には開発者の承認が必要です。

設定リクエストはレート制限の対象にもなります。

POST /configs
新しいマッチメイキング設定を作成します。設定が存在すると、マッチメイキングサイクルでそれが即座に有効になります。
本文：Config
レスポンス：200, 400 (ValidationErrorResponse)

note

POST は設定の新しい GUID 識別子を生成します。put コマンドを使用して設定名を直接制御することを検討してください。

GET /configs/{configId}
既存のマッチメイキング設定を取得します。
レスポンス：200 (Config)

PUT /configs/{configId}
configId によって指定された設定を作成または更新します。configId はほとんどのファイルシステムの命名制約に準拠しています。
本文：Config
レスポンス：200, 400 (ValidationErrorResponse), 409

DELETE /configs/{configId} 既存のマッチメイキング設定を削除します。設定を削除すると、マッチメイキングサイクルでそれが即座に無効になります。 レスポンス：204 [deleted]

関数

マッチ関数は IMatchFunction の実装です。これらの関数は、マッチメイキングサイクル中に呼び出されるマッチメイキングロジックのアップロードおよび展開対象部分です。

マッチ関数には開発者の承認が必要です。

関数リクエストはレート制限の対象にもなります。

GET /functions
現在展開されている関数に関する詳細の一覧を表示します。
レスポンス：200 (FunctionList)

PUT /functions/{function-name}?implementation={impl-name}
{function-name} という名前のマッチ関数を作成または更新します。
本文：
レスポンス：200, 400

重要

既存の関数を更新すると、新しい関数がスピンアップする間、現在のサイクルでマッチメイキングが数秒にわたって一時停止する場合があります。

マッチ関数の数は 20 までに制限されています。この制限値に達した場合、既存の関数を削除してからでないと新しい関数の追加を試行できなくなります。

GET /functions/{function-name}
{function-name} という名前の関数に関する情報を取得します。
レスポンス：200 (Function), 400, 404

GET /functions/{function-name}/log?seconds=1800
現在展開されており実行中の {function-name} という名前の関数に関するログを取得します。ログでカバーされる時間の長さは、クエリパラメーター seconds を使用して設定できます（デフォルトでは 1800 秒に設定されます）。
レスポンス：200 (FunctionLogs), 400, 404

DELETE /functions/{function-name}
関数名 {function-name} を削除します。このアクションはべき等です。
レスポンス：204

POST /functions/actions/restart
一連の関数の再起動をスケジュールします。
本文：200 (FunctionNameList)
レスポンス：200 (FunctionDeployResult), 404

バックフィル (非推奨。代わりに backfill v2 を使用してください)

バックフィルは、バックフィル可能な特殊な関数の実行に使用されます。関数を新しいプレイヤーの基準、既存のプレイヤーに関する詳細、ゲームに関する情報とともに指定することで、専用ゲームサーバー（DGS）がマッチメイキングチケットのプールにリーチして、継続中のゲームにプレイヤーをプルできます。

バックフィルにはサーバーの承認が必要です。

POST /backfill
バックフィルリクエストを、バックフィル可能なマッチ関数で必要とされるパラメーターとともに送信します。バックフィルリクエストの結果で応答します。
本文：BackfillConfig
レスポンス：200 (BackfillResponse), 400

バックフィル V2

POST /api/v2/backfill/{id}/approvals
バックフィルチケットを承認します。BackfillTicket を返します。バックフィルチケットを承認すると、そのバックフィルチケットに関連付けられたすべての申請済みチケットが割り当て可能になります。バックフィル経由でプレイヤーを取得するには、これを定期的に呼び出す必要があります。バックフィルの進行中にこれを呼び出す頻度は、最短でも 1 秒間隔にすることをお勧めします。

レスポンス：200 (BackfillTicket), 404

注：バックフィルに関連付けられた申請済みチケットは、承認されなかった場合、5 秒後に却下されます。却下されたチケットは、マッチ関数によって照会可能なチケットのプールに戻されます。

POST /api/v2/backfill
バックフィルチケットを作成します。CreateBackfillTicketResponse でラップされたバックフィルチケット ID を返します。これはバックフィルの開始時に呼び出す必要があります。

本文：CreateBackfillTicketRequest
レスポンス：201 (CreateBackfillTicketResponse)

PUT /api/v2/backfill/{id}
バックフィルチケットを更新します。バックフィルチケットを更新すると、そのバックフィルチケットに関連付けられたすべての申請済みチケットが却下されます。却下されたチケットは、マッチ関数によって照会可能なチケットのプールに戻されます。これは、サーバーステートの変更時（ユーザーがサーバーを退出した際や、マッチメーカーの関与なくサーバーに参加した際など）に呼び出される必要があります。これにより、最新のサーバーステートが反映されます。

注：バックフィルチケットを更新した関数は、その更新を自身の観測したバージョンにバインドします。このメソッドを呼び出すと、多くの場合、マッチ関数からの保留中の更新が失敗します。詳細については、「DGS によるバックフィルチケットの更新頻度が高い」を参照してください。

本文：BackfillTicket
レスポンス：200

DELETE /api/v2/backfill/{id} バックフィルチケットを削除します。バックフィルチケットを削除すると、そのバックフィルチケットに関連付けられたすべての申請済みチケットが却下されます。却下されたチケットは、マッチ関数によって照会可能なチケットのプールに戻されます。これはバックフィルの終了時に呼び出す必要があります。

レスポンス：204

コントラクト

CreateTicket

{

"attributes": {

"mode": 1,

"playerCount": 2,

"teamSkill": 15.34

},

"properties": {

"qosConnector": "...",

"partyInfo": "eyJwbGF5ZXJzSW5QYXJ0eSI6IHsidXNlcjEiOiB7ImtleXMiOiA0fSwgInVzZXIyIjogeyJrZXlzIjogMX19LCAid2luU3RyZWFrIjogNH0="

}

}

フィールド	説明	型
attributes	これらのインデックス可能なフィールドは、マッチメイキングプールからチケットを取得する目的で、マッチ関数で照会可能なフィールドとして利用できます。このフィールドは省略可能です。	Dictionary<string, double>
properties	properties 内の値は、マッチメイキングロジックでデシリアライズして使用するために、マッチ関数で利用できます。前述の例では、partyInfo に次のカスタム Base64 エンコード文字列が含まれます。 {"playersInParty": {"user1": {"keys": 4}, "user2": {"keys": 1}}, "winStreak": 4} このフィールドは省略可能です。	Dictionary<string, byte[]>

CreateTicketResponse

{

"id": "bb7b0581-ebdb-4a6e-9818-c56d4d546152"

}

フィールド	説明	型
id	新しいチケットの識別子。注：この識別子が GUID であることは保証されません。	string
status	[非推奨] - このフィールドは、元は検証エラーやサービス内部の問題に関するレスポンスの詳細を提供することを意図した、古い機能の一部です。これは ProblemDetails レスポンスに置き換えられました。	object

TicketResponse

{

"id": "6fd1e230-8032-4a29-bd96-a686716e1593",

"attributes": {

"mode": 1,

"playerCount": 2,

"teamSkill": 1500

},

"properties": {

"qosConnector": "...",

"partyInfo": "eyJwbGF5ZXJzSW5QYXJ0eSI6IHsidXNlcjEiOiB7ImtleXMiOiA0fSwgInVzZXIyIjogeyJrZXlzIjogMX19LCAid2luU3RyZWFrIjogNH0="

},

"created": 1570765498,

"assignment":{

"connection": "127.0.0.1:5000",

"error": "An example of an error",

"properties": {

"password": "12345"

},

"matchproperties": {

"mapToLoad": "moon",

"playersOnTeam": ["user1", "user2"]

}

}

}

フィールド	説明	型
attributes	送信済みの属性。	CreateTicket を参照してください。
properties	送信済みのプロパティ。	CreateTicket を参照してください。
created	Unix UTC ミリ秒単位で表されるチケットが作成された時刻。このフィールドには自動的にインデックスが付けられ、属性「"created"」として照会できるようになります。	long
assignment	マッチメイキングリクエストの結果が含まれるオブジェクト。	object
assignment.connection	専用ゲームサーバーまたはセッションに接続するための接続情報。	string
assignment.error	マッチメイキングの失敗を処理するカスタマイズ可能または既知の値。マッチ関数は Proposal.ProposalProperties.AssignmentError を使用してエラーを設定できます。代わりに、次の既知のエラーがいくつかあります。 PoolTimeout（設定済みの timeout-function によって返される） AllocationError（そのマッチで Multiplay の割り当てに失敗した）	string
assignment.properties	Proposal.ProposalProperties.TicketProperties を設定することでマッチ関数から提供されるカスタム情報。このデータは各チケットに対してプライベートであり、そのチケットのオーナーのみが知っているはずのデータを指定する必要があります。 前述の例では、ゲームサーバーと認証するためのパスワードをプレイヤーに伝えるためにそのプロパティが使用されています。プロパティは、特定のプレイヤーについて、他のプレイヤーからは確認できないスキルや能力を有効化するためにも使用できます。	object
assignment.matchproperties	Proposal.ProposalProperties.MatchProperties を設定することでマッチ関数から提供されるカスタム情報。このデータはすべてのプレイヤーとゲームサーバーに提供されます。 前述の例では、どのマップのロードを開始するか、および接続する間に次のゲームでどのプレイヤー名を表示するかをゲームクライアントに伝えるために、マッチプロパティが使用されています。	object

TicketResponse のコントラクト変更

変更	バージョン	説明
assignment.properties はプライベートになりました（いずれのプレイヤーとも共有されないチケットごとのデータ）。共有プロパティは assignment.matchproperties で返されるようになりました。	2.4.2	この変更は下位互換性があります。マッチ関数で Proposal.ProposalProperties.AssignmentProperties が設定された場合は、そのマッチ内のすべてのチケット間で assignment.properties が共有され、assignment.matchproperties は使用されないか、入力されません。 マッチ関数で Proposal.ProposalProperties.TicketProperties または Proposal.ProposalProperties.MatchProperties が設定された場合、この自動コントラクト変換は発生しません。

Config

{

"matchmaking": {

"name": "ctf-champions",

"targetFunction": {

"name": "my-team-func",

"version": "1"

},

"config": {

"TeamSizeMin": 3,

"TeamSizeMax": 4,

"NumberOfTeams": 2,

"MapsInRotation": ["dust", "moon", "mountain"]

}

},

"pools": {

"default": [

{

"attribute": "mode",

"min": 1,

"max": 1

},

{

"attribute": "skill",

"min": 0,

"max": 3000,

"segmentation": {

"DistributionType": "Normal",

"SegmentBehaviorType": "BucketCount",

"Value": 10,

"Stddev": 750

}

}

]

},

"multiplay": {

"Profile": "profileId",

"Access": "accessKey",

"Secret": "secretKey",

"FleetId": "fleetId"

}

}

フィールド	説明	型
matchmaking	マッチメイキングを継続的に実行するための設定。	object
name	フレンドリ名。	string
targetFunction	関数 API を使用してアップロードされる関数の名前。 注：現在 Version は考慮されません（「1」を使用してください）。	object
config	targetFunction で指定される関数の入力に固有のカスタムプロパティ。関数は config の構造について理解していると想定されます。 前述の例では、リストされたマップのいずれかでプレイしている 3 人から 4 人のプレイヤーでそれぞれ構成されたチームを、2 チーム申請するように関数が設定されています。	object
pools	条件に合ったプレイヤーを探すためにマッチ関数によって使用されるチケットの照会情報。キーは、チケットをどのプールから取得するのかを確認する際にマッチ関数で把握されるプール識別子です。たとえば、monsters と hunters は、ある関数が非対称のマッチモードを構築するために使用できる、異なる役割を持った 2 つの異なるプールへの参照として使用できます。このフィールドは省略可能です。	Dictionary<string, PoolFilter[]]>
multiplay	ゲームサーバーを割り当てるためにマッチメイキングによって使用されるマルチプレイヤー情報。このフィールドは省略可能です。Multiplay の設定が指定されていない場合でも、マッチ関数は実行されます。ただし、申請されたマッチにサーバーは割り当てられません。代わりに、割り当てはマッチ関数 Proposal の割り当てのオーバーライドに従って生成されます。マッチ関数に関するドキュメントを参照してください。	MultiplayConfig

PoolFilter

{

"attribute": "skill",

"min": 0,

"max": 3000,

"segmentation": {

"DistributionType": "Normal",

"SegmentBehaviorType": "BucketCount",

"Value": 10,

"Stddev": 750

}

}

フィールド	説明	型
attribute	照会を実行するチケット上のインデックス可能な属性の名前。現在フィルターは intersecting のみです。	string
min	double フィールドの下限（その値を含む）。	double
max	double フィールドの上限（その値を含まない）。 注：min==max の場合は、単一の値が見つけられるよう、max が含められます。たとえば、"min":1, "max":1 の使用は interval [1,1]（min と max の両方を含む）に一致し、"min":1, "max":3 の使用は interval [1, 3)（min を含み、max は含まない）に一致します。	double
segmentation	基本のフィルターから交差しないフィルターを自動的に生成するメソッド。セグメンテーションとスケールに関するドキュメントを参照してください。	object
distributionType	指定の attribute の母集団の形状を推定する曲線の記述。現在 Normal と Uniform がサポートされています。セグメンテーションとスケールに関するドキュメントを参照してください。	string
segmentBehaviorType	distributionType で記述されている曲線を細分化するメソッド。現在のオプションは TargetPercentage、BucketSize、BucketCount です。セグメンテーションとスケールに関するドキュメントを参照してください。	string
Value	segmentBehaviorType のターゲット。たとえば、動作タイプ BucketCount の値はフィルターを分割するために使用されるバケットの数になります。セグメンテーションとスケールに関するドキュメントを参照してください。	integer
Stddev	Normal 分布タイプで必要とされる標準偏差値。これは他の分布タイプでは無視されます。	number

MultiplayConfig

{

"Profile": "profileId",

"Access": "accessKey",

"Secret": "secretKey",

"FleetId": "fleetId"

}

フィールド	説明	型
Profile	Multiplay のプロフィール。これは通常、ビルドイメージのリビジョン、ハードウェアの仕様、サーバー側のゲーム設定、リソースの定義と関連付けられています。	string
Access	Multiplay のアクセスキー。Multiplay のガイダンスに従って生成される AWS アクセスキーです。	string
Secret	Multiplay のシークレットキー。Multiplay のガイダンスに従って生成される AWS シークレットキーです。	string
FleetId	割り当てる Multiplay フリートの ID。	string

ValidationErrorResponse

[

{

"ResultCode": "badFilterRange",

"Message": "Pool default' Filter mode has an invalid value range (Max < Min)",

},

{...}

]

フィールド	説明	型
ResultCode	結果コード。	string
Message	その設定のどのコンポーネントが無効であったかを説明するメッセージ。	string

FunctionList

{

"functions": [

{

"name": "custom-function",

"md5Hash": "mviLOUG44D02SbtkpQPcUA==",

"created": "2019-11-06T02:26:25.250+00:00",

"updated": "2019-11-06T02:26:25.250+00:00",

"status": {

"state": "Running",

"instances": [

{

"state": "Running",

"name": "custom-function-76697d79cd-s7nkc"

}

]

}

},

{...}

]

}

フィールド	説明	型
functions	現在展開されている関数の一覧。	array(function)
function	展開済みの関数、ステータス、メタデータの状態を表すオブジェクト。	関数

関数

{

"name": "custom-function",

"md5Hash": "mviLOUG44D02SbtkpQPcUA==",

"created": "2019-11-06T02:26:25.250+00:00",

"updated": "2019-11-06T02:26:25.250+00:00",

"status": {

"state": "Running",

"instances": [

{

"state": "Running",

"name": "custom-function-76697d79cd-s7nkc"

}

]

}

}

フィールド	説明	型
name	関数の開発者定義名。特定の関数を実行するために、Config の targetFunction で使用されます。	string
md5Hash	保証の目的でアップロードされたファイルの MD5。	string
created	関数がアップロードされた UTC 時間。	datetime (ISO 8601)
updated	関数が更新された UTC 時間。まだ更新されていない場合は、created の値と同じになります。	datetime (ISO 8601)
status	現在デプロイされている関数のリソースに関するステータス。	FunctionStatus

FunctionStatus

{

"state": "Running",

"instances": [

{

"state": "Running",

"name": "custom-function-76697d79cd-s7nkc"

}

]

}

フィールド	説明	型
state	関数の現在の状況すべての記述。ステートには、Running、Pending、Failed、Not Running、Unknown（ステートを確認できない場合）があります。	string
instances	高スケールのニーズや関数のゼロダウンタイムの展開を実現するためにスケーリングできる、展開済みの関数のリソースの配列。	配列
instance.state	個々のインスタンスのステータス。Running、Terminated、Waiting のいずれかになります。インスタンスは、スケジュールを設定するバックエンドがビジーであったり、トラフィックの需要に対応するようスケーリングしたりしている場合に、Waiting 状態になることがあります。	string
instance.name	デバッグ、サポート、ログ記録の目的でインスタンスをキーイングするための一意識別子。	string

FunctionLogs

{

"logs": {

"custom-function-568494c6b-dsp6z": "...",

"custom-function-a38gf663d-ja4gv": "..."

}

}

フィールド	説明	型
logs	あるマッチ関数のインスタンスとそれらに関連付けられているログのリスト。 注：ログには \n などの書式作成文字が含まれる場合があります。	Dictionary<string, string>

FunctionNameList

{

"functions": [

"custom-function-a",

"custom-function-b",

...

]

}

フィールド	説明	型
functions	再起動される関数名のリスト。	array(string)

FunctionDeployResult

{

"functions": [

{

"name": "custom-function-a",

"state": "Pending"

},

{

"name": "custom-function-b",

"state": "Failed"

}

...

]

}

フィールド	説明	型
functions	再起動をスケジュールされた関数のリスト。	array(function)
function.name	関数の名前。	string
function.state	個々の再起動のステータス。ステートには、Pending と Failed があります。	string

BackfillTicket

{

"Id" : "9c452395-d2e2-4ba3-bdde-125c75a98114",

"Created" : 1601585418595,

"RecordVersion" : 4,

"Connection" :"123.20.220.8:900",

"attributes": {

"mode": 1,

"playerCount": 2,

"teamSkill": 15.34

},

"properties": {

"qosConnector": "...",

"serverInfo": "eyAKICAgICJQbGF5ZXJzTmVlZGVkIiA6IDE0LAogICAgIlN1bU9mU2tpbGwiIDogIDIzOTcsCiAgICAiQ3VycmVudFBsYXllcnMiIDogMjYKfQ=="

}

}

フィールド	説明	型
created	バックフィルチケットが作成された Unix 時刻（ミリ秒単位）。	long
recordVersion	バックフィルチケットの最新バージョンを表します。このフィールドはマッチメーカーによって管理されます。変更されたバックフィルチケットを返すマッチ関数では、このフィールドは変更されません。	int
connection	チケットが割り当てられるサーバーの「"ip:port"」。サーバーまだ割り当て中である場合、マッチ関数ではこれが null 値として観測される場合があります。割り当てが完了すると、このバックフィルチケットに関連付けられているチケットにこの接続が割り当てられます。	string
id	バックフィルチケットの ID。更新/承認/削除操作に使用されます	string
attributes	これらのインデックス可能なフィールドは、マッチメイキングプールからバックフィルチケットを取得する目的で、マッチ関数で照会可能なフィールドとして利用できます。マッチ関数と DGS は、チケットの最新のステートを反映するためにこれらを更新することがあります。 このフィールドは省略可能です。	Dictionary<string, double>
properties	properties 内の値は、マッチメイキングロジックでシリアライズ/デシリアライズして使用するために、マッチ関数で利用できます。マッチ関数と DGS は、サーバーの最新のステートを反映するためにこれらを更新することがあります。前述の例では、serverInfo に次のカスタム Base64 エンコード文字列が含まれます。 { "PlayersNeeded" : 14, "SumOfSkill" : 2397, "CurrentPlayers" : 26} このフィールドは省略可能です。	Dictionary<string, byte[]>

CreateBackfillTicketRequest

{

"Connection" :"123.20.220.8:900",

"attributes": {

"mode": 1,

"playerCount": 2,

"teamSkill": 15.34

},

"properties": {

"qosConnector": "...",

"serverInfo": "eyAKICAgICJQbGF5ZXJzTmVlZGVkIiA6IDE0LAogICAgIlN1bU9mU2tpbGwiIDogIDIzOTcsCiAgICAiQ3VycmVudFBsYXllcnMiIDogMjYKfQ=="

}

}

フィールド	説明	型
connection	チケットが割り当てられるサーバーの「"ip:port"」。サーバーまだ割り当て中である場合、マッチ関数ではこれが null 値として観測される場合があります。割り当てが完了すると、このバックフィルチケットに関連付けられているチケットにこの接続が割り当てられます。	string
attributes	これらのインデックス可能なフィールドは、マッチメイキングプールからバックフィルチケットを取得する目的で、マッチ関数で照会可能なフィールドとして利用できます。マッチ関数と DGS は、チケットの最新のステートを反映するためにこれらを更新することがあります。 このフィールドは省略可能です。	Dictionary<string, double>
properties	properties 内の値は、マッチメイキングロジックでシリアライズ/デシリアライズして使用するために、マッチ関数で利用できます。マッチ関数と DGS は、サーバーの最新のステートを反映するためにこれらを更新することがあります。前述の例では、serverInfo に次のカスタム Base64 エンコード文字列が含まれます。 { "PlayersNeeded" : 14, "SumOfSkill" : 2397, "CurrentPlayers" : 26} このフィールドは省略可能です。	Dictionary<string, byte[]>

CreateBackfillTicketResponse

{

"Id" : "9c452395-d2e2-4ba3-bdde-125c75a98114"

}

フィールド	説明	型
Id	バックフィルチケットの ID。更新/承認/削除操作に使用されます	object

BackfillConfig

{

"connection": "95.32.128.231:7398",

"function": {

"name": "role_skill_match",

"version": "1.0.0"

},

"pools": {

"skill_pool": [

{

"attribute": "skill",

"max": 750,

"min": 450

}

],

"role_pool": [

{

"attribute": "tank",

"max": 1,

"min": 1

}

],

...// healer、dps、caster などの他の役割用の追加プール。

},

"config": {

/* カスタム JSON。既存のステートや想定されるステートを記述するためにマッチ関数によって把握されます */

"missing_players": [

{

"player_num": 2,

"id": "97e97652-744f-4031-9359-6614dcd1612e",

"team": 1,

"skill": 600,

"role": "healer"

},

{

"player_num": 6,

"id": "88028725-c8e2-4be4-8a87-1405f13c9314",

"team": 2,

"skill": 550,

"role": "dps"

}

],

"existing_players": [

{

"player_num": 1,

"id": "b1b1904b-27ed-46db-8414-a0dbf192e82b",

"team": 1,

"skill": 500,

"role": "tank"

},

.../* 既存のロースターの残り */

]

}

}

note

Functions、pools、config はいずれも Config 内の値と同じです。

フィールド	説明	型
connection	チケットが割り当てられるサーバーの「"ip:port"」。通常、これがリクエストを行うサーバーです。	string
function	関数 API を通じてアップロードされる関数の名前。 注：現在 Version は考慮されません（「1」を使用してください）。	object
pools	条件に合ったプレイヤーを探すためにマッチ関数によって使用されるチケットの照会情報。キーは、チケットをどのプールから取得するのかを確認する際にマッチ関数で把握されるプール識別子です。たとえば、monsters と hunters は、ある関数が非対称のマッチモードを構築するために使用できる、異なる役割を持った 2 つの異なるプールへの参照として使用できます。このフィールドは省略可能です。	Dictionary<string, PoolFilter&lt;/a>[]]>
config	targetFunction で指定された関数の入力に固有のカスタムプロパティ。関数は config の構造について理解していると想定されます。前述の例では、リストされたマップのいずれかでプレイしている 3 人から 4 人のプレイヤーでそれぞれ構成されたチームを、2 チーム申請するように関数が設定されています。	object

BackfillResponse （非推奨。backfill v2 を使用してください）

{

"assignedTickets": [

{

"id": "b1b1904b-27ed-46db-8414-a0dbf192e82b",

"assignment": {

"connection": "95.32.128.231:7398",

"error": null,

"properties": {}

},

"attributes": {

"skill": 500,

"tank": 1.00

},

"created": 1569967035,

"properties": {

"team": "MQ==", //base64 encoded 1

"role": "dGFuaw==", //base64 encoded “tank”

"number": "MQ==" //base64 encoded 1

}

},

{

"id": "97e97652-744f-4031-9359-6614dcd1612e",

"assignment": {

"connection": "95.32.128.231:7398",

"error": null,

"properties": {}

},

"attributes": {

"skill": 600,

"healer": 1.00

},

"created": 1569967035,

"properties": {

"team": "MQ==", //base64 encoded 1

"role": "aGVhbGVy" //base64 encoded “healer”

"Number": "Mg==" //base64 encoded 2

}

},

...// 追加のチケット

],

"assignmentProperties": {

/* そのマッチ関数から得られる、そのマッチに関連付けられたカスタムプロパティ */

"Region": "US_WEST",

"Average_Skill": 500,

...

},

"error": "何らかの一般エラーが発生した場合はエラーテキスト"

}

note

assignedTickets と assignmentProperties では、TicketResponse と同じ構造が使用されます。assignedTickets 内の繰り返しの配列オブジェクトは、TicketResponse の構造と同じです。assignmentProperties は、TicketResponse の構造の assignment.properties と同じです。

フィールド	説明	型
assignedTickets	リクエストの結果としてサーバーに割り当てられたチケット（TicketResponse に関するドキュメントを参照）。	オブジェクト配列
assignmentProperties	Proposal.ProposalProperties.AssignmentProperties を設定することでマッチ関数から提供されるカスタム情報。前述の例では、どのマップのロードを開始するかや、接続する間に次のゲームでどのプレイヤー名を表示するかが、プロパティによってゲームクライアントに伝えられます。	object
error	バックフィルに問題がある場合はエラー情報を表示し、問題がない場合は空の表示になります。 注：新しいプレイヤーの検索で問題が発生した場合は、「error」フィールドに「No Match Found」というメッセージが表示されます。	string

ProblemDetails

リクエストを正常に完了できない場合は、エラーレスポンスが生成されます。可能な場合は、このレスポンスが RFC 7807 ProblemDetails レスポンスの形式で表示されます。詳細については、RFC 7807 に関する IETF ドキュメントを参照してください。

たとえば、存在しないチケットをリクエストすると、次の例のようなレスポンスが返されます。

{

"type": "https://httpstatuses.com/404",

"title": "Not Found",

"status": 404,

"detail": "Ticket 551a9693-38f6-4404-a4cc-20dd4f4c6cee not found",

"instance": null,

"extensions": {

"correlationId": "18942ed9-5e36-4aa6-bcfe-0ae4aafe59a1"

}

}

ProblemDetails レスポンスは次のシナリオで生成されます。

リクエスト	理由	HTTP コード
チケットを作成	チケット検証エラー（無効なチケットコンテンツ）	400
チケットを作成	コンテンツタイプが無効/見つからない（Content-Type ヘッダーが application/json である必要があります)	415
チケットを購入する	チケットが見つからない	404
設定を作成する	設定検証エラー	400
設定を更新する	設定検証エラー	400
関数を作成する	無効な関数名	400
関数を作成する	ファイルが見つからないか、ファイル長がゼロ	400
関数を作成する	サポートされていないアーカイブタイプ	400
関数を作成する	最大ファイル長を超えている	400
関数を作成する	マッチ関数の最大数を超えている	400
関数を取得する	無効な関数名	400
関数を取得する	関数が見つからない	404
関数ログを取得する	時間範囲が無効	400
関数ログを取得する	無効な関数名	400
関数ログを取得する	関数が見つからない	404
関数を削除する	無効な関数名	400
任意	内部サービスエラー	5xx

ProblemDetails レスポンスで提供される詳細情報は、サポートリクエストに含めた場合、問題のトラブルシューティングに役立つ可能性があります。