在集群中创建或更新存储脚本。
API 格式 #
POST /_scripts/{id}
PUT /_scripts/{id}
POST /_scripts/{id}/{context}
PUT /_scripts/{id}/{context}
API 作用 #
该 API 用于在集群中创建或更新存储脚本：
- 创建新的可重用脚本
- 更新已存在的脚本
- 支持多种脚本语言（如 Painless、Mustache）
- 可指定脚本编译上下文
API 参数 #
路径参数 #
| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|---|---|---|---|---|
{id} | String | 是 | - | 脚本 ID（不能包含 # 字符） |
{context} | String | 否 | - | 脚本编译上下文（如 score、filter） |
查询参数 #
| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|---|---|---|---|---|
timeout | Time | 否 | - | 显式操作超时时间 |
master_timeout | Time | 否 | - | 连接主节点的超时时间 |
请求体参数 #
| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|---|---|---|---|---|
script | Object | 是 | - | 脚本对象 |
script.lang | String | 是 | - | 脚本语言（如 painless、mustache） |
script.source | String | 是 | - | 脚本源代码 |
script.options | Object | 否 | - | 编译器选项（可选） |
script.code | String | 是 | - | 脚本源代码（source 的别名，向后兼容） |
请求示例 #
创建基本脚本 #
PUT /_scripts/calculate-score
{
"script": {
"lang": "painless",
"source": "Math.log(_score * 2) + params.multiplier"
}
}
创建模板脚本 #
POST /_scripts/search-template
{
"script": {
"lang": "mustache",
"source": "{\"query\":{\"match\":{\"title\":\"{{query_string}}\"}}}",
"options": {
"content_type": "application/json"
}
}
}
创建带上下文的脚本 #
PUT /_scripts/field-score/score
{
"script": {
"lang": "painless",
"source": "doc['my_field'].value * params.factor"
}
}
更新现有脚本 #
POST /_scripts/calculate-score
{
"script": {
"lang": "painless",
"source": "Math.log(_score * 3) + params.multiplier"
}
}
响应示例 #
成功响应 #
{
"acknowledged": true
}
响应字段说明 #
| 字段 | 类型 | 描述 |
|---|---|---|
acknowledged | Boolean | 脚本创建或更新是否被集群确认 |
验证规则 #
- 脚本 ID 不能为空
- 脚本 ID 不能包含
#字符 - 必须指定脚本语言
- 必须指定脚本源代码
- 空源代码只允许模板脚本（有弃用警告）
常用脚本语言 #
| 语言 | 描述 |
|---|---|
painless | Easysearch 默认脚本语言，安全高效 |
mustache | 用于搜索模板 |
expression | 简单表达式语言 |
java | Java 语言（不推荐） |
脚本上下文 #
脚本上下文决定脚本的编译环境和可用变量：
| 上下文 | 描述 |
|---|---|
score | 评分脚本，可访问 _score、doc 等 |
filter | 过滤脚本，用于过滤文档 |
field | 字值脚本，用于计算字段值 |
ingest | 摄入管道脚本 |
update | 更新脚本 |
使用场景 #
- 脚本复用：定义可重用的计算逻辑
- 模板管理：集中管理搜索模板
- 评分定制：自定义文档评分逻辑
- 字段计算：定义运行时字段计算
注意事项 #
- ID 命名：脚本 ID 不能包含
#字符 - 向后兼容：
code字段是source的别名，为向后兼容保留 - 模板脚本：Mustache 模板需要设置
content_type选项 - 脚本验证：创建时不会验证脚本的正确性，使用时才会验证
相关操作 #
- GET /_scripts/{id}：查询存储脚本
- DELETE /_scripts/{id}：删除存储脚本
- GET /_script_context：查询支持的脚本上下文
- GET /_script_language：查询支持的脚本语言
实现文件 #
- REST 处理器：
RestPutStoredScriptAction.java - 请求类：
PutStoredScriptRequest.java - 响应类：
AcknowledgedResponse.java - 脚本源：
StoredScriptSource.java
