Func Stateful 服务端API接入指南

Func 服务端API授权

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

在 UOS 网站上获取当前需要使用的 UOS APP 的 AppId 和 AppServiceSecret
注：此处 AppId 和 AppServiceSecret，可在 UOS 网站上获取
在请求任意 API 的 Request Header 中增加 Header:
- Authorization: Basic base64(appId:appServiceSecret)

示例代码

# 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 使用示例 - 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()
    // ……其他处理
}

Func 服务端可以获取的环境变量列表

服务器内置了以下环境变量提供开发者使用。以Go语言为例，可以通过os.Getenv("变量名") 获取。

变量名	说明	示例
SERVER_ID	Func Stateful分配出的Server的UUID	a840**--4cf8--ebac**b5c8
SERVER_IP	Func Stateful分配出的Server的IP	...
SERVER_PORTS_NAMES	开发者设置的所有端口对应的名称。	tcp-8899,test-port1,test-port2,test-port3
SERVER_PORTS	Func Stateful分配出的端口号，以逗号分隔。顺序与变量SERVER_PORTS_NAMES对应	7424,7815,7384,7428
PROFILE_ID	Func Statefu当前服务器所使用的Profile ID	21a7**--0bee--8d63**e954

Func 服务端API列表

1. 服务端心跳

概述: 基于 Func-Stateful 开发的Server应用，如果启用了服务器心跳检测，需要以不低于1次/秒的频率发送心跳信息，否则Server将会被视作不可用（启用弹性伸缩策略后，如果达到缩容条件，Func Stateful会以 SCALE_DOWN_EVENT 事件的形式通知即将被回收的服务器处理缩容）。

基本信息

URL	Method	Content-Type
`https://func.unity.cn/v1/functions/heartbeat`	POST	application/json

请求参数

{
  "serverId": "<server-uuid>",
  "readyToClose": "bool"
}

参数说明

参数名	描述	类型	必填	默认值
serverId	Func Stateful分配出的Server的UUID，可以通过环境变量serverId获取，以Go语言为例，可以通过os.Getenv("SERVER_ID") 获取。	string	是
readyToClose	服务器在收到 SCALE_DOWN_EVENT 后，需要对缩容事件进行处理。完成处理后，发送 readyToClose 为 true 的心跳请求， Func Stateful 会对服务器进行回收。	bool	否	false

输出示例

{
  "event": "NO_EVENT"
}

输出参数说明

参数名	描述	类型
event	Func Stateful返回的事件	string

事件类型

Event	说明
NO_EVENT	心跳发送成功，Server没有需要处理的事件
SCALE_DOWN_EVENT	心跳发送成功，Server 需要处理缩容事件。在完成缩容事件的处理后，需要在下一次心跳请求中将 'readyToClose' 设置为true，Func Stateful在收到心跳后会立刻对服务器进行回收。 SCALE_DOWN_EVENT会有2分钟的超时时间，如果服务器没有发送'readyToClose'的心跳，Func Stateful 会在2分钟后对服务器进行回收。

2. 更新服务器信息

概述: 调用此 API 可以更新指定服务器的基本信息, 其中包括 name, tags, properties。

基本信息

URL	Method	Content-Type
`https://func.unity.cn/v1/functions/{appId}/server/{serverId}`	PUT	application/json

请求参数

{
  "name": "string",
  "tags": [
    "string"
  ],
  "properties": {
    "prop1": "string"
  },
  "profileId": "string"
}

参数说明

参数名	描述	类型	必填
appId	UOS 应用的 Id (UOS AppId)	string	是
serverId	指定需要更新信息的服务器的 id	string	是
name	需要更新的服务器名称	string	是
tags	需要更新的标签信息	string[]	是
properties	需要更新的自定义变量信息	map<string,string>	是
profileId	指定需要更新的配置 Id	string	否

输出示例

{
  "appId": "b6f4****-****-447d-****-6535****8507",
  "serverId": "874b****-****-4141-****-3d88****bcc7",
  "name": "update-FuncName",
  "tags": [
    "tags1",
    "tags2"
  ],
  "properties": {
    "prop1": "value1"
  }
}

输出参数说明

参数名	描述	类型
appId	UOS 应用的 Id (UOS AppId)	string
serverId	指定需要更新信息的服务器的 id	string
name	更新后的服务器名称	string
tags	更新后的标签信息	string[]
properties	更新后的自定义变量信息	map<string,string>

3. 获取服务器玩家 Id

概述: 调用此 API 可以获取指定服务器上所有连接的 player id.

基本信息

URL	Method	Content-Type
`https://func.unity.cn/v1/functions/{appId}/{serverId}/players`	GET	application/json

参数说明

