更新时间：2026-09-02 GMT+08:00

修改参数配置

功能介绍

Elasticsearch集群的核心配置信息都集中在“elasticsearch.yml”和“kibana.yml”文件中，OpenSearch集群的核心配置信息都集中在“opensearch.yml”和“opensearch_dashboards.yml”文件中。当需要根据业务需求调整集群的运行行为时，比如优化查询速度、修改跨域访问配置、调整内部缓存大小或管理后台任务队列等，则可以通过修改参数配置实现。

在使用该接口之前，建议先调用获取参数配置列表，确认集群的参数配置情况，便于根据需求修改参数配置。

接口约束

自定义参数需要配置为Elasticsearch支持的参数，否则集群重启会失败，建议谨慎操作，以免影响业务。

调用方法

请参见如何调用API。

URI

POST /v1.0/{project_id}/clusters/{cluster_id}/ymls/update

表1 路径参数
参数	是否必选	参数类型	描述
project_id	是	String	参数解释：项目ID。获取方法请参见获取项目ID和名称。约束限制：不涉及取值范围：账户的项目ID。默认取值：不涉及
cluster_id	是	String	参数解释：指定修改参数配置的集群ID。获取方法请参见获取集群ID。约束限制：不涉及取值范围：集群ID。默认取值：不涉及

请求参数

表2 请求Body参数
参数	是否必选	参数类型	描述
edit	是	UpdateYmlsReqEdit object	参数解释：配置文件信息。约束限制：不涉及
inst_type	否	String	参数解释：节点类型。约束限制： KooSearch集群涉及不同类型的节点，其他类型集群不涉及。取值范围： kos: KooSearch的搜索中控节点 kos-doc: KooSearch的文档解析节点默认取值：不涉及

表3 UpdateYmlsReqEdit
参数	是否必选	参数类型	描述
modify	否	UpdateYmlsReqEditModify object	参数解释：修改参数配置的操作。约束限制： modify、delete、reset至少一个生效，且每次每个操作仅可使用一次。不能对同种参数同时进行多种操作。
delete	否	UpdateYmlsReqEditModify object	参数解释：删除自定义参数配置的操作。约束限制：与传入的参数值无关。 modify、delete、reset至少一个生效，且每个操作仅可使用一次。不能对同种参数同时进行多种操作。
reset	否	UpdateYmlsReqEditModify object	参数解释：重置参数配置的操作。约束限制：与传入的参数值无关。不支持重置自定义参数。 modify、delete、reset至少一个生效，且每个操作仅可使用一次。不能对同种参数同时进行多种操作。

表4 UpdateYmlsReqEditModify
参数	是否必选	参数类型	描述
elasticsearch.yml	否	Object	参数解释：参数配置列表，值为需要修改的json数据，OpenSearch集群也使用此参数，即修改opensearch.yml时，这里也是填写elasticsearch.yml。约束限制：不涉及
kibana.yml	否	Object	参数解释：参数配置列表，值为需要修改的json数据。OpenSearch集群也使用此参数，即修改opensearch_dashboards.yml时，这里也是填写kibana.yml。约束限制：不涉及

响应参数

状态码：200

表5 响应Body参数
参数	参数类型	描述
acknowledged	Boolean	参数解释：修改参数配置是否成功。取值范围： true: 修改成功。 false: 修改失败。
externalMessage	String	参数解释：错误信息描述。取值范围：当acknowledged为true时，该字段返回null。
httpErrorResponse	String	参数解释： HTTP错误信息，默认为null。取值范围：不涉及

请求示例

修改参数配置。

POST https://{Endpoint}/v1.0/{project_id}/clusters/4f3deec3-efa8-4598-bf91-560aad1377a3/ymls/update

{
  "edit" : {
    "modify" : {
      "elasticsearch.yml" : {
        "thread_pool.force_merge.size" : 1
      }
    }
  }
}

删除自定义参数配置。

POST https://{Endpoint}/v1.0/{project_id}/clusters/4f3deec3-efa8-4598-bf91-560aad1377a3/ymls/update

{
  "edit" : {
    "delete" : {
      "elasticsearch.yml" : {
        "thread_pool.force_merge.size" : 1
      }
    }
  }
}

重置参数配置的操作

POST https://{Endpoint}/v1.0/{project_id}/clusters/4f3deec3-efa8-4598-bf91-560aad1377a3/ymls/update

{
  "edit" : {
    "reset" : {
      "elasticsearch.yml" : {
        "http.cors.allow-credentials" : "false"
      }
    }
  }
}

响应示例

状态码：200

请求成功。

{
  "acknowledged" : true,
  "externalMessage" : null,
  "httpErrorResponse" : null
}

状态码

状态码	描述
200	请求成功。
400	非法请求。建议直接修改该请求，不要重试该请求。
409	服务器在完成请求时发生冲突。返回该状态码，表明客户端尝试创建的资源已经存在，或者由于冲突请求的更新操作不能被完成。
412	未满足前提条件，服务器未满足请求者在请求中设置的其中一个前提条件。

错误码

请参见错误码。

父主题： 参数配置