字串庫提供通用函數以操作字串，例如

提取子字串或匹配模式。你可以通過全局的 `Library.string` 庫訪問字串庫。

詳情請參見

[String pattern reference](/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` 中模式的第一次匹配，並返回 `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

根據定義的分隔符號將字符串拆分為部分，返回一個有序結果的表。

如果找到空的 "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` 的 `s` 的子字符串。`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` 的 `s` 的子字符串，包括 `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

一種值為 true 或 false 的資料類型。

boolean

函數是可以在命令下多次執行的程式碼區塊。

function

number

一系列字元，如字母、數字和符號。

一種可以儲存多個非 nil 類型的值的資料類型，包括布林值、數字、字串、函數和其他表格。

table

體驗

虛擬人偶

素材

範例與專案

引擎 API

開放式雲端 API

Studio

分析

平台

教學

創作者計畫

教育

學習

此方法不同步且會傳回一個「Operation」，代表該操作的目前狀態。其中包含一個端點路徑，您可以輪詢以獲得實際回應和適用的中繼資料。詳情請參閱關於長期執行操作的[說明文件]({longRunningOperationsLink})。
            
以下部分描述操作完成時提供的回應和中繼資料物件。

Beta 測試終點已準備好公開使用。可能出現導致功能無法正常運作的變更，但機率不高。

這些開放式雲端文件頁面將於 2026 年 3 月 31 日移除。屆時，系統會自動將你重新導向至新版開放式雲端文件。{linkStart}瞭解詳情{linkEnd}

這些舊版開放式雲端頁面將於 2026 年 3 月 31 日移除，並重新導向至新頁面。{linkStart}瞭解詳情{linkEnd}

實驗端點已可供公開使用，但隨著 API 合約結束，可能會偶爾發生重大變更。

此終點可在體驗內透過 {httpServiceLinkStart}HttpService{httpServiceLinkEnd} 使用 API 金鑰呼叫。

建立資源時可設定此欄位，但可能無法在後續請求中修改。

建立資源時可設定這些欄位，但可能無法在後續請求中修改。

此欄位可在請求中提供，但永遠不會包含在回應中。

舊版本驗證方法。可用時，請務必使用 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} 次要求數

每位應用程式使用者每日 {limit} 次要求數

每位應用程式使用者每小時 {limit} 次要求數

每位應用程式使用者每分鐘 {limit} 次要求數

每位應用程式使用者每秒 {limit} 次要求數

每位 API 金鑰擁有者每秒 {limit} 次要求數

範圍控制憑證的權限。憑證只能存取你選取的範圍所支援的端點。

穩定終點已準備好投入正式環境，在其生命週期中幾乎不會發生破壞性變更。

此目標可讓你將金鑰存取權限制為所選的{requiredParts}

此目標可讓你將金鑰存取權限制為所選的{requiredParts}和{optionalParts}

目標類型是用來限制憑證對於資源的權限。即使你的帳戶擁有其他資源的權限，也只能對所選資源執行操作。某些操作範圍不包含特定目標部分。在這種情況下，所有相關資源皆可操作。

對於使用者擁有的 API 金鑰，無需選擇宇宙的頂層部分。在這種情況下，你的 API 金鑰將可存取你所擁有的使用者體驗內容，以及你具備正確群組權限的所有群組體驗內容。

「立即試試」功能尚未支援需要 API 金鑰或 OAuth 2.0 驗證的端點

為了安全起見，Cookie 驗證在高風險操作中已停用。

關鍵風險端點極為敏感，為了安全起見，已停用「立即試試」功能

注意：此程式碼範例中不包含驗證標頭資訊。你可能需要為此指令新增驗證標頭，才能正常運作。

這是一個高風險端點，用以修改或刪除關鍵資料。測試時請格外小心。

此 API 端點已被歸類為高風險，且可能會影響即時資料或使用者帳號。

對於高風險 API 的驗證請求，可能會造成無法撤銷的變更。請在繼續之前仔細檢查請求參數。

這是一個低風險端點，用以擷取資料。測試這個端點通常是安全的。

這是一個中等風險端點，用以修改資料。請謹慎地使用非關鍵帳戶測試，因為變更可能是永久性的。

為了確保帳號安全，切勿從其他來源貼上文字，或將此頁面的資訊傳送給其他人。

你即將使用實際帳號憑證來測試已發布的 API 端點。

除非你了解即將進行的 API 呼叫可能涉及的後果，方可繼續操作。在測試之前，請仔細閱讀 API 文件。

API 呼叫將透過你已驗證的工作階段進行

這些皆為實際 API 呼叫，可能會影響你的帳號或資料

部分操作可能會修改或刪除資料

此終點已被這些建議的替代終點取代：

需要以下範圍才能呼叫此端點。若要了解更多
關於產生正確金鑰的資訊，請參閱[管理 API 金鑰]({apiKeyReferenceDocLink})。

若要了解更多關於產生金鑰的資訊，請參閱[管理 API 金鑰]({apiKeyReferenceDocLink})。

根據相對基本網址的路徑，可使用下列終點。

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

JSON 值可為「null」、「boolean」、「string」、「number」、「array」或「object」。

若想使用此端點，您的 OAuth 2.0 應用程式需要以下範圍。有關如何註冊 OAuth 2.0 應用程式的更多資訊，請查看[應用程式註冊和審查]({oauth2ReferenceDocLink})。

若要了解更多關於如何註冊 OAuth 2.0 應用程式的資訊，請參閱[App 註冊與審核]({oauth2ReferenceDocLink})。

