ServiceComb错误码_微服务引擎 CSE_API参考_附录_错误码_华为云

(1)

API 参考

文档版本 01

发布日期 2021-12-08

(2)

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

商标声明

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

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

注意

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

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

华为技术有限公司

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

网址：

https://www.huawei.com

客户服务邮箱：

[email protected]

客户服务电话：4008302118

(3)

1 ^{使用前必读}

概述调用说明

服务注册发现地址约束与限制基本概念

1.1 概述

微服务引擎（Cloud Service Engine，CSE），是用于微服务应用的云中间件，为用户提供注册发现、服务治理、配置管理等高性能和高韧性的企业级云服务能力；CSE可无缝兼容Spring Cloud、ServiceComb等开源生态；用户也可结合其他云服务，快速构建云原生微服务体系，实现微服务应用的快速开发和高可用运维。

1.2 调用说明

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

1.3 服务注册发现地址

服务注册发现地址即调用API的请求地址，不同微服务引擎实例的服务注册发现地址不同，您可以参考获取微服务引擎服务注册发现地址查看服务注册发现地址。

1.4 约束与限制

● 您能创建的资源数量与配额有关系，具体请参见关于配额。

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

(6)

1.5 基本概念

● 帐号

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

● 用户

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

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

● 区域

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

● 可用区

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

● 项目

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

图1-1 项目隔离模型

● 企业项目

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

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

指南》。

(7)

同样在我的凭证下，您可以查看项目ID。

(8)

2 ^{API 概览}

微服务引擎API为开发者、合作伙伴提供微服务开发的开放接口，帮助用户快速、低成本地实现业务上云，使能微服务应用的高效运行。

对应的接口参考请参考下表：

表2-1 接口简介

类型子类型说明

ServiceComb原生接口

认证

提供微服务身份认证功能的相关操作接口。

微服务

提供微服务管理的相关操作接口。

契约

提供微服务契约查询、上传等相关操作接

口。

微服务实例

提供微服务实例注册、上报心跳等相关操作

接口。

依赖关系

提供微服务依赖关系查询接口。

配置管理

提供配置中心配置管理功能的相关操作接

口。

认证

表2-2 认证接口

API 说明

获取微服务引擎专享版用户Token

仅用于开启了安全认证的微服务引擎专享

版。

在访问开启了安全认证的微服务引擎专享版的接口前，需要先调用该接口获取用户 Token，该Token是访问接口的唯一凭据。

(9)

微服务

表2-3 微服务接口

API 说明

查询指定微服务信息

根据serviceId查询微服务定义信息。

删除微服务定义信息

删除一个微服务定义及其相关信息，同时

注销其所有实例信息。

查询所有微服务信息

根据条件组合，查询满足所有条件的微服

务定义信息。

创建微服务静态信息

在注册微服务实例前需要创建服务静态信

息，之后注册的微服务实例根据service_id 这个字段与静态信息关联，一个服务对应对多个实例。service_id可以定制。如果定制了，系统将使用定制的service_id；如果没定制，系统会随机生成service_id。

批量删除微服务静态信息

批量删除指定的微服务定义及其相关信

息，同时注销其所有实例信息。

修改微服扩展属性信息

创建微服务静态信息后可对服务部分字段

进行更新，每次更新都需要传入完整的服务静态信息json，也就是说，即便不更新部分的字段也要作为json的属性传过去。

查询微服务唯一标识信息

可通过指定条件，查询微服务service_id或

schema的唯一标识信息。

契约

表2-4 契约接口

API 说明

查询微服务契约

根据service_id和schema_id查询微服务

的契约信息。

修改微服务契约

根据schema_id更新微服务的契约内容。

查询微服务的所有契约

查询一个微服务的所有契约信息，包括

schema_id和summary信息。

(10)

微服务实例

表2-5 微服务实例接口

API 说明

注册微服务实例

创建微服务后就可以注册该微服务的实

例了。注册微服务实例时，需提供该微服务实例相关的信息。 instance_id可定制，如果定制了，再次注册就直接全内容覆盖。如果没定制，逻辑如下：系统自动生成id，如果endpoints内容重复，

则使用原来的id。

根据service_id查询微服务实例

实例注册后可以根据service_id发现该微

服务的所有实例。

注销微服务实例

实例注册后可以根据instance_id进行实

例注销。

查询微服务实例详细信息

实例注册后可以根据service_id和

instance_id获取该实例的详细信息。

修改微服务实例扩展信息

实例注册后可以根据instance_id进行添

加/更新一个微服务实例扩展信息。

修改微服务实例状态

实例注册后可以根据instance_id进行更

新一个微服务实例状态。

发送心跳信息

服务提供端需要向服务中心发送心跳信

息，以保证服务中心知道服务实例是否健康。

按条件查询微服务实例

实例注册后可以根据微服务版本规则或

字段条件发现该微服务的实例。

批量查询微服务实例

实例注册后可以根据微服务版本规则或

字段条件批量发现多个微服务的实例。

依赖关系

