Zh:Realms API

Minecraft Realms API时用于控制由Mojang的Minecraft Realms服务托管的世界的API端点。这是一个提供了抽象管理Minecraft服务器的付费服务。有关这个的更多信息可以在https://minecraft.net/realms找到。

桌面版的API端点位于 https://pc.realms.minecraft.net 。这是列在此页上所有的请求都应发送至的位置。

也有正在开发中的用于携带版的端点，位于 https://pocket.realms.minecraft.net 。相关文档见携带版Realms。

会话

会话标识存储在随着每个请求头发送的cookies对中。 请求中唯一必需的头是设置该cookie。

键	值
sid	这是登入用户的当前会话ID。它有着以下格式： token:<accessToken>:<player UUID>
user	这是登入用户的用户名。该值是大小写敏感的。
version	正在运行的Minecraft实例的版本。

一个示例请求：

GET /mco/available HTTP/1.1
Cookie: sid=<token>;user=Herobrine;version=1.14.4
Cache-Control: no-cache
Pragma: no-cache
User-Agent: Java/1.6.0_27
Host: pc.realms.minecraft.net
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive

注意

根据标准HTTP，GET请求没有参数，而POST请求可能包含内容（注意，以下几个POST请求的内容为空）。

定义一个服务器

对于大多数需要服务器的端点，会以JSON格式返回，包含以下值：

键	值	值类型
id	服务器的ID，必须唯一。	整型
remoteSubscriptionId	未知，也许与交易有关？似乎与“id”一样就可工作。	字符串
owner	服务器的拥有者。	字符串
ownerUUID	拥有者的唯一ID。如果和预览的玩家唯一ID相同的话，将启用配置按钮，注意此UUID不含连字符。	字符串
name	服务器的名称。	字符串
motd	服务器的MOTD。不支持颜色。	字符串
state	服务器的状态。可以是以下值之一：ADMIN_LOCK、CLOSED、OPEN、UNINITIALIZED	字符串
daysLeft	订阅剩余的时间。若不是拥有者则总是返回“0”，若已过期则返回“-1”。	整型
expired	订阅是否过期。	布尔
expiredTrial	试用订阅是否过期。	布尔
worldType	世界类型。可以是NORMAL、MINIGAME、ADVENTUREMAP、EXPERIENCE、INSPIRATION	字符串
players	当前连接的玩家数组？	包含字符串值的JSON数组
maxPlayers	玩家的最大玩家数，总是返回“10”。	整型
minigameName	当前活跃的小游戏的名称。若不是小游戏则返回null。	字符串
minigameId	尚未确定，可能是小游戏地图的唯一Id。若不是小游戏则返回null。	整型
minigameImage	当前小游戏图像的base64编码的PNG格式。若不是小游戏则返回null。	字符串
activeSlot	当前服务器世界（1-4）	整型
slots	世界槽列表。只对拥有者可见（/worlds/$ID）	未知
member	未知	布尔

端点

GET请求

GET /mco/available

返回玩家是否可以访问Minecraft Realms服务。 该请求不要求发送Cookie令牌。

返回：纯文本，唯一的值为

true

在Realms发布之前会返回false。

如果返回false，那么会显示该界面：[1]。

GET /mco/client/compatible

返回客户端版本是否为Realms的最新版本。这会使用Cookie令牌检查。

返回：字符串，若客户端过期则将返回OUTDATED，若客户端运行快照则返回OTHER，否则返回COMPATIBLE。

GET /worlds

返回玩家收到邀请或拥有的服务器列表。

返回：包含一个数组的JSON文件。数组中的每个元素都表示一个服务器。

键	值	值类型
servers	服务器数组	服务器的JSON数组

示例：

{"servers":[{  
        "id":1,
        "remoteSubscriptionId":"aaaa0000bbbb1111cccc2222dddd3333",
        "owner":"j_selby",
        "ownerUUID":"3333dddd2222cccc1111bbbb0000aaaa",
        "name":"A Test Server",
        "motd":"This is a testing server!",
        "state":"OPEN",
        "daysLeft":30,
        "expired":false,
        "expiredTrial":false,
        "worldType":"NORMAL",
        "players":["Notch"],
        "maxPlayers":10,
        "minigameName":null,
        "minigameId":null,
        "minigameImage":null,
        "activeSlot":1,
        "slots":null,
        "member":false
     }]
}

