# @bedrock-rbx/ocale 中文文档

规范地址：https://npmcn.com/package/%40bedrock-rbx/ocale/

版本：0\.4\.0
npm 元数据更新时间：2026-11-02T23:02:36.422Z
中文译文更新时间：2026-11-07T20:18:57.444Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bedrock-rbx/ocale
原文对照：https://npmcn.com/package/%40bedrock-rbx/ocale/?lang=original
项目主页：https://bedrock-livid.vercel.app/
源码仓库：https://github.com/christopher-buss/bedrock

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.4 MB，75 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.12\.0
- 运行依赖：0 个
- 首次发布：2026-05-06T00:52:04.210Z
- 最新版本发布：2026-11-02T23:02:36.068Z
- 近 30 天下载量：9349（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：41（近 12 个月 41 个）

## 中文简介

Roblox 打开云 API 客户端

## 安装

```sh
npm install @bedrock-rbx/ocale
```

也可以使用：`pnpm add @bedrock-rbx/ocale`、`yarn add @bedrock-rbx/ocale`、`bun add @bedrock-rbx/ocale`

## README

# @bedrock-rbx/ocale (英语)

零依赖性 TypeScript SDK 为Roblox Open Cloud.

[![npm version](https://img.shields.io/npm/v/@bedrock-rbx/ocale.svg)](https://npmx.dev/package/@bedrock-rbx/ocale) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/christopher-buss/bedrock/blob/main/LICENSE) [![CI](https://github.com/christopher-buss/bedrock/actions/workflows/ci.yaml/badge.svg)](https://github.com/christopher-buss/bedrock/actions/workflows/ci.yaml)

> **状态:0.1,前1.0.** 公共API正在稳定;打破变化可能 以微量释放,直到1.0.

## 这是什么 `@bedrock-rbx/ocale`? 吗?

输入的 HTTP 客户端 [Roblox 打开云](https://create.roblox.com/docs/cloud)。每个 Roblox 特性 (单曲,地点,游戏通行证,开发者产品,徽章,存储,Luau) 执行)作为自己的客户类被曝光,其方法,请求类型, 和反应类型,否则您会用手制取原始的 REST 结束点.

SDK的运行时间依赖度为零,运行在节点QQ24.12或BunXQ1.3上 使用标准 `fetch`, (中文(简体) ), `FormData`,以及 `TextEncoder` 网易API. 费率限额 队列和重试处理构建在 : 请求被排入每次操作的队列 与Roblox公布的限制相对应 429和5xx的答复,没有达到消费者代码 `try`编号 :`catch` 或者说 `setTimeout`。 。 。 .

`@bedrock-rbx/ocale` 是基础 [`@bedrock-rbx/core`](https://github.com/christopher-buss/bedrock/tree/main/packages/bedrock) 内部用于与 Roblox 交谈, 它可以作为独立软件包发布 用于任何需要输入 Open Cloud 的构建工具、脚本或服务 没有基德的全IaC引擎。 如果你已经依赖 `@bedrock-rbx/core`,ocare是过渡安装的;当 您需要HTTP级控制,核心的IaC引擎不会暴露.

## 安装

```bash
pnpm add @bedrock-rbx/ocale
# or: npm install @bedrock-rbx/ocale
# or: bun add @bedrock-rbx/ocale
```

**运行时间 :** (原始内容存档于2019-09-22). Node QQ 24.12 或 Bun QQ 1.3.

**认证 :** 每个客户端都拿一个 `credential` 在建筑业,用于 实例 `{ kind: "apiKey", apiKey }`时生成 API 密钥 [创建器枢纽 > 证书 > API 密钥](https://create.roblox.com/dashboard/credentials) 并给予它你计划所称行动的范围(每种方法的JSDoc) 列出其所需范围.

## 快开始

```ts
import { GamePassesClient } from "@bedrock-rbx/ocale/game-passes";

const client = new GamePassesClient({
    credential: { apiKey: "your-open-cloud-api-key", kind: "apiKey" },
});

const result = await client.get({
    gamePassId: "9876543210",
    universeId: "1234567890", // from your experience URL in Creator Hub
});

if (!result.success) {
    console.error(`Open Cloud call failed: ${result.err.message}`);
    process.exit(1);
}

console.log(`${result.data.name} (${result.data.id})`);
```

每种方法返回 `Promise<Result<T, OpenCloudError>>`。 。 。 . `Result` 是一个 受歧视的工会: `result.success` 实值 `true` 的解析后回复 `result.data`,或 `false` 显示结构错误 `result.err`。无例外 总是逃避客户的方法.

## 可用客户

资源客户端住在子路径上 所以未使用的特性 树摇出你的 捆绑.

| 子路径 | 客户端 | 它包含什么 |
| --- | --- | --- |
| `@bedrock-rbx/ocale/universes` | `UniversesClient` | 宇宙元数据,社交链接,图标和缩略图上传,服务器重启. |
| `@bedrock-rbx/ocale/places` | `PlacesClient` | 放置元数据, `.rbxl` 发布,Luau执行任务范围为一地. |
| `@bedrock-rbx/ocale/game-passes` | `GamePassesClient` | 游戏通过CRUD,图标上传,本地化名称和描述更新. |
| `@bedrock-rbx/ocale/developer-products` | `DeveloperProductsClient` | 开发者产品CRUD,图标上传,本地化名称和描述更新. |
| `@bedrock-rbx/ocale/badges` | `BadgesClient` | 徽章 CRUD 和本地化图标上传. |
| `@bedrock-rbx/ocale/storage` | `StorageClient` | 实时游戏状态的内存存储所(各种地图,队列). |
| `@bedrock-rbx/ocale/luau-execution` | `LuauExecutionClient` | 具有二进制输入和日志流的独立 Luau 执行任务 . |
| `@bedrock-rbx/ocale/locales` | `ROBLOX_CREATOR_LOCALES` (数据) | Roblox支持本地化字段的地籍参考列表. |

额外的开放云特性(消息、数据存储、OAuth、组、, 分析(分析)尚未包好;它们被跟踪在 [路线图](https://github.com/christopher-buss/bedrock/projects)。 。 。 .

软件包根( R)`@bedrock-rbx/ocale`\* 故意再出口只分享 公用事业: `Result`, (中文(简体) ), `Page`, (中文(简体) ), `OpenCloudError` 及其子类`ApiError`, (中文(简体) ), `RateLimitError`, (中文(简体) ), `NetworkError`, (中文(简体) ), `ValidationError`和类似) `OpenCloudClientOptions` 类型。 资源客户不在根管上.

## 利率限制和重审

SDK 将每个请求排入每个操作速率限制桶的后面 从Roblox出版的OpenAPI schema。 随便你打多少电话 代码需要; SDK 的速度.

重试行为是一能 - 意识:

| 方法类型 | 429 (限速) | 5xx (服务器出错) |
| --- | --- | --- |
| 创建 | 重试 | 不重试 |
| 读取/ 列表 | 重试 | 重试 |
| 更新 | 重试 | 重试 |
| 删除 | 重试 | 重试 |

创建操作跳过 5xx 重试, 因为 Roblox 不支持一能 密钥和重复重试将默默生成第二个资源。 如果你可以的话 外部检测复制件, 选择返回 5xx 重试 `retryableStatuses` 关于请求选项参数.

在尝试用尽后,最后的失败就会浮出水面 `result.err` 作为导致它的打入错误(`RateLimitError` 429辆, `ApiError` 页:1 5xx, (英语), `NetworkError` 用于运输级别的断层,等等).

429状态无法识别一个语义原因. `RateLimitError` 保留 上游地区 `code`,已解析 `details`和允许列表 `responseHeaders` 因此消费者可以检查现有证据。 将这些字段视为 而不是详尽无遗的:要求配额,一个较长的共享度表, 和被占用的操作能力可以产生重叠的反应形状. 资源特定代码只能从正向分类 域证据,例如已验证的阻断器任务引用.

观察用钩( C)`onRequest`, (中文(简体) ), `onRetry`, (中文(简体) ), `onRateLimit`接受回调 用于记录、计量或跟踪集成的客户端构建器.

## 请求配置覆盖

客户端级配置在构建时被冻结. 每个方法都接受可选 第二届 `RequestOptions` 参数,用于覆盖一个调用配置 :

```ts
const client = new GamePassesClient({
    credential: { apiKey: "main-key", kind: "apiKey" },
});

const result = await client.create(parameters, {
    credential: { apiKey: "asset-upload-key", kind: "apiKey" }, // different key for moderation safety
    deadlineMs: Date.now() + 495_000,
    timeout: 60_000,
});
```

这种模式符合多租户工具(每个工作空间不同的API密钥), 证书旋转( 扫描中框) , 并隔离重试/ 超时策略到 具体电话. `deadlineMs` 是整个逻辑的绝对时间戳 电话 无法完成的重试、 操作队列等, 或报告的预算等 在它失败之前 `RequestDeadlineExceededError`; 超大小重试保留 其服务器在更具体的延迟 `RetryDelayExceededError`。 。 。 .

## 测试助手

A 类 `@bedrock-rbx/ocale/testing` 子路径输出同样的假 SDK 自己的 综合测试的使用:

-   `createFakeHttpClient(...)` 用已录入的 HTTP 传输交换 假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假以假.
-   `createFakeSend(...)` 对于轻量级脚本 发送召回假冒 记录单调测试的要求和回放答复,不设计划 审定.
-   `createFakeSleep(...)` 用于确定重试和费率限制的时间.
-   `valid*Body` 固定装置(`validGamePassBody`, (中文(简体) ), `validPlaceBody`, (中文(简体) ), `validUniverseBody`,以及类似的)用于合成现实反应 载荷.

把假的通过 `httpClient` 财务报告和审定财务报表 `sleep` 参数 `OpenCloudClientOptions` 并针对抓获的请求提出抗辩.

## 现况、文件和贡献

此套装为1.0前并处于积极开发阶段. 轨迹范围和时间 页:1 [项目板](https://github.com/christopher-buss/bedrock/projects)。 。 。 .

-   [文件网站](https://bedrock-livid.vercel.app/) (工作正在进行)
-   [源寄存器](https://github.com/christopher-buss/bedrock/tree/main/packages/open-cloud)
-   [问题](https://github.com/christopher-buss/bedrock/issues) (仅保存者; 外部反馈贯穿 [讨论情况](https://github.com/christopher-buss/bedrock/discussions) 作为 快速请求)
-   [贡献指南](https://github.com/christopher-buss/bedrock/blob/main/CONTRIBUTING.md)
-   [安全政策](https://github.com/christopher-buss/bedrock/blob/main/SECURITY.md)

## 许可证

[麻省理工学院](https://github.com/christopher-buss/bedrock/blob/main/LICENSE) (c)) 克里斯托弗·布斯(英语:Christopher Buss).

## 常见问题

### @bedrock-rbx/ocale 是什么？

Roblox 打开云 API 客户端

### 如何安装 @bedrock-rbx/ocale？

在项目目录运行 npm install @bedrock-rbx/ocale，或使用 pnpm add / yarn add / bun add。

### @bedrock-rbx/ocale 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @bedrock-rbx/ocale 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @bedrock-rbx/ocale 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24\.12\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @bedrock-rbx/ocale 可以商用吗？

@bedrock-rbx/ocale 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @bedrock-rbx/ocale 的下载量有多少？

根据 npm 官方下载统计，@bedrock-rbx/ocale 在 2026/10/08 – 2026/11/06 这 30 天内被下载 9,349 次，日均约 312 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bedrock-rbx/ocale 还在维护吗？

最新版本 0\.4\.0 发布于 2026/11/03（4 天前）；至今共发布 41 个版本，其中过去 12 个月发布了 41 个；首次发布于 2026/05/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。