表2-6 依赖关系接口

API 说明

查询服务providers

根据consumer_id获取该服务的所有

providers,比如A->B A->C，那么根据A的服务Id，可以查询到B、C的微服务信息。

(11)

配置管理

表2-7 配置管理接口

API 说明

创建配置

创建一条配置。

修改配置

修改指定一条配置。

查询指定配置

查询指定一条配置。

查询配置列表

查询配置列表。

删除指定配置

删除指定一条配置。

删除所有配置

删除所有配置。

(12)

3 ^{如何调用 API}

构造请求返回结果

3.1 构造请求

本节介绍REST API请求的组成。

请求 URI

请求URI由如下部分组成。

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

尽管请求URI包含在请求消息头中，但大多数语言或框架都要求您从请求消息中单独传递它，所以在此单独强调。

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

● Endpoint：指定服务注册发现地址。

● resource-path：资源路径，也即API访问路径。从具体API的URI模块获取，例如

“获取用户Token”API的resource-path为“/v3/auth/tokens”。

● query-string：查询参数，是可选部分，并不是每个API都有查询参数。查询参数 前面需要带一个“？”，形式为“参数名=参数取值”，例如“limit=10”，表示查询不超过10条数据。

请求方法

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

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

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

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

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

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

(13)

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

请求消息头

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

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

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

json”，有其他取值时会在具体接口中专门说明。

● Authorization：微服务引擎实例的帐号Token，可选，当使用微服务引擎安全认证时，必须填充该字段。帐号Token是调用获取微服务引擎专享版用户Token接口的响应值，该接口是唯一不需要认证的接口。

请求消息体

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

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

3.2 返回结果

状态码

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

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

响应消息头

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

响应消息体

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

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

{ "error_code": "SVCSTG.0111", "error_msg": "xxxxxxxxx"

(14)

4 ^应用示例

注册发现

4.1 注册发现

场景描述

本章节指导用户通过API实现微服务注册与发现。API的调用方法请参见如何调用API。

流程介绍

1. 注册第一个微服务my-provider 2. 注册微服务my-provider的实例 3. 注册第二个微服务my-consumer

4. my-consumer发现第一个微服务my-provider的实例说明

以上微服务名称均为示例。

前提条件

● 获取微服务引擎实例的注册发现地址，参考服务注册发现地址，以下示例中以 {cse_endpoint}代替。

操作步骤

步骤1 注册微服务my-provider。

调用创建微服务静态信息接口，请求示例如下。

curl -k -H "x-domain-name:default" -XPOST "https://{cse_endpoint}/v4/default/registry/microservices" -d '{

"service": {

"serviceName": "my-provider", "appId": "default",

"version": "1.0.0", "description": "test", "level": "MIDDLE", "status": "UP"

(15)

} }'

返回结果：

{"serviceId":"918282e8562dc5fdc9a8dcd4d1baabb492190aa4"}

得到的serviceId，后续示例中以{providerServiceId}代替。

步骤2 注册微服务my-provider的实例。

调用注册微服务实例接口。实例有效期1小时，到期自动下线。假设provider实例监听的地址为127.0.0.1:8080，请求示例如下。

curl -k -H "x-domain-name:default" -XPOST "https://{cse_endpoint}/v4/default/registry/microservices/

{providerServiceId}/instances" -d '{

"instance": {

"hostName": "test", "endpoints": [

"rest:127.0.0.1:8080"

],

"status": "UP", "healthCheck": { "mode": "push", "interval": 900, "times": 3 }

} }'

返回结果：

{"instanceId":"2be605a095ed11eabcbe0255ac100fa3"}

步骤3 注册微服务my-consumer。

调用创建微服务静态信息接口，请求示例如下。

curl -k -H "x-domain-name:default" -XPOST "https://{cse_endpoint}/v4/default/registry/microservices" -d '{

"service": {

"serviceName": "my-consumer", "appId": "default",

"version": "1.0.0", "description": "test", "level": "MIDDLE", "status": "UP"

} }'

返回结果：

{"serviceId":"9db248934c31fc754d6e922b48ede4a5c004d3c1"}

得到的serviceId，后续示例中以{consumerServiceId}代替。

步骤4 my-consumer发现my-provider的实例。

调用按条件查询微服务实例接口，consumer带着自身的serviceId去服务中心查询 provider的实例信息，请求示例如下。

curl -k -H "x-domain-name:default" -H "X-ConsumerId:{consumerServiceId}" -XGET "https://

{cse_endpoint}/v4/default/registry/instances?appId=default&serviceName=my-provider&version=0.0.0%2B"

返回结果：

{

(16)

"serviceId": "918282e8562dc5fdc9a8dcd4d1baabb492190aa4", "endpoints": [

"rest:127.0.0.1:8080"

],

"hostName": "test", "status": "UP", "healthCheck": { "mode": "push", "interval": 150, "times": 3 },

"timestamp": "1589465646", "modTimestamp": "1589465646", "version": "1.0.0"

} ] }