GET /worlds/$ID

返回有关这个服务器的单个服务器列表。 如果你不是这个服务器的拥有者，服务器将返回403错误，并带有JSON编码的错误消息。

返回：如上所示的JSON编码的服务器。

GET /worlds/v1/$ID/join/pc

需要一个被同意的TOS（服务条款）（如下）。

用于获取服务器的IP地址。

如果服务器不存在/你当前无法访问，服务器将返回404错误，不带其他内容。

返回：

键	值	值类型
address	服务器的地址，编码为[IP]:[Port]	字符串
pendingUpdate	服务器是否等待更新为较新的版本	布尔

GET /worlds/$ID/backups

R返回世界的备份列表。

如果服务器不存在/你当前无法访问，服务器将返回403错误，不带其他内容。

返回：指定世界ID的备份JSON编码列表。

{
    "backups": [
        {
            "backupId": "2019-09-08T18:04:53.5284117Z",
            "lastModifiedDate": 1567965893000,
            "size": 11080009,
            "metadata": {
                "game_difficulty": "1",
                "name": "Azerus Team",
                "game_server_version": "1.14.4",
                "enabled_packs": "{\"resourcePacks\":[],\"behaviorPacks\":[]}",
                "description": "§7Creators of §6Puzzle Wars§7 and §6Maze Wars              §8(l’o’l)",
                "game_mode": "0",
                "world_type": "NORMAL"
            }
        }
    ]
}

GET /worlds/$ID/slot/$WORLD(1-4)/download

获取最新备份的下载URL。

返回像这样的JSON响应：

{
	"downloadLink": "http://us-west-mcr-worlds.s3.amazonaws.com/dfasdfa/mcr_world.tar.gz?AWSAccessKeyId=ADSFASDFADSF&Expires=1457647137&Signature=ADSFASDFASDF",
	"resourcePackUrl": null,
	"resourcePackHash": null
}

GET /ops/$ID

返回该服务的管理员列表。你必须拥有该服务器才能查看，

返回：

键	值	值类型
ops	玩家名称列表	字符串的JSON数组

GET /subscriptions/$ID

返回当前服务器订阅的生命。

返回：

键	值	值类型
startDate	毫秒值。自1970年起测量。	长整型
daysLeft	该订阅中随剩余的时间。	整型
subscriptionType	该用户拥有的订阅类型。这可以是NORMAL或RECURRING。	字符串

GET /mco/buy

向用户下显示状态消息，以及Mojang网站的链接。

返回：

键	值	值类型
statusMessage	向用户显示的消息	字符串
buyLink	至购买网站的URL。可选的。如果未提供，则不显示链接。	字符串

GET /invites/count/pending

返回该玩家当前等待的邀请数量。

返回：整型值

GET /invites/pending

返回用户当前正在等待的邀请。

返回像这样的JSON响应：

{
    "invites": [
        {
            "invitationId": "21538412",
            "worldName": "Plagiatus' Realm",
            "worldDescription": "Play Slay here now!",
            "worldOwnerName": "Plagiatus",
            "worldOwnerUuid": "e75e2d263b724a93a3e7a2491f4c454f",
            "date": 1568125140562
        }
    ]
}

GET /worlds/templates/$TEMPLATE?page=$PAGE&pageSize=$PAGE_SIZE

返回Realms现存的地图。

模板	游戏内名称	描述
MINIGAME	小游戏	小游戏是Minecraft中自我包含、可重复且经常是合作性或竞争性的游戏。
ADVENTUREMAP	冒险	冒险是一类设计用于玩家在脑中有一个确定的目标从开始玩至游戏结束。它们通常包含一个故事、一个总体目标或玩家要努力奋斗的最终目标。
EXPERIENCE	体验	体验是一类宽松定义的地图，大多没有什么特定的目标，而玩家的目的也许是去探险、体验或观察。
NORMAL	世界模板	世界模板是一个自定义的生存世界生成，而Minecraft地形会继续在自定义区外之外生成。它们经常会允许玩家开始一些不同于寻常生存世界的事，例如失落的神殿、遗弃的前哨站或神秘的沉没遗迹。
INSPIRATION	Inspiration	Inspiration地图设计用于鼓励并激励玩家在MInecraft中创造或设计一些新的东西。