以下物件描述被接受或退回的負載。若要獲得更多關於物件使用時機的資訊，請查看個別終點。

需要以下範圍才能呼叫此端點。

資源路徑

此字串的格式為 [Timestamp](/cloud/reference/types#timestamp)。

若想使用此端點，您的 OAuth 2.0 應用程式需要以下範圍。有關如何註冊 OAuth 2.0 應用程式的更多資訊，請查看 [應用程式註冊和審查]（{oauth2ReferenceDocLink}）。

不推薦

你正在檢視新版 Open Cloud 參考資料。

你已選擇退出新版 Open Cloud 參考資料。

授予設定帳務帳號和購買廣告點數的權限。

建立、更新並管理你的廣告活動。

這可以查看有關您資產的資訊。

這可以上傳和更新 Roblox 的資產。

這項操作可讓你查看主體（包括群組和體驗）的素材權限，以及帳號可存取的素材。

這會允許授予素材權限給您的帳號可存取的任何對象（包含群組和體驗）及素材。

這項操作可讓你代為檢視虛擬人偶自動設定工作的狀態和結果。

這項操作可讓你代為建立和管理虛擬人偶自動設定工作。

授予更新使用者所擁有之徽章的能力。

這會允許查看您商品的相關資訊。

這麼做可對已同步的商品進行變更。

此操作可讓你檢視商務聯絡對象的資訊。

這會允許對您的商務商家連結進行編輯。

這能讓您檢視您創作者商店商品的相關資訊。

這能讓您修改您創作者商店商品的相關資訊。

這項操作可以讓你查看創作者商店儲存項目的相關資訊。

這項操作可讓你修改創作者商店儲存項目的相關資訊。

授予代為建立資料存儲的存取權。

授予代為刪除資料存儲的權限。

授予讀取資料存儲清單的存取權。

授予為資料存儲拍攝快照的存取權。

授予在資料存儲中建立條目的存取權。

授予標記指定條目以進行刪除的存取權。

授予可列出資料存儲項目的存取權。

授予在資料存儲中讀取指定條目的存取權。

授予更新項目值、屬性和使用者的存取權。

授予可刪除資料存儲條目修訂版的存取權。

授予可列出資料存儲條目修訂版的存取權。

授予可讀取資料存儲條目修訂版的存取權。

授予檢視授權使用者開發者產品設定詳細資訊的權限。

授予編輯授權使用者開發者產品的權限。

這會允許查看您宇宙環境的相關資訊。

授予檢視授權使用者遊戲通行證設定詳細資訊的權限。

授予編輯授權使用者遊戲通行證的權限。

授予檢視帳號社群論壇資訊的權限。

授予管理帳號社群論壇資訊的權限。

這會允許查看您社群的相關資訊。

這能讓您管理自己帳號的社群加入申請和低階社群成員的角色更新。

允許你修改個體的屬性資料（目前僅支援指令碼）。

這可以查看有關您道具欄的資訊。

授予管理使用者資產的存取權。

授予管理您徽章和花費 Robux 的權限。

授予更新授權使用者徽章的權限。

授予管理您開發者產品的權限。

授予存取權限，以讀取你已開啟通知的體驗相關資訊。

授予存取權限，代你開啟或關閉體驗通知。

授予讀取與寫入您在地化表格的權限。

授予管理您擁有之所有體驗的團隊協作權限。

授予管理您的體驗及部分體驗相關資訊（例如：在地化資訊）的權限。

授予讀取您體驗之在地化資訊的權限。

授予修改您體驗在地化偏好的權限。

授予管理您使用者帳號的權限。

授予修改使用者在地化偏好的權限。

允許你檢視關聯地點的 Luau 執行任務狀態、紀錄和結果。

允許你為關聯地點建立新的 Luau 執行任務。

授予非同步清除宇宙中所有資料結構的存取權。

授予建立新佇列項目的存取權。

授予從佇列前端捨棄讀取項目的存取權。

授予從佇列前端讀取項目的權限。

授予讀取記憶存儲項目的存取權。

授予建立、更新和刪除地圖項目的存取權。

給予代替使用者發布訊息的能力。

這能讓您的體驗向使用者傳送通知。

（棄用）授予在已排序資料存儲中讀取條目清單的存取權。

（棄用）授予在已排序資料存儲中建立新條目的存取權。

授予從已排序資料存儲中列出條目的存取權。

授予在已排序資料存儲中建立條目的存取權。

此將允許列出與您的體驗相關的機密資料。

此將允許建立並更新與您的體驗相關的機密資料。

此權限可讓你提交評估工作，並檢視工作結果。

授予讀取您訂閱產品相關資訊的權限。

這項操作可讓你代為讀取縮圖資訊。

授予建立或修改分析提醒的能力。

授予寫入遊戲分析相關資源的能力。

授予發佈新版本體驗到 Roblox 的權限。

這項操作可讓你讀取體驗的縮圖和縮圖個人化設定。

這項操作可讓你上傳和刪除體驗的縮圖，並管理縮圖個人化設定。

授予編輯授權使用者體驗的權限。

讓您檢視體驗中的使用者限制。

讓您在體驗中編輯使用者限制。

這項操作將允許檢視傳送至你帳號的通知。

授予讀取權限，查看授權使用者的高級會員與驗證狀態。

此舉可以讓你查看授權使用者的社群帳號。

這將授予讀取您個人檔案資訊的權限。

概要