在实际业务中，consumer可从实例查询结果中的"endpoint"字段获取provider实例的地址，发起业务调用。

您还可以进入微服务引擎控制台的“微服务目录”，查看服务注册信息。

----结束

(17)

5 ServiceComb API

认证微服务契约微服务实例依赖关系配置管理

5.1 认证

5.1.1 获取微服务引擎专享版用户 Token

功能介绍

仅用于开启了安全认证的微服务引擎专享版。

在访问开启了安全认证的微服务引擎专享版的接口前，需要先调用该接口获取用户 Token，该Token是访问接口的唯一凭据。

发送访问请求时需要在请求头中带上该Token，格式为：

Authorization:Bearer {Token}

接口约束

无

URI

(18)

请求参数

表5-1 请求 Body 参数

参数是否必选参数类型描述

name 是 String 用户帐号名称。

password 是 String 用户帐号密码。

响应参数

状态码： 200

表5-2 响应 Body 参数

参数参数类型描述

token String 获取的用户Token，有效期为12小时。

状态码： 400

errorCode String 错误代码。

errorMessage String 错误信息。

detail String 详细定位信息。

状态码： 500

请求示例

POST https://{服务注册发现地址}/v4/token

(19)

响应示例

状态码： 200

用于获取用户Token的响应结构体。

{ "token" : "string"

}

状态码

状态码描述

200 用于获取用户Token的响应结构体。

400 错误的请求。

500 服务内部错误

错误码

请参见ServiceComb错误码。

5.2 微服务

5.2.1 查询指定微服务信息

功能介绍

根据service_id查询微服务定义信息。

接口约束

无

调试

您可以在API Explorer中调试该接口。

URI

GET /v4/{project_id}/registry/microservices/{service_id}

表5-5 路径参数

(20)

service_id 是 String 微服务唯一标识。字符长度为 1~64。正则表达式为^.*$

请求参数

表5-6 请求 Header 参数

Authorization 否 String 若微服务引擎专享版开启了安全认证，此参数必填。

请参考访问开启了安全认证的微

服务引擎专享版的接口

响应参数

状态码： 200

service

MicroService

object 微服务信息。

表5-8 MicroService

serviceId String 微服务唯一标识。字符长度为1~64。正则表达式为^.*$

environment String 用于区分微服务环境，取值为development、

testing、acceptance、production。当配置为 development、testing或acceptance时，可以通过批量上传schemas接口新增或者修改已存在的 Schema；当配置为production时，则不可以新增或者修改Schema。默认值development

appId String 应用App唯一标识。字符长度为1~160。正则表达式为^[a-zA-Z0-9]$|^[a-zA-Z0-9][a-zA- Z0-9_-.][a-zA-Z0-9]$

serviceName String 微服务名称，同一个App要保证唯一。字符长度为1~128。正则表达式为^[a-zA-Z0-9]$|^[a-zA- Z0-9][a-zA-Z0-9_-.][a-zA-Z0-9]$

(21)

version String 微服务版本号。字符长度为1~64。正则表达式为

^[0-9]$|^[0-9]+(.[0-9]+)$

description String 微服务描述信息。字符长度不超过256 level String 微服务层级：FRONT、MIDDLE、BACK registerBy String 微服务注册方式：SDK、PLATFORM、

SIDECAR、UNKNOWN schemas Array of

strings 微服务访问的契约内容。支持数字、字母，支持使用括号内字符做连接符(_-.)，长度1-160字节，

数组长度最大100个契约

status String 微服务状态，UP表示上线，DOWN表示下线，默认值UP

枚举值：

● UP

● DOWN timestamp String 微服务注册时间 modTimesta

mp String 最后修改UTC时间

framework

Framework

object 开发框架信息 paths Array of

ServicePath

objects

服务路由信息

表5-9 Framework

name String 微服务开发框架，默认值为UNKNOWN。

version String 微服务开发框架版本号。

表5-10 ServicePath

Path String 路由地址。

Property Object 微服务扩展属性，可以自定义KEY和相应的 Value。长度最小1字节。

(22)

状态码： 400

状态码： 500

请求示例

GET https://{endpoint}/v4/{project_id}/registry/microservices/{service_id}

响应示例

状态码： 200 查询成功。

{ "service" : {

"serviceId" : "string", "environment" : "string", "appId" : "string", "serviceName" : "string", "version" : "string", "description" : "string", "level" : "string", "registerBy" : "string", "schemas" : [ { "schemaId" : "string", "schema" : "string", "summary" : "string"

} ],

"status" : "UP", "timestamp" : "string", "modTimestamp" : "string", "framework" : {

"name" : "string", "version" : "string"

},

"paths" : [ { "Path" : "string"

(23)

} ] }}

状态码

状态码描述

200 查询成功。

错误码

5.2.2 删除微服务定义信息

功能介绍

删除一个微服务定义及其相关信息，同时注销其所有实例信息。

接口约束

无

调试

URI

DELETE /v4/{project_id}/registry/microservices/{service_id}