参数名	描述	类型	必填
appId	UOS 应用的 Id (UOS AppId)	string	是
serverId	需要查询的服务器的 id	string	是
profileId	指定需要查询的配置 Id	string	否

输出示例

{
  "playerList": [
    "player1",
    "player2"
  ]
}

输出参数说明

参数名	描述	类型
playerList	指定服务器连接的用户列表	string[]

4. 创建服务器

概述: 调用此 API 可以创建新的服务器.

成为正式用户后可以使用此 API, 联系我们进行开通

基本信息

URL	Method	Content-Type
`https://func.unity.cn/v1/functions/{appId}/servers`	POST	application/json

请求参数

{
  "name": "string",
  "tags": [
    "string"
  ],
  "properties": {
    "prop1": "string"
  },
  "envs": {
    "env1": "string"
  },
  "profileId": "string"
}

参数说明

参数名	描述	类型	必填
appId	UOS 应用的 Id (UOS AppId)	string	是
name	新创建服务器的名称	string	否
tags	新创建服务器的标签	string[]	否
properties	新创建服务器的自定义变量	map<string, string>	否
envs	新创建服务器的环境变量	map<string, string>	否
profileId	指定需要创建的配置 Id	string	否

输出示例

{
  "serverId": "874b****-****-4141-****-3d88****bcc7",
  "name": "new-created-server",
  "endpoint": {
    "appId": "b6f4****-****-447d-****-6535****8507",
    "ip": "*.*.*.*",
    "ports": [
      {
        "port": "7026",
        "protocol": "TCP",
        "name": "tcp-8899"
      }
    ]
  }
}

输出参数说明

参数名	描述	类型
serverId	新创建的服务器 id	string
name	新创建的服务器名称	string
endpoint	新创建的服务器 IP 和端口相关信息	object

5. 删除服务器

概述: 调用此 API 可以删除指定服务器.

成为正式用户后可以使用此 API, 联系我们进行开通

基本信息

URL	Method	Content-Type
`https://func.unity.cn/v1/functions/{appId}/servers/{serverId}`	DELETE	application/json

参数说明

参数名	描述	类型	必填	默认值
appId	UOS 应用的 Id (UOS AppId)	string	是
serverId	需要删除的服务器 Id	string	是

返回HTTP状态码说明

状态码	说明
204	删除成功
401	请求的auth失败
500	删除失败

6. 驱逐服务器

概述: 调用此 API 可以将指定的服务器标记为"被驱逐"状态。被驱逐的服务器不会参与缩扩容计算，也不再接受新的玩家连接，但会继续运行并维持现有连接。

成为正式用户后可以使用此 API, 联系我们进行开通

基本信息

URL	Method	Content-Type
`https://func.unity.cn/v1/functions/{appId}/servers/evict`	POST	application/json

请求参数

{
  "serverId": "string",
  "profileId": "string"
}

参数说明

参数名	描述	类型	必填
appId	UOS 应用的 Id (UOS AppId)	string	是
serverId	需要驱逐的服务器 Id	string	是
profileId	指定需要驱逐的配置 Id	string	否

输出示例

{
  "server": {
    "serverId": "string",
    "name": "string",
    "endpoint": {
      "appId": "string",
      "ip": "string",
      "ports": [
        {
          "port": 0,
          "protocol": "string",
          "name": "string"
        }
      ]
    },
    "tags": ["string"],
    "properties": {
      "key": "value"
    },
    "playerCount": 0,
    "createdAt": "2024-01-01T00:00:00Z",
    "profileId": "string",
    "isEvicted": true
  }
}

输出参数说明

参数名	描述	类型
server.serverId	服务器 ID	string
server.name	服务器名称	string
server.endpoint	服务器端点信息	object
server.tags	标签列表	string[]
server.properties	自定义属性	map<string,string>
server.playerCount	当前玩家数量	number
server.createdAt	创建时间 (ISO 8601 格式)	string
server.profileId	Profile ID	string
server.isEvicted	是否已被驱逐	boolean

行为说明

缩扩容: 被驱逐的服务器不再参与任何缩扩容计算
新连接: 被驱逐的服务器不再接受新的玩家连接
现有连接: 已建立的连接保持不变，服务器继续运行

幂等性: 该 API 支持幂等操作，对已经处于被驱逐状态的服务器再次调用不会报错，会直接返回当前服务器信息。

返回HTTP状态码说明

HTTP 状态码	错误信息	说明
200	成功	驱逐成功
401	auth failed	认证失败
400	invalid app id	App ID 格式无效
400	server id is empty	Server ID 为空
400	invalid server id	Server ID 格式无效
400	invalid profile id	Profile ID 无效
400	server func id mismatch	服务器不属于指定应用
404	server not found	服务器不存在
500	Internal Server Error	服务器内部错误