查询集群详情_云搜索服务 CSS_API参考_集群管理接口_华为云

(1)

API 参考

文档版本 13

发布日期 2021-12-31

(2)

非经本公司书面许可，任何单位和个人不得擅自摘抄、复制本文档内容的部分或全部，并不得以任何形式传播。

商标声明

和其他华为商标均为华为技术有限公司的商标。

本文档提及的其他所有商标或注册商标，由各自的所有人拥有。

注意

您购买的产品、服务或特性等应受华为公司商业合同和条款的约束，本文档中描述的全部或部分产品、服务或特性可能不在您的购买或使用范围之内。除非合同另有约定，华为公司对本文档内容不做任何明示或暗示的声明或保证。

由于产品版本升级或其他原因，本文档内容会不定期进行更新。除非另有约定，本文档仅作为使用指导，本文档中的所有陈述、信息和建议不构成任何明示或暗示的担保。

华为技术有限公司

地址：深圳市龙岗区坂田华为总部办公楼邮编：518129

网址：

https://www.huawei.com

客户服务邮箱：

[email protected]

客户服务电话：4008302118

(3)

1 ^{使用前必读}

1.1 概述

欢迎使用云搜索服务（Cloud Search Service，简称CSS）。云搜索服务为您提供托管的分布式搜索引擎服务，完全兼容开源Elasticsearch搜索引擎，支持结构化、非结构化文本的多条件检索、统计、报表。

本文档提供了云搜索服务（Cloud Search Service，简称CSS）API的描述、语法、参数说明及样例等内容。云搜索服务提供了集群管理接口、词库管理接口和快照管理接口，通过配合使用这些接口，您可以轻松的对云搜索服务的集群、词库和快照进行管理和使用。

类型说明

集群管理接口您可以通过接口创建集群、扩容集群、查看集群详情、获取实例规格列表等操作。

词库管理接口云搜索服务提供自定义词库功能，您可以通过接口加载自定义库、查询词库状态或删除自定义词库。

快照管理接口快照功能可应用于数据备份与恢复，您可以通过接口创建快照、恢复快照或者删除快照等。

您可以使用本文档提供API对云搜索服务进行相关操作，如创建、查询、删除、重启、

扩容集群等。

在调用云搜索服务API之前，请确保已经充分了解云搜索服务相关概念，详细信息请参见产品介绍。

1.2 调用说明

云搜索服务提供了REST（Representational State Transfer）风格API，支持您通过 HTTPS请求调用，调用方法请参见如何调用API。

(6)

1.3 终端节点

终端节点即调用API的请求地址，不同服务不同区域的终端节点不同，您可以从地区和

终端节点中查询所有服务的终端节点。

1.4 约束与限制

● 您能创建的CSS集群数量与配额有关系，如果您想查看服务配额、扩大配额，具体请参见服务配额。

● 更详细的限制请参见具体API说明。

1.5 基本概念

● 账号

用户注册时的账号，账号对其所拥有的资源及云服务具有完全的访问权限，可以重置用户密码、分配用户权限等。由于账号是付费主体，为了确保账号安全，建议您不要直接使用账号进行日常管理工作，而是创建用户并使用他们进行日常管理工作。

● 用户

由账号在IAM中创建的用户，是云服务的使用人员，具有身份凭证（密码和访问密钥）。

在我的凭证下，您可以查看账号ID和用户ID。通常在调用API的鉴权过程中，您需要用到账号、用户和密码等信息。

● 区域

指云资源所在的物理位置，同一区域内可用区间内网互通，不同区域间内网不互通。通过在不同地区创建云资源，可以将应用程序设计的更接近特定客户的要求，或满足不同地区的法律或其他要求。

● 可用区

一个可用区是一个或多个物理数据中心的集合，有独立的风火水电，AZ内逻辑上再将计算、网络、存储等资源划分成多个集群。一个Region中的多个AZ间通过高速光纤相连，以满足用户跨AZ构建高可用性系统的需求。

● 项目

区域默认对应一个项目，这个项目由系统预置，用来隔离物理区域间的资源（计算资源、存储资源和网络资源），以默认项目为单位进行授权，用户可以访问您账号中该区域的所有资源。如果您希望进行更加精细的权限控制，可以在区域默认的项目中创建子项目，并在子项目中购买资源，然后以子项目为单位进行授权，使得用户仅能访问特定子项目中资源，使得资源的权限控制更加精确。

(7)

图1-1 项目隔离模型

● Checkpoint：消费检查点。应用程序消费数据时，记录已消费数据的最新序列号作为检查点。当重新消费数据时，可根据此检查点继续消费。

● APP：应用程序标识符。当多个应用程序分别消费同一通道的数据时，为区分不同应用程序的消费检查点，使用APP作为标识。

● 企业项目

企业项目是项目的升级版，针对企业不同项目间资源的分组和管理，是逻辑隔离。企业项目中可以包含多个区域的资源，且项目中的资源可以迁入迁出。

关于企业项目ID的获取及企业项目特性的详细信息，请参见《企业管理服务用户

指南》。

1.6 API 版本选择建议

云搜索服务中Elasticsearch搜索引擎目前支持Elasticsearch 5.5.1、6.2.3、6.5.4、

7.1.1、7.6.2和7.9.3版本，Kibana目前支持5.5.1、6.2.3、6.5.4、7.1.1、7.6.2和7.9.3版本。

(8)

2 ^{API 概览}

CSS提供的接口为符合RESTful API设计规范的自研接口。通过CSS的自研接口，您可以使用CSS的如表2-1所示的功能。

表2-1 接口功能

接口功能 API URI

集群管理接口

创建集群

POST /v1.0/{project_id}/clusters

查询集群列表

GET /v1.0/{project_id}/clusters

查询集群详情

GET /v1.0/{project_id}/clusters/{cluster_id}

删除集群

DELETE /v1.0/{project_id}/clusters/{cluster_id}

重启集群

POST /v1.0/{project_id}/clusters/{cluster_id}/restart

扩容集群

POST /v1.0/{project_id}/clusters/{cluster_id}/extend

扩容实例的数量和存储容量

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

role_extend

获取实例规格列表

GET /v1.0/{project_id}/es-flavors

集群管理接口

查询指定集群的标签

GET /v1.0/{project_id}/css-cluster/{cluster_id}/tags