表5-13 路径参数

project_id 是 String 租户子项目的唯一标识，字符长度为1~64。

(24)

表5-14 Query 参数

force 否 Boolean 是否强制删除。

true表示强制删除，false表示非强制删除。

选择强制删除会自动注销所有服务实例，并且删除相关的服务依赖关系。如果未传此参数，那么在服务拥有实例时，无法被删除。

缺省值：false

请求参数

服务引擎专享版的接口

响应参数

状态码： 400

状态码： 500

(25)

参数参数类型描述 errorMessage String 错误信息。

请求示例

DELETE https://{endpoint}/v4/d9f4da085f2c11e8959a00ff2d7c69b7/registry/microservices/

e0f0da073f2c91e8979a89ff2d7c69t6

响应示例

无

状态码

状态码描述

200 删除成功。

错误码

5.2.3 查询所有微服务信息

功能介绍

根据条件组合，查询满足所有条件的微服务定义信息。

接口约束

无

调试

URI

(26)

表5-18 路径参数

请求参数

服务引擎专享版的接口

响应参数

状态码： 200

services Array of

MicroService

objects

微服务列表。

serviceId String 微服务唯一标识。字符长度为1~64。正则表达式为^.*$

environment String 用于区分微服务环境，取值为development、

testing、acceptance、production。当配置为 development、testing或acceptance时，可以通过批量上传schemas接口新增或者修改已存在的 Schema；当配置为production时，则不可以新增或者修改Schema。默认值development

appId String 应用App唯一标识。字符长度为1~160。正则表达式为^[a-zA-Z0-9]$|^[a-zA-Z0-9][a-zA- Z0-9_-.][a-zA-Z0-9]$

(27)

serviceName String 微服务名称，同一个App要保证唯一。字符长度为1~128。正则表达式为^[a-zA-Z0-9]$|^[a-zA- Z0-9][a-zA-Z0-9_-.][a-zA-Z0-9]$

version String 微服务版本号。字符长度为1~64。正则表达式为

^[0-9]$|^[0-9]+(.[0-9]+)$

description String 微服务描述信息。字符长度不超过256 level String 微服务层级：FRONT、MIDDLE、BACK registerBy String 微服务注册方式：SDK、PLATFORM、

SIDECAR、UNKNOWN schemas Array of

strings 微服务访问的契约内容。支持数字、字母，支持使用括号内字符做连接符(_-.)，长度1-160字节，

数组长度最大100个契约

status String 微服务状态，UP表示上线，DOWN表示下线，默认值UP

timestamp String 微服务注册时间 modTimesta

mp String 最后修改UTC时间

framework

Framework

object 开发框架信息 paths Array of

ServicePath

objects

服务路由信息

name String 微服务开发框架，默认值为UNKNOWN。

version String 微服务开发框架版本号。

Path String 路由地址。

Property Object 微服务扩展属性，可以自定义KEY和相应的 Value。长度最小1字节。

(28)

状态码： 400

状态码： 500

请求示例

GET https://{endpoint}/v4/{project_id}/registry/microservices

响应示例

{ "services" : [ { "serviceId" : "string", "environment" : "string", "appId" : "string", "serviceName" : "string", "version" : "string", "description" : "string", "level" : "string", "registerBy" : "string", "schemas" : [ "string" ], "status" : "UP", "timestamp" : "string", "modTimestamp" : "string", "framework" : {

"name" : "string", "version" : "string"

},

"paths" : [ { "Path" : "string"

} ] } ] }

(29)

状态码

状态码描述

200 查询成功。

错误码

5.2.4 创建微服务静态信息

功能介绍

在注册微服务实例前需要创建服务静态信息，之后注册的微服务实例根据service_id这个字段与静态信息关联，一个服务对应对多个实例。

service_id可以定制。如果定制了，系统将使用定制的service_id；如果没有定制，系统会随机生成service_id。

接口约束

无

调试

URI

POST /v4/{project_id}/registry/microservices

表5-26 路径参数

(30)

请求参数

服务引擎专享版的接口

service 否

MicroService

object 微服务信息。

rules 否 Array of Rule

objects 黑白名单信息。

instances 否 Array of

MicroServiceInsta nce objects

实例信息。

tags 否 Object 微服务扩展属性，可以自定义

KEY和相应的Value。长度最小1字节。

serviceId 否 String 微服务唯一标识。字符长度为 1~64。正则表达式为^.*$

environment 否 String 用于区分微服务环境，取值为 development、testing、

acceptance、production。当配置为development、testing或 acceptance时，可以通过批量上传schemas接口新增或者修改已存在的Schema；当配置为 production时，则不可以新增或者修改Schema。默认值

development

appId 是 String 应用App唯一标识。字符长度为

1~160。正则表达式为^[a-zA- Z0-9]$|^[a-zA-Z0-9][a-zA- Z0-9_-.][a-zA-Z0-9]$

(31)

