脚本请求API

experimental

脚本请求API

配置
在基岩版专用服务器中启用模块
HTTP请求方法
简单HTTP请求
高级HTTP请求
- http.request
示例

WARNING

脚本API目前处于积极开发阶段，频繁会有破坏性更新。本文档基于Minecraft 1.21.20版本格式编写

WARNING

该模块仅能在基岩版专用服务器上使用。

通过脚本API，您可以发送和接收基于HTTP的请求来与互联网交互。更多详细信息请参阅微软官方文档。

配置

依赖项

与其他模块类似，您需要在manifest.json中添加依赖项：

json

{
    "dependencies": [
        {
            "module_name": "@minecraft/server-net",
            "version": "1.0.0-beta"
        }
    ]
}

在基岩版专用服务器中启用模块

从Minecraft官网下载基岩版专用服务器包
将压缩包解压到文件夹中

以下是默认基岩版专用服务器的目录结构：

- 📝behavior_packs
- - - 📝permissions.json
- 📝definitions
- 📝development_behavior_packs
- 📝development_resource_packs
- 📝development_skin_packs
- 📝resource_packs
- 📝structures
- - - 📝behavior_packs
    - 📝db
    - 📝resource_packs
- 📝world_templates

在config/<pack_id>/permissions.json或config/default/permissions.json文件中，通过在allowed_modules键中添加"@minecraft/server-net"来启用该模块。该模块在服务器中默认未启用。

修改默认配置文件夹中的文件将允许所有包含server-net模块的附加包访问@minecraft/server-net模块。
建议为每个脚本行为包单独分配权限。

BedrockServer/config/default/permissions.json

json

{
    "allowed_modules": [
        "@minecraft/server-gametest",
        "@minecraft/server",
        "@minecraft/server-ui",
        "@minecraft/server-admin",
        "@minecraft/server-editor",
        "@minecraft/server-net"
    ]
}

HTTP请求方法

脚本API支持以下HTTP请求方法：

简单HTTP请求

http.get(url) - 在行为包中执行简单的HTTP get请求。

url: string
返回: Promise<HttpResponse>

由于大多数请求都是没有正文的GET请求，@minecraft/server-net提供了这个便捷方法。该方法与http.request()的唯一区别是它会自动将方法设置为GET。

示例：

import { http } from "@minecraft/server-net";

http.get("http://example.com/").then((response) => {
    // HTTP响应的正文内容
    // 类型: string
    const body = response.body;
});

高级HTTP请求

http.request

向Web服务器发出请求。

config: HttpRequest
返回: Promise<HttpResponse>

config必须是一个新的HttpRequest实例，用于构建请求。

示例

以下是向Web服务器发送请求的几种方式，包括每种可用的HTTP请求方法。

创建HttpRequest对象

import { HttpRequest } from "@minecraft/server-net";

const request = new HttpRequest("http://localhost:8000/"); // 必须将URL作为参数

设置HTTP方法

有关HTTP请求方法的更多信息：https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods

GET

import { HttpRequestMethod } from "@minecraft/server-net";
request.method = HttpRequestMethod.Get;

HEAD

import { HttpRequestMethod } from "@minecraft/server-net";
request.method = HttpRequestMethod.Head;

POST

import { HttpRequestMethod } from "@minecraft/server-net";
request.method = HttpRequestMethod.Post;

PUT

import { HttpRequestMethod } from "@minecraft/server-net";
request.method = HttpRequestMethod.Put;

DELETE

import { HttpRequestMethod } from "@minecraft/server-net";
request.method = HttpRequestMethod.Delete;

设置HTTP头

HTTP头可用于HTTP请求中，提供有关请求上下文的信息，以便服务器可以定制响应。

import { HttpHeader } from "@minecraft/server-net";
request.headers = [
    new HttpHeader("Content-Type", "application/json"),
    new HttpHeader("auth", "my-auth-token"),
];

HttpHeader的值参数也接受'@minecraft/server-admin'模块中的SecretString对象。

import { HttpHeader } from "@minecraft/server-net";
import { secrets } from "@minecraft/server-admin";

const secret = secrets.get("TOKEN");
request.headers = [new HttpHeader("Authorization", secret)];

设置请求正文

HTTP请求正文的内容，此信息将发送到Web服务器。

request.body = "消息内容";

设置响应超时

设置请求超时和放弃前的等待时间（以秒为单位）。

此属性在HTTP请求中不常用。

request.timeout = 10; // 10秒

发送请求

向Web服务器发送请求，返回一个Promise HttpResponse。

http.request(request).then((response) => {
    // HTTP响应的正文内容
    // 类型: string
    response.body;
});

示例：

一个简单的脚本，将发送的聊天消息发布到Discord webhook。

import { world } from "@minecraft/server";
import { http, HttpRequest, HttpRequestMethod, HttpHeader } from "@minecraft/server-net";

// 注意：此事件需要服务器模块版本1.14.0-beta。
world.afterEvents.chatSend.subscribe((data) => {
    // 玩家发送的消息
    const chatMsg = data.message;

    // 创建一个新的请求到Discord webhook URL
    const request = new HttpRequest("https://discord.com/api/webhooks/您的webhook地址");

    // 将方法设置为POST类型（仅发送）
    request.method = HttpRequestMethod.Post;

    // 将请求正文设置为Discord要求的格式
    // 更多关于此主题的信息可以在这里找到：https://discord.com/developers/docs/resources/webhook
    request.body = JSON.stringify({
        content: chatMsg,
    });

    // 设置请求头
    request.headers = [new HttpHeader("Content-Type", "application/json")];

    // 执行请求
    http.request(request).then((response) => {
        // HTTP请求响应的正文
        response.body;
    });
});