Matchmaking 服务端API接入指南

Matchmaking 服务端API

Matchmaking 服务端 API 是面向需要在服务端集成 Matchmaking 的开发者提供的服务端集成的 API 列表。

API Endpoint: https://m.unity.cn

Matchmaking 服务端 API 授权

使用 Basic Authorization 来进行鉴权 (推荐服务器端程序使用). 步骤如下:

1. 在 UOS 网站上获取当前需要使用的 UOS APP 的 AppId 和 AppServiceSecret

   注：此处 AppId 和 AppServiceSecret，可在 UOS 网站上获取

   
   

2. 在请求任意 API 的 Request Header 中增加 Header:

   • Authorization: Basic base64(appId:appServiceSecret)

3. 示例代码

   C#

   # C# 使用示例 - Basic 授权方式
   using System;
   using System.Collections.Generic;
   using System.Net.Http;
   using System.Security.Cryptography;
   using System.Text;
   using System.Threading.Tasks;
   using Newtonsoft.Json;
   
   class Program
   {
       private static string GetBasicAuthorization(string appId, string appServiceSecret)
       {
           string credentials = $"{appId}:{appServiceSecret}";
           byte[] credentialsBytes = Encoding.UTF8.GetBytes(credentials);
           string encodedCredentials = Convert.ToBase64String(credentialsBytes);
           return $"Basic {encodedCredentials}";
       }
   
       public static async Task Main(string[] args)
       {
           using (HttpClient client = new HttpClient())
           {
               // 使用项目的 APP_ID, APP_SERVICE_SECRET 获取 headers
               client.DefaultRequestHeaders.Add("Authorization", GetBasicAuthorization(APP_ID, APP_SERVICE_SECRET));
   
               // 以get方法为例，替换 url 为你需要请求的 url
               HttpResponseMessage response = await client.GetAsync(url);
               response.EnsureSuccessStatusCode();
   
              // 其他处理……
           }
       }
   }

   Python

   # Python 使用示例 - Basic 授权方式
   import base64
   import requests
   
   def get_basic_authorization(app_id, app_service_secret):
     """ 获取basic auth的Header """
     credentials = f'{app_id}:{app_service_secret}'
     encoded_credentials = base64.b64encode(credentials.encode("utf-8")).decode("utf-8")
     return {'Authorization': f'Basic {encoded_credentials}'}
   
   # 使用 APP_ID, APP_SERVICE_SECRET 获取Basic Token Header
   headers = get_basic_authorization(APP_ID, APP_SERVICE_SECRET)
   # 以get方法为例，替换 url 为你需要请求的 url
   response = requests.get(url, headers=headers)

   JavaScript

   // JavaScript 使用示例 - Basic 授权方式
   const axios = require('axios');
   
   function getBasicAuthorization(appId, appServiceSecret) {
     /** 获取 basic auth 的 Header */
     const credentials = `${appId}:${appServiceSecret}`;
     const encodedCredentials = btoa(credentials);
     return { 'Authorization': `Basic ${encodedCredentials}` };
   }
   
   // 使用 APP_ID, APP_SERVICE_SECRET 获取Basic Token Header
   const headers = getBasicAuthorization(APP_ID, APP_SERVICE_SECRET);
   // 以get方法为例，替换 url 为你需要请求的 url
   const response = await axios.get(url, { headers });

   Go

   // Go 使用示例 - Basic 授权方式
   import (
       "bytes"
       "encoding/base64"
       "encoding/json"
       "fmt"
       "io"
       "net/http"
   )
   
   func GetBasicAuthorization(appID, appServiceSecret string) string {
       credentials := appID + ":" + appServiceSecret
       encodedCredentials := base64.StdEncoding.EncodeToString([]byte(credentials))
       return "Basic " + encodedCredentials
   }
   
   
   func main() {
       // 以get方法为例，替换 url 为你需要请求的 url
       req, err := http.NewRequest("GET", url, nil)
       if err != nil {
           return nil, err
       }
   
       // 使用 APP_ID, APP_SERVICE_SECRET 获取Basic Token Header
       req.Header.Set("Authorization", GetBasicAuthorization(APP_ID, APP_SERVICE_SECRET))
   
       client := &http.Client{}
       response, err := client.Do(req)
       if err != nil {
           return nil, err
       }
       defer resp.Body.Close()
       // ……其他处理
   }

Matchmaking 服务端 API 列表

Backfill

Backfill相关API，包括开启、停止、查询Backfill。

Ticket

Ticket相关API，包括创建、获取和删除Ticket。

Matchmaking 服务端 API 调用示例

Backfill API 调用示例:

-- Matchmking服务端 Backfill API & sync realtime lua plugin 使用示例

local muninn = require('MuninnPlugin')
local json = require('Utils.json')
local base64 = require('Utils.base64')