serviceName 是 String 微服务名称，同一个App要保证唯一。字符长度为1~128。正则表达式为^[a-zA-Z0-9]$|^[a- zA-Z0-9][a-zA-Z0-9_-.][a-zA- Z0-9]$

version 是 String 微服务版本号。字符长度为

1~64。正则表达式为^[0-9]$|

^[0-9]+(.[0-9]+)$

description 否 String 微服务描述信息。字符长度不超过256

level 否 String 微服务层级：FRONT、

MIDDLE、BACK

registerBy 否 String 微服务注册方式：SDK、

PLATFORM、SIDECAR、

UNKNOWN。

schemas 否 Array of

strings 微服务访问契约内容的外键ID，

数组长度最大100个契约。

status 否 String 微服务状态，UP表示上线，

DOWN表示下线，默认值UP timestamp 否 String 微服务注册时间

modTimesta

mp 否 String 最后修改UTC时间

framework 否

Framework

object 开发框架信息

paths 否 Array of

ServicePath

objects

服务路由信息

name 否 String 微服务开发框架，默认值为

UNKNOWN。

version 否 String 微服务开发框架版本号。

(32)

Path 否 String 路由地址。

Property 否 Object 微服务扩展属性，可以自定义

KEY和相应的Value。长度最小1 字节。

表5-32 Rule

ruleId 否 String 自定义ruleId。

ruleType 否 String rule类型：WHITE或者BLACK。

attribute 否 String 如果是tag_xxx开头，则按Tag过滤attribute属性，否则，则按

"serviceId", "AppId",

"ServiceName", "Version",

"Description", "Level",

"Status"过滤。

pattern 否 String 匹配规则，正则表达式，长度1

到64。

description 否 String rule描述。

timestamp 否 String 只有获取rule时返回使用，创建 rule的时间。

modTimesta

mp 否 String 更新时间。

表5-33 MicroServiceInstance

instanceId 否 String 实例id，唯一标识。创建实例，

instanceId由service-center产生。

serviceId 否 String 微服务唯一标识。创建实例时，

以url里面的为准，不用这里的 serviceId。

version 否 String 微服务版本号。

hostName 是 String 主机信息。

(33)

参数是否必选参数类型描述 endpoints 是 Array of

strings 访问地址信息。

status 否 String 实例状态：UP、DOWN、

STARTING、OUTOFSERVICE，

默认值UP。

properties 否 Object 微服务扩展属性，可以自定义 KEY和相应的Value。长度最小1 字节。

healthCheck 否

HealthCheck

object 健康检查信息。

dataCenterInf

o 否

DataCenterIn

fo object

数据中心信息。

timestamp 否 String 实例创建时间戳，自动生成。

modTimesta

表5-34 HealthCheck

mode 是 String 心跳模式： push或者pull。

port 否 Integer 端口。

interval 是 Integer 心跳间隔（秒），当值小于5秒时，按5秒注册。

times 是 Integer 允许失败次数，不允许小于0。

表5-35 DataCenterInfo

name 是 String 区域名称

region 是 String 区域

availableZone 是 String 可获取区

响应参数

(34)

serviceId String 微服务唯一标识。

状态码： 400

状态码： 500

请求示例

POST https://{endpoint}/v4/{project_id}/registry/microservices { "service" : {

"serviceName" : "helloworld", "alias" : "HelloWorld", "appId" : "TestApp", "version" : "1.0.1",

"description" : "some descrition message!", "level" : "FRONT",

"schemas" : [ "com.test.HelloWorld" ], "status" : "UP",

"properties" : { "attr1" : "a"

},

"paths" : [ { "path" : "/rest/url", "property" : {

"match" : "accurate", "local" : "force", "checksession" : "true"

} }, {

(35)

"path" : "/rest/url2", "property" : {

"match" : "accurate", "local" : "force"

} } ] }}

响应示例

状态码： 200

创建成功。service_id该微服务生成的id。后续的操作都是针对该微服务ID进行操作。

{ "serviceId" : "string"

}

状态码

状态码描述

200 创建成功。

500 服务内部错误。

错误码

5.2.5 批量删除微服务静态信息

功能介绍

批量删除指定的微服务定义及其相关信息，同时注销其所有实例信息。

接口约束

无

调试

URI

(36)

表5-39 路径参数

force 否 Boolean 是否强制删除。

true表示强制删除，false表示非强制删除。

选择强制删除会自动注销所有服务实例，并且删除相关的服务依赖关系。如果未传此参数，那么在服务拥有实例时，无法被删除。

缺省值：false。

请求参数

服务引擎专享版的接口

serviceIds 否 Array of

strings 服务ID列表。

响应参数

状态码： 200

(37)

services Array of

DelServicesR spInfo objects

需要删除的服务信息列表。

表5-44 DelServicesRspInfo

serviceId String 微服务id。

状态码： 400

状态码： 500

请求示例

DELETE https://{endpoint}/v4/{project_id}/registry/microservices { "serviceIds" : [ "id1", "id2"]

}

(38)

删除成功。

{ "services" : [ { "serviceId" : "string", "errMessage" : "string"

} ] }