查询所有标签

GET /v1.0/{project_id}/css-cluster/tags

添加集群标签

POST /v1.0/{project_id}/css-cluster/{cluster_id}/tags

批量添加或删除集群标签

POST /v1.0/{project_id}/css-cluster/{cluster_id}/tags/

action

删除集群指定标签

DELETE /v1.0/{project_id}/css-cluster/{cluster_id}/

tags/{key}

词库管理接口（IK 分词）

加载自定义词库

thesaurus

查询自定义词库状态

GET /v1.0/{project_id}/clusters/{cluster_id}/

thesaurus

(9)

接口功能 API URI

删除自定义词库

DELETE /v1.0/{project_id}/clusters/{cluster_id}/

thesaurus

快照管理接口

自动设置集群快照的基础配置（不推荐使用）

index_snapshot/auto_setting

修改集群快照的基础配置

index_snapshot/setting

设置自动创建快照策略

index_snapshot/policy

查询集群的自动创建快照策略

index_snapshot/policy

手动创建快照

index_snapshot

查询快照列表

index_snapshots

恢复快照

index_snapshot/{snapshot_id}/restore

删除快照

index_snapshot/{snapshot_id}

停用快照功能

index_snapshots

(10)

3 ^{如何调用 API}

3.1 构造请求

本节介绍REST API请求的组成，以调用获取用户Token接口说明如何调用API，该API 获取用户的Token，Token是用户的访问令牌，承载身份与权限信息，Token可以用于调用其他API时鉴权。

您还可以通过这个视频教程了解如何构造请求调用API：https://

bbs.huaweicloud.com/videos/102987 。

请求 URI

请求URI由如下部分组成。

{URI-scheme}://{Endpoint}/{resource-path}?{query-string}

表3-1 请求 URL

参数说明

URI-scheme 传输请求的协议，当前所有API均采用HTTPS协议。

Endpoint 承载REST服务端点的服务器域名或IP，不同服务在不同区域，

Endpoint不同，可以从地区和终端节点中获取。例如IAM服务在

“华北-北京一”区域的Endpoint为“iam.cn- north-1.myhuaweicloud.com”。

resource-

path 资源路径，即API访问路径。从具体API的URI模块获取，例如“获取用户Token”API的resource-path为“/v3/auth/tokens”。

query-string 查询参数，可选，查询参数前面需要带一个“？”，形式为“参数名=参数取值”，例如“limit=10”，表示查询不超过10条数据。

例如您需要获取“华北-北京一”区域的Token，则需使用“华北-北京一”区域的 Endpoint（iam.cn-north-1.myhuaweicloud.com），并在获取用户Token的URI部分找到resource-path（/v3/auth/tokens），拼接起来如下所示。

(11)

https://iam.cn-north-1.myhuaweicloud.com/v3/auth/tokens

图3-1 URI 示意图

说明

为查看方便，每个具体API的URI，只给出resource-path部分，并将请求方法写在一起。这是因为URI-scheme都是HTTPS，而Endpoint在同一个区域也相同，所以简洁起见将这两部分省略。

请求方法

HTTP请求方法（也称为操作或动词），它告诉服务你正在请求什么类型的操作。

● GET：请求服务器返回指定资源。

● PUT：请求服务器更新指定资源。

● POST：请求服务器新增资源或执行特殊操作。

● DELETE：请求服务器删除指定资源，如删除对象等。

● HEAD：请求服务器资源头部。

● PATCH：请求服务器更新资源的部分内容。当资源不存在的时候，PATCH可能会 去创建一个新的资源。

在获取用户Token的URI部分，您可以看到其请求方法为“POST”，则其请求为：

POST https://iam.cn-north-1.myhuaweicloud.com/v3/auth/tokens

请求消息头

附加请求头字段，如指定的URI和HTTP方法所要求的字段。例如定义消息体类型的请求头“Content-Type”，请求鉴权信息等。

如下公共消息头需要添加到请求中。

● Content-Type：消息体的类型（格式），必选，默认取值为“application/

json”。

● X-Auth-Token：用户Token，可选，当使用Token方式认证时，必须填充该字 段。X-Auth-Token是调用获取用户Token接口返回的响应值，该接口功能为获取 Token，因此调用该接口时，不用填写本字段。

说明

公有云API同时支持使用AK/SK认证，AK/SK认证是使用SDK对请求进行签名，签名过程会自动往请求中添加Authorization（签名认证信息）和X-Sdk-Date（请求发送的时间）请求头。AK/SK认证的详细说明请参见：AK/SK认证。

对于获取用户Token接口，由于不需要认证，所以只添加“Content-Type”即可，添加消息头后的请求如下所示。

POST https://iam.cn-north-1.myhuaweicloud.com/v3/auth/tokens Content-Type: application/json

(12)

请求消息体

请求消息体通常以结构化格式发出，与请求消息头中Content-type对应，传递除请求消息头之外的内容。若请求消息体中参数支持中文，则中文字符必须为UTF-8编码。

每个接口的请求消息体内容不同，也并不是每个接口都需要有请求消息体（或者说消息体为空），GET、DELETE操作类型的接口就不需要消息体，消息体具体内容需要根据具体接口而定。

对于获取用户Token接口，您可以从接口的请求部分看到所需的请求参数及参数说明。将消息体加入后的请求如下所示，加粗的斜体字段需要根据实际值填写，其中

username

为用户名，

********

为用户的登录密码，domainnname为用户所属的账号名称，如果是账号本身获取token，

username

和

domainname

填为一致，

xxxxxxxxxxxxxxxxxx

为project的ID，获取方法请参见获取项目ID。

说明

scope参数定义了Token的作用范围，取值为project，示例中取值为project，表示获取的Token 仅能访问指定project下的资源，scope参数的详细说明，请参见：获取用户Token。

POST https://iam.cn-north-1.myhuaweicloud.com/v3/auth/tokens Content-Type: application/json

{ "auth": { "identity": { "methods": [ "password"

],

"password": { "user": {

"name": "username", "password": "********", "domain": {

"name": "domainname "

} } } }, "scope": { "project": {

"id": "xxxxxxxxxxxxxxxxxx"

} } } }

