文档首页/ 微服务引擎 CSE/ API参考/ ServiceComb API/ 微服务/ 创建微服务静态信息 - CreateStaticInformationForMicroservice

更新时间：2026-05-29 GMT+08:00

创建微服务静态信息 - CreateStaticInformationForMicroservice

功能介绍

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

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

接口约束

无

授权信息

账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限。

如果使用角色与策略授权，具体权限要求请参见权限和授权项。
如果使用身份策略授权，当前API调用无需身份策略权限。

URI

POST /v4/{project_id}/registry/microservices

表1 路径参数
参数	是否必选	参数类型	描述
project_id	是	String	请填固定值：default。

请求参数

表2 请求Header参数
参数	是否必选	参数类型	描述
Authorization	否	String	若ServiceComb引擎专享版开启了安全认证，此参数必填。否则，无此参数。开启了安全认证的ServiceComb引擎专享版Token，格式为： Authorization:Bearer {Token} Token获取方法，请参考获取ServiceComb引擎专享版用户Token。
X-Authorization	否	String	若ServiceComb引擎专享版开启了安全认证，此参数必填。否则，无此参数。开启了安全认证的ServiceComb引擎专享版Token，格式为： X-Authorization:Bearer {Token} Token获取方法，请参考获取ServiceComb引擎专享版用户Token。

表3 请求Body参数
参数	是否必选	参数类型	描述
service	是	MicroService object	微服务信息。
rules	否	Array of Rule objects	黑白名单信息。
instances	否	Array of MicroServiceInstance objects	实例信息。
tags	否	Object	微服务扩展属性，可以自定义KEY和相应的Value。长度最小1字节。

表4 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]$。
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	微服务注册时间。
modTimestamp	否	String	最后修改UTC时间。
framework	否	Framework object	开发框架信息。
paths	否	Array of ServicePath objects	服务路由信息。

表5 Framework
参数	是否必选	参数类型	描述
name	否	String	微服务开发框架，默认值为UNKNOWN。
version	否	String	微服务开发框架版本号。

表6 ServicePath
参数	是否必选	参数类型	描述
Path	否	String	路由地址。
Property	否	Object	微服务扩展属性，可以自定义KEY和相应的Value。长度最小1字节。

表7 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的时间。
modTimestamp	否	String	更新时间。

表8 MicroServiceInstance
参数	是否必选	参数类型	描述
instanceId	否	String	实例id，唯一标识。创建实例，instanceId由service-center产生。
serviceId	否	String	微服务唯一标识。创建实例时，以url中的为准，不用此处的serviceId。
version	否	String	微服务版本号。
hostName	是	String	主机信息。
endpoints	是	Array of strings	访问地址信息。
status	否	String	实例状态。取值范围： UP：实例健康。 DOWN：实例不健康。 STARTING：实例正在启动。 OUTOFSERVICE：停止对外提供服务。默认取值： UP
properties	否	Object	微服务扩展属性，可以自定义KEY和相应的Value。长度最小1字节。
healthCheck	否	HealthCheck object	健康检查信息。
dataCenterInfo	否	DataCenterInfo object	数据中心信息。
timestamp	否	String	实例创建时间戳，自动生成。
modTimestamp	否	String	更新时间。

表9 HealthCheck
参数	是否必选	参数类型	描述
mode	是	String	心跳模式： push或者pull。
port	否	Integer	端口。
interval	是	Integer	心跳间隔（秒），当值小于5秒时，按5秒注册。
times	是	Integer	最大尝试请求次数。

**表10** DataCenterInfo
参数	是否必选	参数类型	描述
name	是	String	区域名称。
region	是	String	区域。
availableZone	是	String	可用区。

响应参数

状态码： 200

**表11** 响应Body参数
参数	参数类型	描述
serviceId	String	微服务唯一标识。

状态码： 400

**表12** 响应Body参数
参数	参数类型	描述
errorCode	String	错误代码。
errorMessage	String	错误信息。
detail	String	详细定位信息。

状态码： 500

**表13** 响应Body参数
参数	参数类型	描述
errorCode	String	错误代码。
errorMessage	String	错误信息。
detail	String	详细定位信息。

请求示例

创建一个微服务的静态信息，其微服务名为test，微服务版本为1.0.0，rule的类型为白名单，实例的主机信息为instanceTest，访问地址为rest:127.0.0.1:8080。

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

{
	"service": {
		"appId": "default",
		"serviceName": "test",
		"version": "1.0.0",
		"description": "this is a test"
	},
	"rules": [{
		"ruleType": "WHITE",
		"attribute": "tag_123",
		"pattern": "aaa"
	}],
	"instances": [{
		"hostName": "instanceTest",
		"endpoints": ["rest:127.0.0.1:8080"]
	}],
	"tags": {
		"test_tag1": "test_tag1",
		"test_tag2": "test_tag2",
		"test_tag3": "test_tag3"
	}
}

响应示例

状态码： 200

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

{
  "serviceId" : "8aed80ea052ac04a64dfc79c24f2170224d074f5"
}

状态码

状态码	描述
200	创建成功。
400	错误的请求。
500	服务内部错误。

错误码

请参见ServiceComb错误码。

父主题： 微服务

上一篇：查询所有微服务信息 - QueryInformationAboutAllMicroservices

下一篇：批量删除微服务静态信息 - DeleteStaticInformationAboutMicroservicesInBatches