状态码

状态码描述

200 删除成功。

错误码

5.2.6 修改微服扩展属性信息

功能介绍

创建微服务静态信息后可对服务部分字段进行更新，每次更新都需要传入完整的服务静态信息json，即便不更新部分的字段也要作为json的属性传入。

接口约束

无

调试

URI

PUT /v4/{project_id}/registry/microservices/{service_id}/properties

表5-47 路径参数

project_id 是 String 租户子项目的唯一标识，字符长度为1~64

(39)

请求参数

服务引擎专享版的接口

响应参数

状态码： 400

状态码： 500

(40)

{ "properties" : { "a" : "test"

}}

响应示例

无

状态码

状态码描述

200 修改成功。

错误码

5.2.7 查询微服务唯一标识信息

功能介绍

可通过指定条件，查询微服务service_id或schema的唯一标识信息。

调试

URI

GET /v4/{project_id}/registry/existence

表5-52 路径参数

type 否 String 资源类型分为两种，microservice 微服务schema微服务访问契约

(41)

env 否 String 微服务的环境信息：

development、testing、

acceptance、production

appId 否 String 资源类型为microservice时需传入应用app唯一标识。字符长度为 1~160。正则表达式为^[a-zA- Z0-9]$|^[a-zA-Z0-9][a-zA- Z0-9_-.][a-zA-Z0-9]$

serviceName 否 String 资源类型为microservice时需传入微服务名称。字符长度为1~128 正则表达式为^[a-zA-Z0-9]$|^[a- zA-Z0-9][a-zA-Z0-9_-.][a-zA- Z0-9]$

version 否 String 资源类型为microservice时需传入微服务版本。字符长度为1~64。

正则表达式为^[0-9]$|^[0-9]+(.

[0-9]+)$

serviceId 否 String 资源类型为schema时需传入微服务唯一标识。字符长度为1~64。

正则表达式为^.*$

schemaId 否 String 资源类型为schema时需传入 schema唯一标识。字符长度为 1~160。正则表达式为^[a-zA- Z0-9]{1,160}$|^[a-zA-Z0-9][a- zA-Z0-9_-.]{0,158}[a-zA-Z0-9]$

请求参数

服务引擎专享版的接口

响应参数

状态码： 200

(42)

表5-55 响应 Header 参数

X-Schema-Summary String 契约的摘要

serviceId String 查询实体为服务时，返回服务ID。

schemaId String 查询实体为契约时，返回契约ID。

状态码： 400

状态码： 500

请求示例

GET https://{endpoint}/v4/{project_id}/registry/existence

响应示例

状态码： 200

查询成功，则返回 service_id 或者 schema_id。

{ "serviceId" : "string",

(43)

"schemaId" : "string"

}

状态码

状态码描述

200 查询成功。

错误码

5.3 契约

5.3.1 查询微服务契约

功能介绍

根据service_id和schema_id查询微服务的契约信息。

接口约束

无

调试

URI

GET /v4/{project_id}/registry/microservices/{service_id}/schemas/{schema_id}

表5-59 路径参数

(44)

请求参数

服务引擎专享版的接口

响应参数

状态码： 200

表5-61 响应 Header 参数

X-Schema-Summary String 微服务契约的摘要。

schema String 契约内容。

状态码： 400

状态码： 500

(45)

请求示例

GET https://{endpoint}/v4/{project_id}/registry/microservices/{service_id}/schemas/{schema_id}

响应示例

状态码： 200

查询成功，如果summary存在，则header里面的X-Schema-Summary的value为该 schema对应的摘要。

{ "schema" : "string"

}

状态码

状态码描述

200 查询成功。

错误码

5.3.2 修改微服务契约

功能介绍

根据schema_id更新微服务的契约内容。

接口约束

服务中心老版本如果微服务环境定为production，不支持契约覆盖；从版本2.3.33开始，支持使用环境变量SCHEMA_EDITABLE支持契约覆盖。

(46)

URI

PUT /v4/{project_id}/registry/microservices/{service_id}/schemas/{schema_id}

表5-65 路径参数

schema_id 是 String 微服务契约唯一标识。字符长度为1~160。正则表达式为^[a- zA-Z0-9]{1,160}$|^[a-zA-Z0-9]

[a-zA-Z0-9_-.]{0,158}[a-zA- Z0-9]$

请求参数

服务引擎专享版的接口

schema 是 String 契约内容。

summary 否 String 新加入参数，后面创建

schema，请尽量提供shema的摘要。

响应参数

状态码： 400

(47)

状态码： 500

请求示例

PUT https://{endpoint}/v4/{project_id}/registry/microservices/{service_id}/schemas/{schema_id}

schema: | ---

swagger: "2.0"

info:

version: "1.0.0"

title: "swagger definition for com.service.comment.controller.SimpleCtrlImpl"

x-java-interface: "cse.gen.blog.comment_service.Simple.SimpleCtrlImplIntf"

basePath: "/simple"

schemes:

- "https"

consumes:

- "application/json"

produces:

- "application/json"

paths:

/getname:

get:

operationId: "getName"

parameters:

- name: "age"

in: "query"

required: false type: "integer"

format: "int32"

responses:

200:

description: "response of 200"

schema:

$ref: "#/definitions/CommonResult"

definitions:

CommonResult:

(48)

properties:

resultCode:

type: "integer"

format: "int32"

resultDesc:

type: "string"

x-java-class: "com.service.comment.controller.CommonResult"

响应示例

无

状态码

状态码描述

200 修改成功。

错误码

5.3.3 查询微服务的所有契约

功能介绍

查询一个微服务的所有契约信息，包括schema_id和summary信息。

调试

URI

GET /v4/{project_id}/registry/microservices/{service_id}/schemas

表5-70 路径参数

(49)

withSchema 否 Integer 是否查询schema内容。

0表示不显示schema内容只有 schema_id和summary。

1表示显示schema_id、

summary和schema。

请求参数

服务引擎专享版的接口

响应参数

状态码： 200

schemas Array of

Schema

objects

契约列表。

表5-74 Schema

schemaId String 契约id

状态码： 400

(50)

状态码： 500

请求示例

GET /v4/{project_id}/registry/microservices/{service_id}/schemas

响应示例

{ "schemas" : [ { "schemaId" : "string", "schema" : "string", "summary" : "string"

} ] }

状态码

状态码描述

200 查询成功。

错误码

(51)

5.4 微服务实例

5.4.1 注册微服务实例

功能介绍

创建微服务后就可以注册该微服务的实例。

注册微服务实例时，需提供该微服务实例相关的信息。

instance_id可定制，如果定制了，再次注册就直接全内容覆盖；如果没有定制，系统自动生成id，如果endpoints内容重复，则使用原来的id。

调试

URI

POST /v4/{project_id}/registry/microservices/{service_id}/instances

表5-77 路径参数

请求参数

服务引擎专享版的接口

(52)

instance 否

MicroServiceI nstance

object

微服务实例信息。

instanceId 否 String 实例id，唯一标识。创建实例，

instanceId由service-center产生。

serviceId 否 String 微服务唯一标识，创建实例时，

以url里面的为准，不用这里的 serviceId。

version 否 String 微服务版本号。

hostName 是 String 主机信息。

endpoints 是 Array of

status 否 String 实例状态：UP、DOWN、

STARTING、OUTOFSERVICE。

默认值UP。

healthCheck 否

HealthCheck

dataCenterInf

o 否

DataCenterIn

fo object

timestamp 否 String 实例创建时间戳，自动生成。

modTimesta

mode 是 String 心跳模式push/pull。

port 否 Integer 端口。

(53)

interval 是 Integer 心跳间隔（秒），当值小于5秒时，按5秒注册。

times 是 Integer 允许失败次数，不允许小于0。

name 是 String 区域名字

region 是 String 区域

availableZone 是 String 可获取区

响应参数

状态码： 200

instanceId String 实例ID。

状态码： 400

状态码： 500

(54)

请求示例

POST https://{endpoint}/v4/{project_id}/registry/microservices/{service_id}/instances { "instance" : {

"endpoints" : [ "grpc://127.0.1.312:9980", "rest://127.0.0.111:8081" ], "hostName" : "localhost",

"status" : "UP", "stage" : "dev", "properties" : { "_TAGS" : "A, B", "attr1" : "a", "nodeIP" : "127.0.0.1"

},

"dataCenterInfo" : { "name" : "dc", "region" : "r1", "availableZone" : "az1"

},

"healthCheck" : { "mode" : "push", "interval" : 30, "times" : 3 }

}}

响应示例

状态码： 200 注册成功。

{ "instanceId" : "string"

}

状态码

状态码描述

200 注册成功。

错误码

(55)

5.4.2 根据 service_id 查询微服务实例

功能介绍

实例注册后可以根据service_id发现该微服务的所有实例。

调试

URI

GET /v4/{project_id}/registry/microservices/{service_id}/instances

表5-86 路径参数

tags 否 String Tag标签过滤，多个时逗号分

隔。正则表达式为^[a-zA-Z][a- zA-Z0-9_-.]{0,63}$

env 否 String 实例的环境信息：

development、testing、

acceptance、production

请求参数

X-ConsumerId 否 String 微服务消费者的微服务唯一标识。

(56)

响应参数

状态码： 200

instances Array of

MicroServiceI nstance

objects

实例列表。

instanceId String 实例id，唯一标识。创建实例，instanceId由 service-center产生。

serviceId String 微服务唯一标识，创建实例时，以url里面的为准，不用这里的serviceId。

version String 微服务版本号。

hostName String 主机信息。

endpoints Array of

status String 实例状态：UP、DOWN、STARTING、

OUTOFSERVICE。默认值UP。

properties Object 微服务扩展属性，可以自定义KEY和相应的 Value。长度最小1字节。

healthCheck

HealthCheck

dataCenterInf

o

DataCenterIn