到这里为止这个请求需要的内容就具备齐全了，您可以使用curl、Postman或直接编写代码等方式发送请求调用API。对于获取用户Token接口，返回的响应消息头中“x- subject-token”就是需要获取的用户Token。有了Token之后，您就可以使用Token认证调用其他API。

3.2 认证鉴权

调用接口有如下两种认证方式，您可以选择其中一种进行认证鉴权。

● Token认证：通过Token认证通用请求。

● AK/SK认证：通过AK（Access Key ID）/SK（Secret Access Key)加密调用请求。

(13)

Token 认证

说明

Token的有效期为24小时，需要使用同一个Token鉴权时，可以缓存起来，避免频繁调用。

Token在计算机系统中代表令牌（临时）的意思，拥有Token就代表拥有某种权限。

Token认证就是在调用API的时候将Token加到请求消息头，从而通过身份认证，获得操作API的权限。

Token可通过调用获取用户Token接口获取，调用本服务API需要project级别的 Token，即调用获取用户Token接口时，请求body中“auth.scope”的取值需要选择

“project”，如下所示。

{ "auth": { "identity": { "methods": [ "password"

],

"password": { "user": {

"name": "username", "password": "********", "domain": {

"name": "domainname"

} } } }, "scope": { "project": {

"name": "xxxxxxxx"

} } } }

获取Token后，再调用其他接口时，您需要在请求消息头中添加“X-Auth-Token”，

其值即为Token。例如Token值为“ABCDEFJ....”，则调用接口时将“X-Auth-Token:

ABCDEFJ....”加到请求消息头即可，如下所示。

GET https://iam.cn-north-1.myhuaweicloud.com/v3/auth/projects Content-Type: application/json

X-Auth-Token: ABCDEFJ....

您还可以通过这个视频教程了解如何使用Token认证：https://

bbs.huaweicloud.com/videos/101333 。

AK/SK 认证

说明

AK/SK签名认证方式仅支持消息体大小12MB以内，12MB以上的请求请使用Token认证。

AK/SK认证就是使用AK/SK对请求进行签名，在请求时将签名信息添加到消息头，从而通过身份认证。

● AK(Access Key ID)：访问密钥ID。与私有访问密钥关联的唯一标识符；访问密钥 ID和私有访问密钥一起使用，对请求进行加密签名。

● SK(Secret Access Key)：与访问密钥ID结合使用的密钥，对请求进行加密签名，

可标识发送方，并防止请求被修改。

(14)

使用AK/SK认证时，您可以基于签名算法使用AK/SK对请求进行签名，也可以使用专门的签名SDK对请求进行签名。详细的签名方法和SDK使用方法请参见API签名指南。

须知

签名SDK只提供签名功能，与服务提供的SDK不同，使用时请注意。

3.3 返回结果

状态码

请求发送以后，您会收到响应，包含状态码、响应消息头和消息体。

状态码是一组从1xx到5xx的数字代码，状态码表示了请求响应的状态，完整的状态码列表请参见状态码。

对于获取用户Token接口，如果调用后返回状态码为“201”，则表示请求成功。

响应消息头

对应请求消息头，响应同样也有消息头，如“Content-type”。

对于获取用户Token接口，返回如图1所示的消息头，其中“x-subject-token”就是需要获取的用户Token。有了Token之后，您就可以使用Token认证调用其他API。

图3-2 获取用户 Token 响应消息头

响应消息体

响应消息体通常以结构化格式返回，与响应消息头中Content-type对应，传递除响应消息头之外的内容。

对于获取用户Token接口，返回如下消息体。为篇幅起见，这里只展示部分内容。

(15)

