---
title: "创建或更新存储脚本"
date: 2026-02-24
lastmod: 2026-02-24
description: "创建或更新存储的脚本"
tags: ["脚本", "创建", "存储脚本"]
summary: "在集群中创建或更新存储脚本。
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."
---


在集群中创建或更新存储脚本。

## 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` 的别名，向后兼容） |

## 请求示例

### 创建基本脚本

```json
PUT /_scripts/calculate-score
{
  "script": {
    "lang": "painless",
    "source": "Math.log(_score * 2) + params.multiplier"
  }
}
```

### 创建模板脚本

```json
POST /_scripts/search-template
{
  "script": {
    "lang": "mustache",
    "source": "{\"query\":{\"match\":{\"title\":\"{{query_string}}\"}}}",
    "options": {
      "content_type": "application/json"
    }
  }
}
```

### 创建带上下文的脚本

```json
PUT /_scripts/field-score/score
{
  "script": {
    "lang": "painless",
    "source": "doc['my_field'].value * params.factor"
  }
}
```

### 更新现有脚本

```json
POST /_scripts/calculate-score
{
  "script": {
    "lang": "painless",
    "source": "Math.log(_score * 3) + params.multiplier"
  }
}
```

## 响应示例

### 成功响应

```json
{
  "acknowledged": true
}
```

## 响应字段说明

| 字段 | 类型 | 描述 |
|------|------|------|
| `acknowledged` | Boolean | 脚本创建或更新是否被集群确认 |

## 验证规则

- 脚本 ID 不能为空
- 脚本 ID 不能包含 `#` 字符
- 必须指定脚本语言
- 必须指定脚本源代码
- 空源代码只允许模板脚本（有弃用警告）

## 常用脚本语言

| 语言 | 描述 |
|------|------|
| `painless` | Easysearch 默认脚本语言，安全高效 |
| `mustache` | 用于搜索模板 |
| `expression` | 简单表达式语言 |
| `java` | Java 语言（不推荐） |

## 脚本上下文

脚本上下文决定脚本的编译环境和可用变量：

| 上下文 | 描述 |
|--------|------|
| `score` | 评分脚本，可访问 `_score`、`doc` 等 |
| `filter` | 过滤脚本，用于过滤文档 |
| `field` | 字值脚本，用于计算字段值 |
| `ingest` | 摄入管道脚本 |
| `update` | 更新脚本 |

## 使用场景

1. **脚本复用**：定义可重用的计算逻辑
2. **模板管理**：集中管理搜索模板
3. **评分定制**：自定义文档评分逻辑
4. **字段计算**：定义运行时字段计算

## 注意事项

1. **ID 命名**：脚本 ID 不能包含 `#` 字符
2. **向后兼容**：`code` 字段是 `source` 的别名，为向后兼容保留
3. **模板脚本**：Mustache 模板需要设置 `content_type` 选项
4. **脚本验证**：创建时不会验证脚本的正确性，使用时才会验证

## 相关操作

- **GET /_scripts/{id}**：查询存储脚本
- **DELETE /_scripts/{id}**：删除存储脚本
- **GET /_script_context**：查询支持的脚本上下文
- **GET /_script_language**：查询支持的脚本语言

## 实现文件

- **REST 处理器**：`RestPutStoredScriptAction.java`
- **请求类**：`PutStoredScriptRequest.java`
- **响应类**：`AcknowledgedResponse.java`
- **脚本源**：`StoredScriptSource.java`