字符串库提供通用函数以操作字符串，例如提取子字符串或匹配模式。您可以通过全局 `Library.string` 库访问字符串库。

参见
[字符串模式参考](/luau/strings#string-pattern-reference)
以获取有关如何使用 `Library.string.match()`、`Library.string.gmatch()` 和
`Library.string.gsub()` 查找（和替换）子字符串的详细信息。

返回字符的内部数值编码
`s[i], s[i+1], ..., s[j]`。`i` 的默认值为 1；`j` 的默认值为 `i`。这些索引按照与函数 `Library.string.sub()` 相同的规则进行修正。

数值编码对应于单字节字符值（`0`-`255`）。
该函数在指定范围内每个字符返回一个数字，因此在多字符切片上调用它会产生多个返回值。如果解析的范围为空（调整后起始索引大于结束索引），则不返回任何值。

```lua
-- 单个字符
print(string.byte("A")) -- 65

-- 字符范围
print(string.byte("hello", 1, 3)) -- 104 101 108

-- 负索引（从末尾计数）
print(string.byte("abc", -1)) -- 99（'c' 的字节值）

-- 与 string.char 的往返
local a, b, c = string.byte("ABC", 1, 3)
print(string.char(a, b, c)) -- ABC
```


string.byte

要转换的字符范围的起始索引。


要转换的字符范围的结束索引。


返回字符的内部数值编码
`s[i], s[i+1], ..., s[j]`。`i` 的默认值为 `1`；`j` 的默认值为 `i`。这些索引按照与函数 string.sub 相同的规则进行修正。


接收零个或多个整数，并返回一个长度等于参数个数的字符串，其中每个字符的内部数值编码等于其对应的参数。

每个整数必须在 `[0, 255]` 范围内；超出该范围的值会引发错误。这是 `Library.string.byte()` 的逆操作。

```lua
-- 基本用法
print(string.char(72, 101, 108, 108, 111)) -- Hello

-- 单个字符
print(string.char(65)) -- A

-- 从字节值构造（例如，空字节）
local s = string.char(0)
print(#s) -- 1

-- 与 string.byte 的往返
local code = string.byte("Z")
print(string.char(code)) -- Z
```


string.char

零个或多个在 `[0, 255]` 范围内的整数，每个代表一个字节值。


接收零个或多个整数，并返回一个字符串，其长度等于参数的数量，其中每个字符的内部数字编码等于其对应的参数。

在字符串中搜索模式的第一次出现，并返回匹配的起始和结束索引。如果未找到匹配，则返回 `nil`。您可以使用可选的 `init` 参数指定搜索的起始位置，默认值为 `1`，可以为负数。可选的 `plain` 参数关闭模式匹配，因此该函数执行普通子字符串搜索；请注意，如果使用 `plain`，还必须提供 `init`。

```lua
-- 示例 1：基本用法
local s = "Hello, world!"
local pattern = "world"
local start_index, end_index = string.find(s, pattern)
print(start_index, end_index)  -- 输出：8 12
```

```lua
-- 示例 2：使用 init 参数
local s = "Hello, world! Hello, Roblox!"
local pattern = "Hello"
local start_index, end_index = string.find(s, pattern, 10)
print(start_index, end_index)  -- 输出：15 19
```

```lua
-- 示例 3：使用 plain 参数
local s = "Hello, world! (Hello)"
local pattern = "(Hello)"
local start_index, end_index = string.find(s, pattern, 1, true)
print(start_index, end_index)  -- 输出：14 20
```

```lua
-- 示例 4：未找到模式
local s = "Hello, world!"
local pattern = "Roblox"
local start_index, end_index = string.find(s, pattern)
print(start_index, end_index)  -- 输出：nil
```


string.find

pattern

要在给定字符串中搜索的模式。

init

plain

如果为 true，则关闭模式匹配并执行普通子字符串搜索。


在字符串 `s` 中查找模式的第一个匹配，并返回匹配开始和结束的索引。

返回其可变数量参数的格式化版本，遵循其第一个参数中给出的描述，该参数必须是字符串。

您可以使用 `Library.string.format()` 函数将变量转换为用户友好的文本字符串。该函数需要以下格式：

`%[flags][width].[precision][specifier]`。

#### 说明符

字符串格式化中最重要的部分是 **说明符**。

<table>
  <thead>
    <tr>
      <th>说明符</th>
      <th>接受</th>
      <th>输出</th>
      <th>示例输出</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>c</code></td>
      <td>整数</td>
      <td></td>
      <td><code>3</code></td>
    </tr>
    <tr>
      <td><code>d</code> 或 <code>i</code></td>
      <td>整数</td>
      <td>十进制表示。</td>
      <td><code>321</code></td>
    </tr>
    <tr>
      <td><code>e</code> 或 <code>E</code></td>
      <td>浮点数</td>
      <td>使用 <code>e</code> 或 <code>E</code> 的科学计数法。</td>
      <td><code>3.296e2</code><br><code>3.296E2</code></td>
    </tr>
    <tr>
      <td><code>f</code></td>
      <td>浮点数</td>
      <td></td>
      <td><code>3231.1231</code></td>
    </tr>
    <tr>
      <td><code>g</code> 或 <code>G</code></td>
      <td>浮点数</td>
      <td>较短的 <code>e</code>/<code>E</code> 和 <code>f</code>。</td>
      <td><code>3E14</code><br><code>3e14</code></td>
    </tr>
    <tr>
      <td><code>o</code></td>
      <td>整数</td>
      <td>八进制表示。</td>
      <td><code>610</code></td>
    </tr>
    <tr>
      <td><code>q</code></td>
      <td>字符串</td>
      <td>以适合被 Luau 解释器安全读取的形式表示的字符串。字符串用双引号括起来，所有双引号、换行符、嵌入的零和反斜杠都被正确转义。</td>
      <td><code>"print(\"Hi\")"</code></td>
    </tr>
    <tr>
      <td><code>s</code></td>
      <td>字符串</td>
      <td></td>
      <td><code>Hello world!</code></td>
    </tr>
    <tr>
      <td><code>u</code></td>
      <td>整数</td>
      <td>十进制表示。</td>
      <td><code>3131</code></td>
    </tr>
    <tr>
      <td><code>x</code> 或 <code>X</code></td>
      <td>整数</td>
      <td>十六进制表示。</td>
      <td><code>7fa</code><br><code>7FA</code></td>
    </tr>
    <tr>
      <td><code>*</code></td>
      <td>任何</td>
      <td>等同于 <code>s</code>，但接受任何变量，通过使用 <code>Global.LuaGlobals.tostring()</code> 将其转换为字符串。</td>
      <td><code>table: 0x0123456789abcdef</code></td>
    </tr>
    <tr>
      <td><code>%</code></td>
      <td></td>
      <td><code>%</code> 后跟另一个 <code>%</code> 将返回 <code>%</code> 符号本身。</td>
      <td><code>%</code></td>
    </tr>
  </tbody>
</table>

```lua
local str = "The magic word is %s"
print(string.format(str, "Roblox"))
-- The magic word is Roblox

local str = "The magic word is %q"
print(string.format(str, "Roblox"))
-- The magic word is "Roblox"

local str = "Skip to \na new line and \nanother new line!"
print(string.format(str, "%q"))
--[[ 输出：
Skip to
a new line and
another new line!
]]
```

#### 标志

<table>
<thead>
  <tr>
    <th>标志</th>
    <th>描述</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td><code>-</code></td>
    <td>左对齐给定的字段宽度（见 <b>宽度</b>）。右对齐是默认值。</td>
  </tr>
  <tr>
    <td><code>+</code></td>
    <td>强制在数字前加上 <code>+</code> 符号。对负数没有影响。</td>
  </tr>
  <tr>
    <td>(空格)</td>
    <td>在正数前插入一个空格，而负数不受影响。这对于使正负数在视觉堆叠列表中垂直对齐很有用。</td>
  </tr>
  <tr>
    <td><code>#</code></td>
    <td>与 <code>o</code> 和 <code>x</code>/<code>X</code> 一起使用时，在非零值前写入 <code>0</code>（八进制）或 <code>0x</code>/<code>0X</code>（十六进制）。<br>与 <code>e</code>/<code>E</code> 和 <code>f</code> 一起使用时，强制输出包含小数点，即使后面没有数字（默认情况下，如果后面没有数字，则不写小数点）。<br>与 <code>g</code> 或 <code>G</code> 一起使用时，结果与 <code>e</code> 或 <code>E</code> 相同，但不删除尾随零。</td>
  </tr>
  <tr>
    <td><code>0</code></td>
    <td>用零而不是空格左填充数字（见 <b>宽度</b>）。</td>
  </tr>
</tbody>
</table>

```lua
local str = "%-10d"
print(string.format(str, 300) .. "]")
-- 300       ]
-- '300' 和 ']' 之间有 7 个空格

local str = "%+i versus %+i"
print(string.format(str, 300, -300)) -- +300 versus -300

local str = "There is a% i%% chance of rain in Seattle today."
print(string.format(str, 100))
-- There is a 100% chance of rain in Seattle today.
```

#### 宽度

<table>
  <thead>
    <tr>
      <th>宽度</th>
      <th>描述</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>(数字)</td>
      <td>返回的最小字符数。如果要格式化的字符数少于此数字，则结果用空格填充。</td>
    </tr>
  </tbody>
</table>

```lua
local str = "%012i"
print("Score: " .. string.format(str, 15000))
-- 输出：Score: 000000015000
-- 输出总共有 12 位，左侧用零填充
```

#### 精度

默认精度为 <code>1</code>。如果您给出一个没有值的句点，默认值为 <code>0</code>。

<table>
  <thead>
    <tr>
      <th>精度</th>
      <th>描述</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>.</code>(数字)</td>
      <td>对于整数说明符（<code>d</code>, <code>i</code>, <code>o</code>, <code>u</code>, <code>x</code>/<code>X</code>），精度指定要返回的最小数字位数。如果要格式化的值短于此数字，则结果用前导零填充。精度为 <code>0</code> 意味着值 <code>0</code> 不写入任何字符。<br>对于 <code>e</code>/<code>E</code> 和 <code>f</code> 说明符，这是小数点后要打印的数字位数。<br>对于 <code>g</code>/<code>G</code> 说明符，这是最大数字位数（在 <code>e</code>/<code>E</code> 之前，如果存在）。<br>对于 <code>s</code>，这是要返回的最大字符数。<br>对于 <code>c</code> 和 <code>q</code>，这没有影响。</td>
    </tr>
  </tbody>
</table>

```lua
-- 添加小数，精度为 2，用于货币输出
local str = "$%.2f"
print(string.format(str, 300)) -- 输出：$300.00

-- 返回字符串的前 6 个字母
local str = "%.6s"
print(string.format(str, "Robloxian")) -- 输出：Roblox

local str = "Once upon a time, there was a dragon named %s and it had %.8f horns."
print(string.format(str, "Pi", math.pi))
-- 输出：Once upon a time, there was a dragon named Pi and it had 3.14159265 horns.
```


string.format

formatstring

包含格式说明符的字符串，控制后续参数的格式。


根据格式字符串中的说明符进行格式化的值。


返回其可变参数的格式化版本，按照其第一个参数给出的描述，必须为字符串。

返回一个迭代器函数，每次调用时返回字符串 `s` 中 `pattern` 的下一个捕获。如果模式没有捕获，则每次调用返回整个匹配。

迭代器通常在通用 `for` 循环中使用。当模式包含捕获组时，每次调用返回捕获的子字符串作为单独的值。空匹配（零宽度）会使当前位置向前移动一个字符，以避免无限循环。

```lua
-- 遍历句子中的所有单词
for word in string.gmatch("Hello Roblox world", "%a+") do
    print(word)
end
-- Hello
-- Roblox
-- world

-- 使用捕获提取键值对
local t = {}
for key, value in string.gmatch("name=Roblox, version=1.0", "(%w+)=(%w[%w.]*)") do
    t[key] = value
end
print(t.name, t.version) -- Roblox 1.0

-- 收集所有数字
local digits = {}
for d in string.gmatch("abc123def456", "%d+") do
    table.insert(digits, d)
end
print(table.concat(digits, ", ")) -- 123, 456
```


string.gmatch

返回一个迭代器函数，每次调用时返回模式在字符串 `s` 中的下一个捕获。

全局替换的缩写。返回 `s` 的副本，其中所有（或前 `n` 个，如果给定）模式的出现都被给定的 `replacement` 替换。第二个返回值是进行的替换总数。

`replacement` 可以是几种类型之一，每种类型的使用方式不同，以确定实际字符串：

- 字符串：模式直接替换为字符串
- 表：匹配模式的字符串在表中作为键查找，值（字符串）是替换它的内容（如果存在）。
- 函数：使用匹配模式的字符串调用，应该返回替换匹配模式的字符串。

可以提供一个可选的最后一个参数，指定要进行的最大替换次数（例如，替换 2 次后停止）

#### 各种示例

```lua
-- 基本替换
string.gsub("I love tacos!", "tacos", "Roblox") --> I love Roblox! 1
-- 使用模式的替换
string.gsub("I like red!", "%w+", "word") --> word word word! 3
-- 替换表
string.gsub("I play Roblox.", "%w+", {I="Je", play="joue à"}) --> "Je joue à Roblox." 3
-- 替换函数
string.gsub("I have 2 cats.", "%d+", function(n) return tonumber(n) * 12 end) --> "I have 24 cats." 1
-- 仅替换两次
string.gsub("aaa", "a", "b", 2) --> "bba" 2
-- 使用捕获组的替换（最多九个）
string.gsub("love2play Roblox", "(%w+)(%d+)(%w+)%s+(%w+)", "I %1 %2 %3 %4!") --> "I love 2 play Roblox!" 1
```


string.gsub

要替换的字符串中给定模式的出现。

replacement

确定应替代给定模式的出现的内容。

replacements

返回 `s` 的副本，其中所有或前 `n` 次出现的模式被给定的替代值替换。第二个返回值是所做替代的总数。

返回字符串 `s` 中的字节数。由于 Luau 字符串是字节序列，因此这计算字节而不是 Unicode 字符或字形簇。空字符串返回 `0`。嵌入的空字节（`\\0`）也包含在计数中。

```lua
print(string.len("Hello")) -- 5
print(string.len(""))      -- 0

-- 嵌入的空字节被计数
local s = "ab\\0cd"
print(string.len(s)) -- 5

-- 等同于 # 长度运算符
local str = "Roblox"
print(string.len(str) == #str) -- true
```


string.len

返回字符串 `s` 的副本，其中所有大写 ASCII 字母（`A`-`Z`）都被更改为其小写等价物（`a`-`z`）。ASCII 字母范围之外的字符，包括带重音或多字节字符，保持不变。

```lua
print(string.lower("HELLO")) -- hello
print(string.lower("Hello World!")) -- hello world!

-- 非字母字符不受影响
print(string.lower("Roblox 123!")) -- roblox 123!

-- 仅转换 ASCII 字母
print(string.lower("ABC abc")) -- abc abc
```


string.lower

返回一个副本，其中所有大写字母变为小写。

查找字符串 `s` 中 `pattern` 的第一次匹配。如果模式包含捕获，则捕获的子字符串作为单独的值返回；否则，返回整个匹配。如果未找到匹配，函数返回 `nil`。

可选的第三个参数 `init` 指定开始搜索的字节位置（默认 `1`）。负的 `init` 从字符串末尾计数。与 `Library.string.find()` 不同，此函数直接返回捕获值，而不是匹配索引。

```lua
-- 提取匹配的子字符串
print(string.match("I have 42 cats", "%d+")) -- 42

-- 多个捕获
local year, month, day = string.match("2024-03-15", "(%d+)-(%d+)-(%d+)")
print(year, month, day) -- 2024 03 15

-- 未匹配返回 nil
print(string.match("hello", "%d+")) -- nil

-- 使用 init 跳过
print(string.match("foo123bar456", "%d+", 7)) -- 456

-- 锚定模式
print(string.match("hello", "^%a+")) -- hello
```


string.match

查找字符串 `s` 中 `pattern` 的第一次匹配。


返回一个包含提供参数的二进制字符串。第一个参数 `format` 决定了其余参数的打包方式；请参见 [这里](https://www.lua.org/manual/5.3/manual.html#6.4.2) 以获取选项。

string.pack

format

描述要打包的值的布局和类型的格式字符串。


根据格式字符串序列化为二进制形式的值。


返回一个包含提供参数的二进制字符串。

返回使用给定描述打包的任何字符串的字节大小。唯一的参数 `format` 决定了其余参数的打包方式，但您不能使用 `s` 和 `z`，因为它们的长度是可变的。请参见 [这里](https://www.lua.org/manual/5.3/manual.html#6.4.2) 以获取选项。

string.packsize

描述打包布局的格式字符串（不得包含可变长度选项 `s` 或 `z`）。


返回使用给定描述打包的任何字符串的字节大小。

返回字符串 `s` 的 `n` 份副本的连接。如果 `n` 为零或负数，函数返回空字符串。如果结果字符串超过最大字符串大小，则会引发错误。

```lua
print(string.rep("ab", 3))  -- ababab
print(string.rep("Go! ", 2)) -- Go! Go!

-- 零或负重复返回空字符串
print(string.rep("x", 0))  -- (空字符串)
print(string.rep("x", -1)) -- (空字符串)

-- 用于填充或分隔符
local separator = string.rep("-", 20)
print(separator) -- --------------------
```


string.rep

返回一个字符串，它是字符串 `s` 的 `n` 份副本的连接。

返回字符串 `s` 的字节反转副本。由于反转操作是针对单个字节进行的，因此多字节 UTF-8 序列在反转后不会作为有效字符保留。

```lua
print(string.reverse("hello"))  -- olleh
print(string.reverse("Roblox")) -- xolboR

-- 单个字符或空字符串
print(string.reverse("a")) -- a
print(string.reverse(""))  -- (空字符串)

-- 回文检查
local function isPalindrome(s)
    local lower = string.lower(s)
    return lower == string.reverse(lower)
end
print(isPalindrome("racecar")) -- true
print(isPalindrome("hello"))   -- false
```


string.reverse

返回一个字符串，它是字符串 `s` 的反转。

根据定义的分隔符字符将字符串拆分为部分，返回一个有序结果的表。

如果找到一个空的 "slice"，该部分将作为空字符串返回。例如 `string.split("abc||def", "|")` 将返回一个包含三个字符串的表：`"abc"`、`""` 和 `"def"`。

```lua
local input = "a,b,c"
local values = input:split(",")
print(values[1], values[2], values[3]) --> "a" "b" "c"
```
还要注意，原始字符串中的空格将被保留，例如 `string.split("abc _ def", "_")` 将尊重 `_` 分隔符两侧的空格。默认情况下，分隔符字符为 `,`，但您可以指定替代字符或字符序列。

**边缘情况**

#### 空字符串

```lua
local result = string.split("", ",")
print(#result) --> 1
print(result[1]) --> ""
```

#### 空切片

```lua
local result = string.split("foo,,bar", ",")
print(result[1], result[2], result[3]) --> "foo" "" "bar"

local result2 = string.split(",foo", ",")
print(result2[1], result2[2]) --> "" "foo"

local result3 = string.split("foo,", ",")
print(result3[1], result3[2]) --> "foo" ""

local result4 = string.split(",", ",")
print(result4[1], result4[2]) --> "" ""

local result5 = string.split(",,", ",")
print(result5[1], result5[2], result5[3]) --> "" "" ""
```

#### 空格保留

```lua
local result = string.split("   whitespace   ", ",")
print(result[1]) --> "   whitespace   "

local result2 = string.split("foo , bar", ",")
print(result2[1], result2[2]) --> "foo " " bar"
```

#### 无效的 UTF-8

```lua
local result = string.split("\\xFF", ",")
print(result[1]) --> "\\xFF"

local result = string.split("\\xFF,\\xFE", ",")
print(result[1], result[2]) --> "\\xFF" "\\xFE"
```

#### Unicode

```lua
local result = string.split("我很高兴，你呢？", "，")
print(result[1], result[2]) --> "我很高兴" "你呢？"

local result2 = string.split("hello•world", "•")
print(result2[1], result2[2]) --> "hello" "world"
```

string.split

separator

用于分割字符串的分隔符字符。

根据定义的分隔符将字符串分割成多个部分，返回一个有序结果的表。

返回从字节位置 `i` 开始并持续到字节位置 `j` 的子字符串，包括 `j`。`i` 和 `j` 都可以为负数：`-1` 指最后一个字节，`-2` 指倒数第二个，以此类推。`i` 的默认值为 `1`（开始），`j` 的默认值为 `-1`（结束）。

如果解析后的 `i` 小于 `1`，则修正为 `1`。如果 `j` 超过字符串长度，则修正为字符串长度。如果在这些修正后 `i` 大于 `j`，则函数返回空字符串。

```lua
local s = "Hello, world!"
print(string.sub(s, 1, 5))   -- Hello
print(string.sub(s, 8))      -- world!
print(string.sub(s, -6))     -- orld!
print(string.sub(s, -6, -2)) -- orld

-- 提取文件扩展名
local filename = "script.lua"
local dot = string.find(filename, "%.")
print(string.sub(filename, dot + 1)) -- lua

-- 当起始 > 结束时结果为空
print(string.sub("abc", 3, 1)) -- (空字符串)
```


string.sub

子字符串的起始字节位置（负值从末尾计数）。


子字符串的结束字节位置，包括（负值从末尾计数）。


返回从 `i` 开始并持续到 `j` 的子字符串，包括 `j`。`i` 和 `j` 可以为负数。`i` 的默认值为 `1`，`j` 的默认值为 `-1`。


从提供的二进制字符串中提取值，基于第一个参数 `format`，该格式应与最初用于 `Library.string.pack|pack()` 的格式相匹配；请参见 [这里](https://www.lua.org/manual/5.3/manual.html#6.4.2) 以获取选项。可选的第三个参数决定读取开始的字节。

string.unpack

描述二进制数据打包方式的格式字符串。


data

要从中解包值的二进制字符串。


readStart

在 `data` 中开始读取的字节位置。


提取到的值以及第一个未读字节的索引。

从提供的二进制字符串中提取值。

返回字符串 `s` 的副本，其中所有小写 ASCII 字母（`a`-`z`）都被更改为其大写等价物（`A`-`Z`）。ASCII 字母范围之外的字符，包括带重音或多字节字符，保持不变。

```lua
print(string.upper("hello")) -- HELLO
print(string.upper("Hello World!")) -- HELLO WORLD!

-- 非字母字符不受影响
print(string.upper("roblox 123!")) -- ROBLOX 123!

-- 仅转换 ASCII 字母
print(string.upper("abc ABC")) -- ABC ABC
```


string.upper

返回一个副本，其中所有小写字母变为大写。

string

一个在特定事件发生时运行连接的函数的对象。

Data Type

RBXScriptSignal

Luau

Tuple

Variant

boolean

函数是可以根据命令多次执行的代码块。

function

number

一系列字符，如字母、数字和符号。

数据类型，可以存储多个任意非 nil 类型的值，包括布尔值、数字、字符串、函数和其他表。

table

体验

虚拟形象

素材

范例和项目

引擎 API

Open Cloud API

Studio

分析

平台

教程

创作者计划

教育

学习

此方法是异步的，会返回一个`Operation`对象，该对象表示操作的当前状态。它包含一个端点路径，您可以轮询该路径以获取实际响应和相关的元数据。有关长时间运行操作的更多信息，请参阅[文档]({longRunningOperationsLink})。

以下部分描述了操作完成时提供的响应和元数据对象。

Beta 测试终点已准备好公开使用。可能出现导致功能无法正常运作的更改，但几率极低。

这些 Open Cloud 文档页面将于 2026 年 3 月 31 日移除。届时你将被自动重定向到新的 Open Cloud 文档。{linkStart}了解更多{linkEnd}

这些旧 Open Cloud 页面将于 2026 年 3 月 31 日移除并重定向。{linkStart}了解更多{linkEnd}

实验性终端节点已准备好供公众使用，但随着 API 协定的最终确定，可能偶尔会出现重大变更。

此终端节点可通过使用 API 密钥的 {httpServiceLinkStart}HttpService{httpServiceLinkEnd} 在体验中调用。

此字段可能在创建资源时被设置，但可能无法在后续请求中修改。

这些字段可能在创建资源时被设置，但可能无法在后续请求中修改。

此字段可以在请求中提供，但永远不会包括在答复中。

旧版验证方法。始终首选使用 API 密钥或 OAuth 2.0（如有）。

每个 API 密钥：每个 IP 地址每 {periodInSeconds} 秒有 {maxInPeriod} 次请求

无需身份验证即可调用。通常会显著降低速率限制。始终首选使用 API 密钥或 OAuth 2.0（如有）。

对于每个分组，只需提供架构中的以下字段之一，其余字段可以排除。

你可以随时重新选择加入。{linkStart}提供反馈。{linkEnd}

你正在查看旧版文档。{linkStart}提供反馈。{linkEnd}

你可以随时退出，并重定向回旧的引用页面。{linkStart}在这里提供反馈。{linkEnd}

你正在查看全新改版的文档。{linkStart}提供反馈。{linkEnd}

此字段可能被设置为响应，但在请求中将被忽略。

注意：在高流量期间，速率限制可能会更低。某些终端节点有额外的速率限制。[进一步了解速率限制]({link})。

用户或群组所有 API 密钥每天 {limit} 个请求

用户或群组所有 API 密钥每小时 {limit} 个请求

用户或群组所有 API 密钥每分钟 {limit} 个请求

用户或群组所有 API 密钥每秒 {limit} 个请求

每个 API 密钥所有者每分钟 {limit} 个请求

每个 App 用户每天 {limit} 个请求

每个 App 用户每小时 {limit} 个请求

每个 App 用户每分钟 {limit} 个请求

每个 App 用户每秒 {limit} 个请求

每个 API 密钥所有者每秒 {limit} 个请求

范围可以控制你的凭据拥有哪些权限。你的凭据只能访问你所选范围支持的终端节点。

稳定终端节点已准备好投入生产使用，在其生命周期内几乎不会发生重大变更。

此目标允许你将密钥的访问权限限制为选定的{requiredParts}

此目标允许你将密钥的访问权限限制为选定的{requiredParts}和{optionalParts}

目标类型用于限制你的凭据可操作的资源。即使你的帐户拥有其他资源的权限，也只能处理选定的资源。某些范围没有目标部件，在这种情况下，你的所有相关资源都可进行操作。

对于用户拥有的 API 密钥，无需选择宇宙顶级部件。在这种情况下，你的 API 密钥可以访问你拥有的所有个人体验，以及你在群组中拥有相应权限的群组体验。

尚不支持试用需要 API 密钥或 OAuth 2.0 验证的终端节点

为了安全起见，已停用高风险操作的 Cookie 验证。

关键风险终端节点非常敏感，为了安全起见，已停用“试用”

注意：此代码示例中不包含验证标头。你可能需要添加验证标头，以便此命令能够正常运作。

这是会修改或删除关键数据的高风险终端节点。测试时要格外小心。

此 API 终端节点已被归类为高风险，可能会影响实时数据或用户帐户。

对高风险 API 的已验证请求可能会进行无法撤销的更改。请在继续之前仔细查看你的请求参数。

这是会取回数据的低风险终端节点。通常可以安全测试。

这是会修改数据的中风险终端节点。请使用非关键帐户仔细测试，因为更改可能是永久性的。

为了确保你帐户的安全，请不要在此处粘贴来自其他来源的文本，或将此页面的信息发送给其他人。

你即将使用实际帐户凭据测试实时 API 终端节点。

只有在你了解即将进行的 API 调用的影响后才能继续。在测试之前，请仔细查看 API 文档。

将使用已验证的会话进行 API 调用

这些是可能影响你帐户或数据的真实 API 调用

某些操作可能会修改或删除数据

此终端节点已被以下推荐的替代终端节点取代：

调用此终端节点需要以下范围。如需
有关生成正确密钥的更多信息，请参阅 [管理 API 密钥]({apiKeyReferenceDocLink})。

如需有关生成密钥的更多信息，请参阅 [管理 API 密钥]({apiKeyReferenceDocLink})。

相对于基础 URL 的路径，下列端点是可用的。

此字符串格式为 [FieldMask](/cloud/reference/types#fieldmask)。

JSON 值可以是 “null”、“boolean”、“string”、“number”、“array” 或 “object”。

你的 OAuth 2.0 应用程序需要以下范围才能使用此终端节点。如需进一步了解如何注册 OAuth 2.0 应用程序，请参阅 [App 注册和审核]({oauth2ReferenceDocLink})。

如需进一步了解如何注册 OAuth 2.0 应用程序，请参阅 [App 注册和审核]({oauth2ReferenceDocLink})。

下列对象描述了接受或返回的有效载荷。请参阅每个单独的端点，以了解更多关于这些对象用途的信息。

调用此终端节点需要以下范围。

资源路径

若要使用此端点，你的 OAuth 2.0 应用程序需要以下范围。关于如何注册 OAuth 2.0 应用程序的更多信息，请查看【应用程序注册及评价】({oauth2ReferenceDocLink})。

不推荐

你正在查看更新后的 Open Cloud 引用。

你已退出新的 Open Cloud 引用。

授予配置账单账户和购买广告点数的权限。

创建、更新和管理你的广告活动。

这将允许查看关于你素材的信息。

这将允许在 Roblox 上传或更新素材。

允许查看你的帐户有权访问的主体（包括群组和体验）和素材。

这将允许向你帐户有权访问的任何主体（包括群组和体验）和素材授予素材权限。

允许代表你查看虚拟形象自动设置任务的状态和结果。

允许代表你创建和管理虚拟形象自动设置任务。

授予更新用户拥有的徽章的能力。

这将允许查看有关你商业项目的信息。

这将允许更改你的同步商业项目。

这将允许查看有关你商户联结平台的信息。

这将允许编辑你的商户联结平台。

这将允许你查看关于你创作者商店产品的信息。

这将允许你修改关于你创作者商店产品的信息。

这将允许你查看关于你创作者商店保存的信息。

这将允许你修改关于你创作者商店保存的信息。

授予代表你创建数据存储的权限。

授予代表你删除数据存储的权限。

授予读取数据存储列表的权限。

授予拍摄数据存储快照的权限。

授予在数据存储中创建条目的权限。

授予标记要删除的指定条目的权限。

授予列出数据存储条目的权限。

授予读取数据存储中指定条目的权限。

授予更新条目的值、属性和用户的权限。

授予删除数据存储条目修订的权限。

授予列出数据存储条目修订的权限。

授予读取数据存储条目修订的权限。

授予查看授权用户的开发者产品配置详细信息的权限。

授予编辑授权用户的开发者产品的权限。

这将允许查看有关你宇宙环境的信息。

授予查看授权用户的游戏通行证配置详细信息的权限。

授予编辑授权用户的游戏通行证的权限。

授予查看你的帐户社区论坛信息的权限。

授予访问权限，允许管理你的帐户对应的社区论坛信息。

这将允许查看有关你社区的信息。

这将允许你管理社区加入请求，并处理你帐户中低级别社区成员的角色更新。

允许你修改实例的属性数据（目前仅支持脚本）。

这将允许查看你的道具栏信息。

授予权限，以管理你的徽章并使用 Robux。

授予更新授权用户徽章的权限。

授予读取你已开启通知的体验信息的权限。

授予代表你开启或关闭体验通知的权限。

授予读取和写入本地化表格的权限

授予为你拥有的所有体验管理团队协作的权限。

授予管理体验和与体验相关的某些信息（例如本地化信息）的权限。

授予读取体验本地化信息的权限。

授予修改体验本地化偏好设置的权限。

授予修改用户本地化偏好设置的权限。

允许你查看关联场景的 Luau 执行任务的状态、日志和结果。

允许你为关联场景创建新的 Luau 执行任务。

授予异步清空宇宙中所有数据结构的权限。

授予从队列前端丢弃已读项目的权限。

授予读取队列前端项目的权限。

授予读取记忆存储项目的权限。

授予创建、更新和删除地图项目的权限。

授予代替用户发布信息的权力。

这将允许从你的体验向用户发送通知。

（已弃用）授予读取有序数据存储中条目列表的权限。

（已弃用）授予在有序数据存储中创建新条目的权限。

授予从有序数据存储中列出条目的权限。

授予在有序数据存储中创建条目的权限。

这将允许列出与你的作品相关联的密钥。

这将允许创作和更新与你的作品相关联的密钥。

此权限允许你提交评估工作并查看工作结果。

授予读取订阅产品信息的权限。

授予创建或修改分析提醒的权限。

授予写入游戏分析相关资源的权限。

授予在 Roblox 上发布新版本体验的权限。

允许读取体验的缩略图和缩略图个性化设置。

允许上传和删除缩略图，并管理体验的缩略图个性化设置。

授予编辑授权用户体验的权限。

允许你查看体验中的用户限制。

允许你编辑体验中的用户限制。

允许查看发送至你帐户的通知。

授予读取用户 Premium 和验证状态的能力。

这将允许你查看授权用户的社交帐户。

这将授予读取你的个人资料信息的权限。

摘要