返回一个像这样的JSON响应：

{
    "templates": [
        {
            "id": 292,
            "name": "Maze Wars",
            "version": "1.0.3",
            "author": "Azerus Team",
            "link": "",
            "image": "<base64 image>",
            "trailer": "https://www.youtube.com/watch?v=Ly3HRBWUxQc",
            "recommendedPlayers": "2+ players",
            "type": "MINIGAME"
        }
    ],
    "page": 5,
    "size": 1,
    "total": 55
}

GET /trial

返回布尔类型。

True - 你拥有Realms的1个月免费试用

False - 你已经使用了你免费的1个月试用

GET /activities/liveplayerlist

返回玩家此刻的活动。

GET /subscriptions/$WORLD_ID

返回像这样的JSON响应：

{
    "startDate": 1562061319119,
    "daysLeft": 109,
    "subscriptionType": "NORMAL"
}

POST requests

POST /mco/tos/agreed

要加入Realm，你必须同意这个TOS。向该端点发送一个空白POST请求会设置标志位。

POST /ops/$WORLD_ID/$UUID

通过uuid给予玩家管理员状态。

返回像这样的JSON：

{
    "ops": [
        "BrandShei",
        "_Juski_",
        "Sirboys",
        "Plagiatus",
        "Just_Vlad"
    ]
}

POST /invites/$WORLD_ID

邀请玩家至Realm

负载

{
	"name":"Marc",					//用户名
	"uuid":"b05881186e75410db2db4d3066b223f7",	//UUID
	"operator":false,				//可选的
	"accepted":false,				//可选的
	"online":false					//可选的
}

返回像这样的有关Realm的JSON信息：

{
    "id": 123,
    "remoteSubscriptionId": "ID",
    "owner": "Notch",
    "ownerUUID": "069a79f444e94726a5befca90e38aaf5",
    "name": "Realm name",
    "motd": "Notch's realm",
    "defaultPermission": "MEMBER",
    "state": "OPEN",
    "daysLeft": 1,
    "expired": false,
    "expiredTrial": false,
    "gracePeriod": false,
    "worldType": "NORMAL",
    "players": [                                          //所有玩家（邀请的、接受的）的数组
        {
            "uuid": "b05881186e75410db2db4d3066b223f7",
            "name": "Marc",
            "operator": false,
            "accepted": false,
            "online": false,
            "permission": "MEMBER"
        }
    ],
    "maxPlayers": 10,
    "minigameName": null,
    "minigameId": null,
    "minigameImage": null,
    "activeSlot": 1,
    "slots": null,
    "member": false,
    "clubId": null
}

PUT requests

PUT /worlds/minigames/$MINIGAME_ID/$WORLD_ID

如果成功设置世界为小游戏则返回true

PUT invites/reject/$INVITATION_ID

拒绝来自玩家的请求。

若成功则发送空消息。

PUT /invites/accept/$INVITATION_ID

接受来自玩家的邀请

若成功则大宋空消息。

PUT /worlds/$WORLD_ID/open

开启Realm。

若世界开启则返回true。

PUT /worlds/$WORLD_ID/close

关闭Realm。

若世界关闭则返回true。

DELETE requests

DELETE /invites/$WORLD_ID/invite/$UUID

将玩家踢出你的Realms即使他没有同意申请。 $UUID - 玩家的UUID 若成功则返回空消息。

DELETE /ops/$WORLD_ID/$UUID

通过UUID移除玩家的管理员状态。

返回像这样的JSON响应：

{
    "ops": [
        "BrandShei",
        "_Juski_",
        "Sirboys",
        "Plagiatus",
        "Just_Vlad"
    ]
}