fo object

timestamp String 实例创建时间戳，自动生成。

modTimesta

mp String 更新时间。

mode String 心跳模式push/pull。

(57)

参数参数类型描述 port Integer 端口。

interval Integer 心跳间隔（秒），当值小于5秒时，按5秒注册。

times Integer 允许失败次数，不允许小于0。

name String 区域名字

region String 区域 availableZone String 可获取区

状态码： 400

状态码： 500

请求示例

GET https://{endpoint}/v4/{project_id}/registry/microservices/{service_id}/instances

(58)

查询成功。

{ "instances" : [ { "instanceId" : "string", "serviceId" : "string", "version" : "string", "hostName" : "string",

"endpoints" : [ "string", "string" ], "status" : "string",

"null" : null, "healthCheck" : { "mode" : "string", "port" : 0, "interval" : 0, "times" : 0 },

"dataCenterInfo" : { "name" : "string", "region" : "string", "availableZone" : "string"

},

"timestamp" : "string", "modTimestamp" : "string"

} ] }

状态码

状态码描述

200 查询成功。

错误码

5.4.3 注销微服务实例

功能介绍

实例注册后可以根据instance_id进行实例注销。

调试

URI

DELETE /v4/{project_id}/registry/microservices/{service_id}/instances/{instance_id}

(59)

表5-95 路径参数

project_id 是 String 租户子项目的唯一标识。字符长度为1~64

instance_id 是 String 微服务实例唯一标识。字符长度不超过64位。正则表达式为

^[A-Za-z0-9_.-]*$

请求参数

服务引擎专享版的接口

响应参数

状态码： 400

状态码： 500

errorCode String

(60)

请求示例

DELETE https://{endpoint}/v4/{project_id}/registry/microservices/{service_id}/instances/{instance_id}

响应示例

无

状态码

状态码描述

200 注销成功。

错误码

5.4.4 查询微服务实例详细信息

功能介绍

实例注册后可以根据service_id和instance_id获取该实例的详细信息。

调试

URI

GET /v4/{project_id}/registry/microservices/{service_id}/instances/{instance_id}

表5-99 路径参数

project_id 是 String 租户子项目的唯一标识。字符长度为1~64

ServiceComb错误码_微服务引擎 CSE_API参考_附录_错误码_华为云

API 参考

华为技术有限公司

https://www.huawei.com

[email protected]

目 录

1 使用前必读... 1

1.1 概述... 1

1.2 调用说明...1

1.3 服务注册发现地址... 1

1.4 约束与限制... 1

1.5 基本概念...2

2 API 概览... 4

3 如何调用 API...8

3.1 构造请求...8

3.2 返回结果...9

4 应用示例...10

4.1 注册发现... 10

5 ServiceComb API...13

5.1 认证... 13

5.1.1 获取微服务引擎专享版用户 Token... 13

5.2 微服务...15

5.2.1 查询指定微服务信息... 15

5.2.2 删除微服务定义信息... 19

5.2.3 查询所有微服务信息... 21

5.2.4 创建微服务静态信息... 25

5.2.5 批量删除微服务静态信息... 31

5.2.6 修改微服扩展属性信息...34

5.2.7 查询微服务唯一标识信息... 36

5.3 契约... 39

5.3.1 查询微服务契约...39

5.3.2 修改微服务契约...41

5.3.3 查询微服务的所有契约...44

5.4 微服务实例... 47

5.4.1 注册微服务实例...47

5.4.2 根据 service_id 查询微服务实例... 51

5.4.5 修改微服务实例扩展信息... 60

5.4.6 修改微服务实例状态... 62

5.4.7 发送心跳信息... 64

5.4.8 按条件查询微服务实例...66

5.4.9 批量查询微服务实例... 70

5.5 依赖关系... 77

5.5.1 查询服务 providers...77

5.6 配置管理... 81

5.6.1 创建配置... 81

5.6.2 修改配置... 84

5.6.3 查询指定配置... 87

5.6.4 查询配置列表... 89

5.6.5 删除指定配置... 92

5.6.6 删除所有配置... 94

6 附录... 97

6.1 状态码...97

6.2 错误码...98

6.2.1 CSE 错误码...98

6.2.2 ServiceComb 错误码... 100

7 修订记录... 103

1 使用前必读

概述 调用说明

服务注册发现地址 约束与限制 基本概念

1.1 概述

1.2 调用说明

1.3 服务注册发现地址

1.4 约束与限制

1.5 基本概念

指南》。

2 API 概览

认证

微服务

契约

微服务实例

依赖关系

配置管理

认证

获取微服务引擎专享版用户Token

微服务

查询指定微服务信息

删除微服务定义信息

查询所有微服务信息

创建微服务静态信息

批量删除微服务静态信息

目录

1 ^{使用前必读}

概述调用说明

服务注册发现地址约束与限制基本概念

2 ^{API 概览}

3 ^{如何调用 API}

构造请求返回结果

4 ^应用示例

认证微服务契约微服务实例依赖关系配置管理