-- [生命周期] 创建房间成功后
function OnCreateRoom(room)
	muninn.LogInfo("[plugin] OnCreateRoom")

	-- 声明appId 和 appServiceSecret, 实际情况可根据你的项目修改appId, appServiceSecret存储位置
	local appId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"
	local appServiceSecret = "*************************"
	local mmApiAuthHeader = { Authorization = "Basic " .. base64.encode(appId .. ":" .. appServiceSecret)}
	local mmApiEndpoint = "https://m.unity.cn"

	-- 获取匹配系统匹配到的该局的所有玩家信息
	local match_properties = room.Properties["match_properties"]
	-- 如果开启了自动匹配回填，可通过该参数判断该局是否已启动匹配回填（开启自动匹配回填模式下，匹配阶段人数不满max_players会自动开启匹配回填，人数达到max_players则不会开启）
	local backfill_started = room.Properties["backfill_started"] == "true"

	if backfill_started then
		muninn.LogInfo("匹配回填已开始")
	else
	-- 根据实际情况决定是否手动开启匹配回填
		local data = {
			appId = appId,
			roomId = room.Id,
			teams = json.decode(match_properties) -- 传递匹配阶段抓取到的玩家信息，实际可根据情况自行传递真实的玩家数据
		}
		local startReq = {
			Method = "POST",
			Url = mmApiEndpoint .. "/v2/backfill/start",
			Headers = mmApiAuthHeader,
			Data = json.encode(data),
			Timeout = 1000,
		}

		local startResp, err = muninn.SyncHttp(startReq)
		if startResp.HttpStatusCode ~= 200 then
			muninn.LogInfo("请求开启匹配回填出错: " .. json.encode(startResp))
			return
		end

		muninn.LogInfo("开启匹配回填成功")

		-- 查看匹配回填结果
		local getReq = {
			Method = "GET",
			Url = mmApiEndpoint .. "/v2/backfill",
			Headers = mmApiAuthHeader,
			Params = {
				roomId = room.Id
			},
			Timeout = 1000,
		}

		local getResp, err = muninn.SyncHttp(getReq)
		if getResp.HttpStatusCode ~= 200 then
			muninn.LogInfo("查看开启匹配回填结果出错: " .. json.encode(getResp))
			return
		end

		local backfillInfo = json.decode(getResp.Data)

		-- 匹配回填存在亮种状态: active(撮合匹配玩家中)，completed（已完成，即人数达到max_players）
		muninn.LogInfo("匹配回填状态: " .. backfillInfo.status)
		muninn.LogInfo("当前该局房间所有玩家数据: " .. json.encode(backfillInfo.teams))

		-- 停止匹配回填
		if backfillInfo.status == "completed" then
			muninn.LogInfo("准备停止匹配回填，roomId: " .. room.Id)

			data = {
				roomId = room.Id
			}

			local deleteReq = {
				Method = "POST",
				Url = mmApiEndpoint .. "/v2/backfill/stop",
				Headers = mmApiAuthHeader,
				Data = json.encode(data),
				Timeout = 1000,
			}

			local deleteResp, err = muninn.SyncHttp(deleteReq)
			if deleteResp and deleteResp.HttpStatusCode ~= 200 then
				muninn.LogInfo("停止匹配回填出错: " .. json.encode(deleteResp))
				return
			end
		end
	end
end

-- 定时任务函数
function SendMessage()
	players, err = muninn.GetOnlinePlayers()
	for key, player in pairs(players) do
		local currentDateTime = os.date("%Y-%m-%d %H:%M:%S")
		muninn.SendMessage(player.Id, "[plugin] 每 10s 执行定时任务发送消息，当前接收者为玩家" .. player.Id .. "。" .. currentDateTime)
		muninn.LogInfo("[plugin] 每 10s 执行定时任务发送消息，当前接收者为玩家" .. player.Id .. "。" .. currentDateTime)
	end
end


-- [生命周期] 关闭房间前
function BeforeCloseRoom(room)
	muninn.LogInfo("[plugin] BeforeCloseRoom")
end

-- [生命周期] 关闭房间后
function OnClose(room)
	muninn.LogInfo("[plugin] OnClose")
end

-- [生命周期] 玩家加入房间前
function BeforeJoin(player)
	muninn.LogInfo("[plugin] BeforeJoin")
	return muninn.ReturnType.CONTINUE
end

-- [生命周期] 玩家加入房间后
function OnJoin(player)
	muninn.LogInfo("[plugin] OnJoin")
	muninn.SendMessage(player.Id, "[plugin] " .. player.Name .. " 欢迎加入房间!")
	local currentDateTime = os.date("%Y-%m-%d %H:%M:%S")
	muninn.SendMessage(player.Id, "[plugin] 当前服务器时间为" .. currentDateTime)
end

-- [生命周期] 玩家离开房间
function OnLeave(player)
	muninn.LogInfo("[plugin] OnLeave")
end

-- [生命周期] 玩家发起的事件
function OnMessage(msg)
	muninn.LogInfo("[plugin] OnMessage => " .. msg.Data .. " " .. tostring(msg.Target) )
	muninn.SendMessage(msg.SenderId, "[plugin] 接收到来自玩家" .. msg.SenderId .. "的消息")
	return muninn.ReturnType.CONTINUE
end

完整示例项目代码: mm.zip