{ "token": {

"expires_at": "2019-02-13T06:52:13.855000Z", "methods": [

"password"

],

"catalog": [ {

"endpoints": [ {

"region_id": "az-01", ...

当接口调用出错时，会返回错误码及错误信息说明，错误响应的Body体格式如下所示。

{ "error_msg": "The format of message is error", "error_code": "AS.0001"

}

其中，error_code表示错误码，error_msg表示错误描述信息。

(16)

4 ^快速入门

本节通过调用云搜索服务的API创建CSS服务集群，CSS的接口调用流程如图4-1所示。

图4-1 接口调用流程

说明

通过IAM服务获取到的Token有效期为24小时，需要使用同一个Token鉴权时，可以先将Token 缓存，避免频繁调用。

(17)

涉及 API

当您使用Token认证方式完成认证鉴权时，需要获取用户Token并在调用接口时增加

“X-Auth-Token”到业务接口请求消息头中。

● IAM获取token的API

● CSS创建集群的API

具体步骤

1. 发送“POST https://IAM的Endpoint/v3/auth/tokens”。

– Token认证，具体操作请参考Token认证。

– 获取IAM的Endpoint。

–

获取用户Token

2. 在Request Header中增加“X-Auth-Token”和“Content-type ”。

– Content-Type：消息体的类型（格式），默认取值为“application/json”。

– X-Auth-Token：用户Token。用户Token也就是步骤1调用获取用户Token接 口的响应值，该接口是唯一不需要认证的接口。

3. 在Request Body中传入参数如下：

POST /v1.0/6204a5bd270343b5885144cf9c8c158d/clusters { "cluster": {

"name": "ES-Test", "backupStrategy": {

"period": "16:00 GMT+08:00", "prefix": "snapshot",

"keepday": 7 },

"instanceNum": 3, "instance": {

"flavorRef": "ess.spec-2u16g", "volume": {

"volume_type": "COMMON", "size": 100

}, "nics": {

"vpcId": "fccd753c-91c3-40e2-852f-5ddf76d1a1b2", "netId": "af1c65ae-c494-4e24-acd8-81d6b355c9f1",

"securityGroupId": "7e3fed21-1a44-4101-ab29-34e57124f614"

} } } }

响应消息样例。

{ "cluster": {

"id": "ef683016-871e-48bc-bf93-74a29d60d214", "name": "ES-Test"

}}

请求响应成功后，返回200 OK，表示集群创建成功。

若请求失败，则会返回错误码及对应的错误信息说明，详细错误码信息请参考状

态码。

(18)

5 ^{集群管理接口}

5.1 创建集群

功能介绍

该接口用于创建集群。

URI

POST /v1.0/{project_id}/clusters

表5-1 参数说明

参数是否为必选类型说明

project_id 是 String 项目编号。详细请参考获取项目ID/

账号ID。

请求消息

请求参数如表5-2所示。

表5-2 请求参数

cluster 是 Object 集群对象。详细参数请参见表5-3。

表5-3 cluster 字段要素说明

instance 是 Object 实例对象。详细参数请参见表5-4。

(19)

datastore 是 Object 数据搜索引擎类型。详细参数请参见表

5-7 。

name 是 String 集群名称。4～32个字符，只能包含数字、字母、中划线和下划线，且必须以字母开头。

instanceNu

m 是 Integer 集群实例个数，取值范围为1~32。

backupStrat

egy 否 Object 开启自动创建快照策略。默认关闭。详细参数请参见表5-8。

说明当backupStrategy参数配置不为空时，才会开

启自动创建快照策略。

httpsEnable 否 boolean 设置是否进行通信加密。取值范围为true 或false。默认关闭通信加密功能。当 httpsEnable设置为true时，

authorityEnable字段需要设置为true。

● true：表示集群进行通信加密。

● false：表示集群不进行通信加密。

说明此参数只有6.5.4及之后版本支持。

authorityEna

ble 否 boolean 是否开启认证，取值范围为true或false。

默认关闭认证功能。当开启认证时，

httpsEnable需要设置为true。

● true：表示集群开启认证。

● false：表示集群不开启认证。

说明此参数只有6.5.4及之后版本支持。

adminPwd 否 String 安全模式下集群管理员admin的密码，只有当authorityEnable设置为true时需要设置此参数。

说明

● 管理员密码需要满足规则：

● 可输入的字符串长度为8-32个字符。

● 密码至少包含大写字母，小写字母，

数字和特殊字符中的三类，其中可输入的特殊字符为：~!@#$%^&*()-_=+

\\|[{}];:,<.>/?。

● 安全集群的密码会进行弱口令校验，建议设置安全性高的密码。

(20)

参数是否为必选类型说明 enterprise_p

roject_id 否 String 企业项目ID。创建集群时，给集群绑定企业项目ID。最大长度36个字符，带"-"连字符的UUID格式，或者是字符串"0"。

"0"表示默认企业项目。

说明关于企业项目ID的获取及企业项目特性的详细

信息，请参见《企业管理服务用户指南》。

tags 否 Array of

tag

objects

集群标签。

说明

关于标签特性的详细信息，请参见《标签管理产品介绍》。

表5-4 instance 字段要素说明

参数是否为必

选

类型说明

flavorRef 是 String 实例规格名称。例如，

● ess.spec-2u16g规格对应的取值范围为40GB

～1280GB。

～2560GB。

～5120GB。

● ess.spec-16u128g规格对应的取值范围为 160GB～10240GB。

volume 否 Object 当flavorRef选择的是本地盘规格时不需要填写，本地盘规格可以通过获取实例规格列表接口获取。目前支持的本地盘规格有：

● ess.spec-i3small

● ess.spec-i3medium

● ess.spec-i3.8xlarge.8

● ess.spec-ds.xlarge.8

● ess.spec-ds.2xlarge.8

● ess.spec-ds.4xlarge.8

volume信息。详细参数请参见表5-5。

nics 是 Object 子网信息。详细参数请参见表5-6。

(21)

参数是否为必选

类型说明

availability

_zone 否 String 可用区。不填时默认创建单AZ。

如果需要创建多AZ，各个AZ之间使用英文逗号分隔，比如az1,az2 ，az不能重复输入，并且要求节点个数大于等于AZ个数。

如果节点个数为AZ个数的倍数，节点将会均匀的分布到各个AZ。如果节点个数不为AZ个数的倍数时，各个AZ分布的节点个数之和的绝对值之差小于等于1。

表5-5 volume 字段要素说明

参数是否为必

选

类型说明

volume_ty

pe 是 String COMMON：普通I/O。

HIGH：高I/O。

ULTRAHIGH：超高I/O。

size 是 Integer 卷大小，必须为4和10的倍数。

单位：GB。

表5-6 nics 字段要素说明

参数是否为必

选

类型说明

vpcId 是 String 指定虚拟私有云ID，用于集群网络配置。

netId 是 String 子网ID(网络ID)，其中一个搜索集群所有实例的子网和安全组必须相同。

securityGr

oupId 是 String 安全组ID，其中一个搜索集群所有实例的子网和安全组必须相同。

表5-7 datastore 字段要素说明

参数是否为必

选

类型说明

version 是 String 引擎版本号，支持5.5.1、6.2.3、6.5.4、7.1.1、

7.6.2和7.9.3，默认为5.5.1。

type 是 String 引擎类型，默认为elasticsearch。目前只支持 elasticsearch。

(22)

表5-8 backupStrategy 字段要素说明

参数是否为必

选

类型说明

period 是 String 每天创建快照的时刻，只支持整点，后面需加上时区，格式为“HH:mm z”，“HH:mm”

表示整点时间，“z”表示时区。比如“00:00 GMT+08:00”、“01:00 GMT+08:00”等。

prefix 是 String 自动创建的快照的前缀。

keepday 是 Integer 自动创建快照的保留天数。

取值范围：1-90。

bucket 否 String 备份使用的OBS桶名称，如果桶已经存放快照数据了，不可更改。

basePath 否 String 快照在OBS桶中的存放路径。

agency 否 String 访问OBS使用的IAM委托名称。

说明如果bucket、basePath和agency三个参数同时为空，则系统会自动创建OBS桶和IAM代理，否则使用配置的参数值。

表5-9 tags 字段要素说明

参数是否为必

选类型说明

key 是 String 集群标签的key值。可输入的字符串长度为 1~36个字符。只能包含数字、字母、中划线

"-"和下划线"_"。

value 是 String 集群标签的value值。可输入的字符串长度为 0~43个字符。只能包含数字、字母、中划线

"-"和下划线"_"。

响应消息

响应参数如表5-10所示。

表5-10 响应参数

参数类型说明

cluster Object 集群对象。详细请参见表5-11。

(23)

表5-11 cluster 字段要素说明

参数类型说明

id String 集群ID。

name String 集群名称。

示例

请求样例

{ "cluster": {

"name": "ES-Test", "instanceNum": 1, "instance": {

"availability_zone": "cn-north-7c", "flavorRef": "ess.spec-2u8g", "volume": {

"volume_type": "HIGH", "size": 40

}, "nics": {

"vpcId": "07e7ab39-6df8-4298-863f-d3f28ea7f001", "netId": "025d45f9-cbcb-4ad5-8345-e882c6455a5e",

"securityGroupId": "0347aabc-6371-4fb9-ab34-6b19a79701e2"

} },

"datastore": { "version": "7.6.2", "type": "elasticsearch"

},

"backupStrategy": { "prefix": "snapshot",

"period": "18:00 GMT+08:00", "keepday": 1

},

"httpsEnable": true, "authorityEnable": true, "adminPwd": "12334fdsf@"

} }

响应样例{ "cluster": {

"id": "ef683016-871e-48bc-bf93-74a29d60d214", "name": "ES-Test"

}}

状态码

状态码如表5-12所示。

(24)

表5-12 状态码

状态码编码状态码说明

400 BadRequest 非法请求。

建议直接修改该请求，不要重试该请求。

409 Conflict 服务器在完成请求时发生冲突。

返回该状态码，表明客户端尝试创建的资源已经存在，或者由于冲突请求的更新操作不能被完成。

412 Precondition Failed 未满足前提条件，服务器未满足请求者在请求中设置的其中一个前提条件。

200 OK 请求已成功。

5.2 查询集群列表

功能介绍

该接口用于查询并显示集群列表以及集群的状态。

URI

GET /v1.0/{project_id}/clusters

表5-13 参数说明

账号ID。

start 否 Integer 指定查询起始值，默认值为1，即从第1个集群开始查询。

limit 否 Integer 指定查询个数，默认值为10，即一次查询10个集群信息。

请求消息

无。

响应消息

(25)

表5-14 响应参数

参数类型说明

clusters Array of

clusters

objects

集群对象列表。

表5-15 clusters 字段数据结构说明

参数类型说明

datastore Object 数据搜索引擎类型。详细请参考表

5-16。

instances Array of instance

objects 节点对象列表。

updated String 集群上次修改时间，格式为ISO8601:

CCYY-MM-DDThh:mm:ss。

created String 集群创建时间，格式为ISO8601: CCYY- MM-DDThh:mm:ss。

说明

返回的集群列表信息按照创建时间降序排序，即创建时间最新的集群排在最前。

status String 查询返回值。

● 100：创建中。

● 200：可用。

● 303：不可用，如创建失败。

endpoint String 用户VPC访问IP地址和端口号。

actionProgress Object 集群行为进度，显示创建和扩容进度的百分比。CREATING表示创建的百分比。

actions Array of strings 集群当前行为，REBOOTING表示重启，GROWING表示扩容，RESTORING 表示恢复集群，SNAPSHOTTING表示创建快照。

failed_reasons Object 失败原因。如果集群处于正常状态，则不返回该参数。详细请参考表5-18。

(26)

参数类型说明

authorityEnable String 是否开启认证，取值范围为true或 false。默认关闭认证功能。当开启认证时，httpsEnable需要设置为true。

vpcId String VPC ID。

subnetId String 子网ID。

securityGroupId String 安全组ID。

enterprise_project_

id String 集群所属的企业项目ID。

如果集群所属用户没有开通企业项目，

则不会返回该参数。

tags Array of tag

objects 集群标签。

表5-16 datastore 字段数据结构说明

参数类型说明

type String 支持类型：elasticsearch。

version String 引擎版本号。当前引擎版本为5.5.1、

6.2.3、6.5.4、7.1.1、7.6.2、7.9.3。

表5-17 instances 字段数据结构说明

参数类型说明

type String 支持类型：ess（Elasticsearch节点）。

id String 实例ID。

name String 实例名字。

status String 状态。

● 100：创建中。

● 200：可用。

specCode String 节点规格名称。

azCode String 节点所属AZ信息。

(27)

表5-18 failed_reasons 字段数据结构说明

参数类型说明

error_code String 错误码。

● CSS.6000：表示集群创建失败。

● CSS.6001：表示集群扩容失败。

● CSS.6002：表示集群重启失败。

● CSS.6004：表示集群节点创建失败。

● CSS.6005：表示服务初始化失败。

error_msg String 详细错误信息。

表5-19 tags 字段数据结构说明

参数类型说明

key String 集群标签的key值。

value String 集群标签的value值。

示例

● 请求样例

– 查询请求样例，默认最多查询10个集群。

GET /v1.0/6204a5bd270343b5885144cf9c8c158d/clusters

– 分页查询请求样例

示例一：查询前2个集群。

方法1

GET /v1.0/6204a5bd270343b5885144cf9c8c158d/clusters?start=1&limit=2

方法2GET /v1.0/6204a5bd270343b5885144cf9c8c158d/clusters?limit=2

示例二：查询前10个集群。

方法1GET /v1.0/6204a5bd270343b5885144cf9c8c158d/clusters?start=1&limit=10

方法2GET /v1.0/6204a5bd270343b5885144cf9c8c158d/clusters?start=1

● 响应样例

{ "clusters": [ {

"datastore": {

"type": "elasticsearch", "version": "6.2.3"

},

"instances": [ {

"status": "200", "type": "ess",

"id": "a8922be2-5e41-4cd1-8486-630c04c2d1e3",

(28)

"name": "ES-new1-ess-esn-1-1"

} ],

"updated": "2017-11-27T10:36:18", "name": "ES-new1",

"created": "2017-11-27T10:36:18",

"id": "306e5597-d7a9-4cbe-866c-33428440d0e3", "status": "200",

"endpoint": "192.168.0.219:9200", "actionProgress": {

"CREATING": "5%"

},

"actions": [],

"enterprise_project_id":"3e1c74a0-86a0-40e9-bdc9-c6b9e46cf81b", "tags": []

}, {

"datastore": {

},

"instances": [ {

"status": "200", "type": "ess",

"id": "9635de45-895c-45e1-ba0b-d9f497c8ce52", "name": "Es-Test1-ess-esn-1-1"

} ],

"updated": "2017-11-14T12:32:00", "name": "Es-Test1",

"created": "2017-11-14T12:32:00",

"id": "c99b1514-647e-4418-8b6d-2748255f2f95", "status": "200",

"endpoint": "192.168.0.127:9200", "actionProgress": {},

"actions": [ "REBOOTING"

],

"enterprise_project_id":"0", "tags": [

{

"key": "k1", "value": "v1"

}, {

"key": "k2", "value":"v2"

} ] } ]}

状态码

表5-20 状态码

(29)

404 NotFound 所请求的资源不存在。

5.3 查询集群详情

功能介绍

该接口用于查询并显示单个集群详情。

URI

GET /v1.0/{project_id}/clusters/{cluster_id}

表5-21 参数说明

账号ID。

cluster_id 是 String 指定查询集群ID。

请求消息

无。

响应消息

表5-22 响应参数

参数类型说明

datastore Object 数据搜索引擎类型。详细请参考表5-23。

objects 节点对象列表。

updated String 集群上次修改时间，格式为ISO8601: CCYY-MM- DDThh:mm:ss。

created String 集群创建时间，格式为ISO8601: CCYY-MM- DDThh:mm:ss。

(30)

参数类型说明

status String 查询返回值。

● 100：操作进行中，如创建中。

● 200：可用。

endpoint String 用户VPC访问IP地址和端口号。

actionProg

ress Object 集群行为进度，显示创建和扩容进度的百分比。

actions Array of strings 集群当前行为，REBOOTING表示重启，

GROWING表示扩容，RESTORING表示恢复集群，SNAPSHOTTING表示创建快照。

failed_reas

ons Object 失败原因。如果集群处于正常状态，则不返回该参数。详细请参考表5-25。

authorityE

nable String 是否开启认证，取值范围为true或false。默认关闭认证功能。当开启认证时，httpsEnable需要设置为true。

enterprise_

project_id String 集群所属的企业项目ID。

如果集群所属用户没有开通企业项目，则不会返回该参数。

tags Array of tag

objects 集群标签。

表5-23 datastore 字段数据结构说明

参数类型说明

type String 支持类型：elasticsearch。

version String 引擎版本号。当前引擎版本为5.5.1、6.2.3、

6.5.4、7.1.1、7.6.2、7.9.3。

参数类型说明

type String 支持类型：ess（Elasticsearch节点）。

(31)

参数类型说明

status String 状态。

● 100：操作进行中，如创建中。

● 200：可用。

specCode String 节点规格名称。

azCode String 节点所属AZ信息。

表5-25 failed_reasons 字段数据结构说明

参数类型说明

error_code String 错误码。

● CSS.6000：表示集群创建失败。

● CSS.6001：表示集群扩容失败。

● CSS.6002：表示集群重启失败。

● CSS.6004：表示集群节点创建失败。

● CSS.6005：表示服务初始化失败。

error_msg String 详细错误信息。

表5-26 tags 字段数据结构说明

参数类型说明

key String 集群标签的key值。

value String 集群标签的value值。

示例

请求样例

GET /v1.0/6204a5bd270343b5885144cf9c8c158d/clusters/5c77b71c-5b35-4f50-8984-76387e42451a

响应样例

{ "datastore": {

}, "instances": [ {

"status": "200",

(32)

"type": "ess",

"id": "3c7fe582-a9f6-46fd-9d01-956bed4a8bbc", "name": "ES-1-16-test17-ess-esn-1-1"

}

], "updated": "2018-01-16T08:37:18", "name": "ES-1-16-test17", "created": "2018-01-16T08:37:18",

"id": "5c77b71c-5b35-4f50-8984-76387e42451a", "status": "200",

"endpoint": "192.168.0.8:9200", "actionProgress": {},

"actions": [],

"enterprise_project_id":"3e1c74a0-86a0-40e9-bdc9-c6b9e46cf81b", "tags": [

{

"key": "k1", "value": "v1"

} ] }

状态码

表5-27 状态码

5.4 删除集群

功能介绍

此接口用于删除集群。集群删除将释放此集群的所有资源，包括客户数据。为了安全起见，请确保为这个集群创建快照。

URI

DELETE /v1.0/{project_id}/clusters/{cluster_id}

表5-28 参数说明

参数是否为必

选

类型说明

project_id 是 String 项目编号。详细请参考获取项目ID/账

号ID。

(33)

参数是否为必选

类型说明

cluster_id 是 String 指定删除集群ID。

请求消息

无。

响应消息

无。

示例

删除集群ID为2a197c4d-5467-4003-931d-83ec49939cf的集群。

请求样例

DELETE /v1.0/6204a5bd270343b5885144cf9c8c158d/clusters/2a197c4d-5467-4003-931d-83ec49939cf

响应样例返回值为空。

状态码

表5-29 状态码

5.5 重启集群

功能介绍

此接口用于重启集群，重启集群将导致业务中断。

URI

POST /v1.0/{project_id}/clusters/{cluster_id}/restart

(34)

表5-30 参数说明

project_id 是 String 项目编号。详细请参考获取

项目ID/账号ID。

cluster_id 是 String 指定重启集群ID。

请求消息

无。

响应消息

表5-31 响应参数

参数类型说明

jobId String 重启任务的ID。

示例

请求样例

POST /v1.0/6204a5bd270343b5885144cf9c8c158d/clusters/47e49a5e-8ced-4d0d-ae15-2af62ac468e3/restart

响应样例

{ "jobId": [

"ff8080815fa0fa5e015fa365b6300007"

] }

状态码

表5-32 状态码

(35)

5.6 扩容集群

功能介绍

该接口用于集群扩容实例，只扩容普通节点，且只针对要扩容的集群实例不存在特殊节点（Master、Client、冷数据节点）的情况。

说明

推荐使用扩容实例的数量和存储容量进行扩容。

URI

POST /v1.0/{project_id}/clusters/{cluster_id}/extend

表5-33 参数说明

project_id 是 String 项目编号。详细请参考获取项目

ID/账号ID。

cluster_id 是 String 指定待扩容的集群ID。

请求消息

表5-34 请求参数

grow 是 Object 集群扩容请求详细描述。详细请参考

表5-35。

表5-35 grow 字段要素说明

参数是否为必

选

类型说明

modifySize 是 Integer 扩容实例个数，即扩容集群后的实例个数。

说明

集群已有实例个数和扩容实例个数总和不能超过32。

(36)

响应消息

表5-36 响应参数

参数类型说明

objects 扩容实例列表。

参数类型说明

type String 实例类型。

shard_id String 实例组名。

示例

请求样例

POST /v1.0/6204a5bd270343b5885144cf9c8c158d/clusters/ea244205-d641-45d9-9dcb-ab2236bcd07e/

extend { "grow":

{

"modifySize": 4 }

}

响应样例

{ "id": "4b0fae9f-e3fb-4581-872b-330cdd09a3d5", "instances": [

{

"id": "2c47ec92-337b-4f22-8337-e342eb315063", "name": "Es-c1a2-ess-esn-4-1",

"type": "ess", "shard_id": "esn-4"

}, {

"id": "311077f8-debb-4350-97d5-9eafd2b438f2", "name": "Es-c1a2-ess-esn-5-1",

}, {

"id": "fcc3c59e-9420-4fd8-a8ad-836c45b6813e", "name": "Es-c1a2-ess-esn-6-1",

"type": "ess",

(37)

"shard_id": "esn-6"

}, {

"id": "dd64e308-3799-4f2a-a57e-9b92e9f3ce45", "name": "Es-c1a2-ess-esn-7-1",

} ]}

状态码

表5-38 状态码

5.7 扩容实例的数量和存储容量

功能介绍

该接口用于集群扩容不同类型实例的个数以及存储容量。已经存在独立Master、

Client、冷数据节点的集群使用该接口扩容。

URI

POST /v1.0/{project_id}/clusters/{cluster_id}/role_extend

表5-39 参数说明

project_id 是 String 项目编号。详细请参考获取项目ID/账

号ID。

cluster_id 是 String 指定待扩容的集群ID。

请求消息

(38)

表5-40 请求参数

grow 是 Array of

object 集群扩容请求详细描述。详细请参见表

5-41。

表5-41 grow 字段要素说明

type 是 String 扩容实例类型。取值为ess、ess-cold、

ess-master或ess-client，请至少选择一个。

ess-master、ess-client节点只支持扩容实例个数。

nodesize 是 Integer 扩容实例个数。集群已有实例个数和扩容实例个数总和不能超过32。

disksize 是 Integer 扩容实例存储容量。集群原实例存储容量和扩容实例存储容量之和不能超过创建集群时对应的实例存储容量上限，且同一个集群实例存储容量扩容不能超过 6次。

单位：GB。

响应参数

表5-42 响应参数

参数类型说明

示例

请求样例

POST v1.0/458d905f22da49c39f609e3347d65723/clusters/4f3deec3-efa8-4598-bf91-560aad1377a3/

role_extend { "grow": [ {

"type": "ess-master", "nodesize": 2, "disksize": 0 },

{

"type": "ess",

(39)

"nodesize": 0, "disksize": 50 },

{

"type": "ess-client", "nodesize": 1, "disksize": 0 }

] }

响应样例

{ "id": "4f3deec3-efa8-4598-bf91-560aad1377a3"

}

状态码

表5-43 状态码

5.8 获取实例规格列表

功能介绍

该接口用于查询并显示支持的实例规格对应的ID。

URI

GET /v1.0/{project_id}/es-flavors

表5-44 参数说明

project_id 是 String 项目编号。详细请参考

获取项目ID/账号ID。

请求消息

无。

(40)

响应消息

表5-45 响应参数

参数类型说明

versions Array of versions

objects 引擎版本列表。

表5-46 versions 字段要素说明

参数类型说明

version String 引擎版本。支持5.5.1、6.2.3、6.5.4、

7.1.1、7.6.2、7.9.3。

type String 实例类型，包括为ess、ess-cold、ess- master和ess-client。

flavors Array of flavors

objects 规格列表。

表5-47 flavors 字段要素说明

参数类型说明

ram Integer 实例的内存大小。单位GB。

cpu Integer 实例的CPU核数。

name String 规格名称。

region String 可用区域。

diskrange String 实例的硬盘容量范围。

flavor_id String 规格对应的ID。

示例

请求样例GET /v1.0/6204a5bd270343b5885144cf9c8c158d/es-flavors

响应样例

{ "versions": [ {

"flavors": [ {

"cpu": 2,

(41)

"ram": 4,

"name": "ess.spec-kc1.large.2", "region": "cn-north-7", "diskrange": "40,640",

"flavor_id": "6209dc79-c000-46a1-b843-5e7288a55e2f"

}, {

"cpu": 2, "ram": 8,

"name": "ess.spec-2u8g", "region": "cn-north-7", "diskrange": "40,800",

"flavor_id": "b58dfcfb-5f73-4f05-8c06-5171b12fd618"

}, {

"cpu": 2, "ram": 8,

"flavor_id": "eb33baee-01dd-4f27-905d-42a6f63f2808"

}, {

"cpu": 2, "ram": 16,

"flavor_id": "d3952f68-86d5-4a41-8be3-73f99b6be7f8"

}, {

"cpu": 4, "ram": 8,

"flavor_id": "d9dc06ae-b9c4-4ef4-acd8-953ef4205e27"

}, {

"cpu": 4, "ram": 8,

"name": "ess.spec-kc1.xlarge.2", "region": "cn-north-7", "diskrange": "40,1280",

"flavor_id": "ea2588af-7e0f-4fc8-adfd-fda49f8c09c7"

}, {

"cpu": 4, "ram": 16,

"flavor_id": "35b060a4-f152-48ce-8773-36559ceb81f2"

}, {

"cpu": 4, "ram": 16,

"flavor_id": "ae5323a5-4493-44ff-9e9b-e404e835e1fe"

}, {

"cpu": 4, "ram": 32,

"flavor_id": "cb1a3408-33a7-4ced-b834-c2ad419876d8"

(42)

}, {

"cpu": 4, "ram": 32,

"name": "ess.spec-ds.xlarge.8", "region": "cn-north-7", "diskrange": "3350,3350",

"flavor_id": "cc0aafd1-ea06-4ade-92ca-5d0a476cd7bf"

}, {

"cpu": 8, "ram": 16,

"flavor_id": "b9fe19f1-835b-40db-879c-cddcd64a9648"

}, {

"cpu": 8, "ram": 32,

"flavor_id": "c3ed3633-e62c-4903-af4e-dd7aec13816d"

}, {

"cpu": 8, "ram": 64,

"flavor_id": "c2f6e2f5-a8de-49d7-864b-19559f127954"

}, {

"cpu": 8, "ram": 64,

"name": "ess.spec-i3small", "region": "cn-north-7", "diskrange": "1600,1600",

"flavor_id": "5f34d13b-3b49-4ac5-8f78-46eb60cffd7e"

}, {

"cpu": 16, "ram": 32,

"flavor_id": "70c5a33e-dfcb-41ee-8992-129deb069b26"

}, {

"cpu": 16, "ram": 64,

"flavor_id": "d4e2a36b-3d93-41df-97e7-498816b7bd2e"

}, {

"cpu": 16, "ram": 128,

"flavor_id": "3da413a1-2ad0-4f09-905c-28fbde50c1d4"

}, {

"cpu": 32, "ram": 64,

"name": "ess.spec-32u64g",

(43)

"region": "cn-north-7", "diskrange": "320,10240",

"flavor_id": "d62976d4-6019-95a2-7e30-1db3fbfaa87d"

}, {

"cpu": 32, "ram": 256,

"flavor_id": "82c1c69d-2b13-45a3-bf71-9ff758a59cb8"

} ],

"type": "ess", "version": "7.1.1"

}, {

"flavors": [ {

"cpu": 2, "ram": 4,

}, {

"cpu": 2, "ram": 8,

}, {

"cpu": 2, "ram": 8,

}, {

"cpu": 2, "ram": 16,

}, {

"cpu": 4, "ram": 8,

}, {

"cpu": 4, "ram": 8,

}, {

"cpu": 4, "ram": 16,

(44)

"flavor_id": "35b060a4-f152-48ce-8773-36559ceb81f2"

}, {

"cpu": 4, "ram": 16,

"flavor_id": "ae5323a5-4493-44ff-9e9b-e404e835e1fe"

}, {

"cpu": 4, "ram": 32,

"flavor_id": "cb1a3408-33a7-4ced-b834-c2ad419876d8"

}, {

"cpu": 8, "ram": 16,

"flavor_id": "b9fe19f1-835b-40db-879c-cddcd64a9648"

}, {

"cpu": 8, "ram": 32,

"flavor_id": "c3ed3633-e62c-4903-af4e-dd7aec13816d"

}, {

"cpu": 8, "ram": 64,

"flavor_id": "c2f6e2f5-a8de-49d7-864b-19559f127954"

}, {

"cpu": 16, "ram": 32,

"flavor_id": "70c5a33e-dfcb-41ee-8992-129deb069b26"

}, {

"cpu": 16, "ram": 64,

"flavor_id": "d4e2a36b-3d93-41df-97e7-498816b7bd2e"

}, {

"cpu": 16, "ram": 128,

"flavor_id": "3da413a1-2ad0-4f09-905c-28fbde50c1d4"

},

(45)

{

"cpu": 32, "ram": 64,

"flavor_id": "d62976d4-6019-95a2-7e30-1db3fbfaa87d"

}, {

"cpu": 32, "ram": 256,

"flavor_id": "82c1c69d-2b13-45a3-bf71-9ff758a59cb8"

} ],

"type": "ess-master", "version": "7.1.1"

}, {

"flavors": [ {

"cpu": 2, "ram": 4,

}, {

"cpu": 2, "ram": 8,

}, {

"cpu": 2, "ram": 8,

}, {

"cpu": 2, "ram": 16,

}, {

"cpu": 4, "ram": 8,

}, {

"cpu": 4, "ram": 8,

查询集群详情_云搜索服务 CSS_API参考_集群管理接口_华为云

API 参考

华为技术有限公司

https://www.huawei.com

[email protected]

目 录

1 使用前必读... 1

1.1 概述... 1

1.2 调用说明...1

1.3 终端节点...2

1.4 约束与限制... 2

1.5 基本概念...2

1.6 API 版本选择建议... 3

2 API 概览... 4

3 如何调用 API...6

3.1 构造请求...6

3.2 认证鉴权...8

3.3 返回结果... 10

4 快速入门...12

5 集群管理接口...14

5.1 创建集群... 14

5.2 查询集群列表...20

5.3 查询集群详情...25

5.4 删除集群... 28

5.5 重启集群... 29

5.6 扩容集群... 31

5.7 扩容实例的数量和存储容量... 33

5.8 获取实例规格列表... 35

5.9 管理标签... 45

5.9.1 查询指定集群的标签... 45

5.9.2 查询所有标签... 47

5.9.3 添加集群标签... 49

5.9.4 批量添加或删除集群标签... 50

5.9.5 删除集群指定标签... 52

6 词库管理接口...54

6.1 词库介绍... 54

6.2 IK 分词... 54

6.2.1 加载自定义词库...54

6.2.2 查询自定义词库状态... 56

6.2.3 删除自定义词库...58

7 快照管理接口...60

7.1 自动设置集群快照的基础配置（不推荐使用）...60

7.2 修改集群快照的基础配置... 61

7.3 设置自动创建快照策略... 62

7.4 查询集群的自动创建快照策略... 64

7.5 手动创建快照...65

7.6 查询快照列表...68

7.7 恢复快照... 71

7.8 删除快照... 73

7.9 停用快照功能...74

8 权限策略和授权项... 76

9 附录... 79

9.1 获取项目 ID/账号 ID... 79

9.2 状态码...80

9.3 错误码...82

10 修订记录... 86

1 使用前必读

1.1 概述

1.2 调用说明

1.3 终端节点

终端节点中查询所有服务的终端节点。

1.4 约束与限制

1.5 基本概念

指南》。

1.6 API 版本选择建议

2 API 概览

创建集群

查询集群列表

查询集群详情

删除集群

重启集群

扩容集群

扩容实例的数量和 存储容量

获取实例规格列表

查询指定集群的标 签

查询所有标签

添加集群标签

批量添加或删除集 群标签

删除集群指定标签

加载自定义词库

目录

1 ^{使用前必读}

2 ^{API 概览}

扩容实例的数量和存储容量

查询指定集群的标签

批量添加或删除集群标签

查询自定义词库状态

自动设置集群快照的基础配置（不推荐使用）

修改集群快照的基础配置

设置自动创建快照策略

查询集群的自动创建快照策略

3 ^{如何调用 API}

4 ^快速入门

5 ^{集群管理接口}