Help Center/ ServiceStage/ API Reference/ ServiceComb APIs/ Microservice/ Creating Static Information for a Microservice
Updated on 2024-10-16 GMT+08:00

Creating Static Information for a Microservice

Function

This API is used to create static information for a microservice before registering a microservice instance. The registered instance is associated with the static information based on serviceId. One service corresponds to multiple instances.

serviceId can be customized. If serviceId is not customized, the system generates a random service ID.

Restrictions

None

URI

POST /v4/{project_id}/registry/microservices

Table 1 Path parameter

Parameter

Mandatory

Type

Description

project_id

Yes

String

  • For a professional microservice engine, enter the tenant project ID. The value contains 1 to 64 characters. See Obtaining a Project ID. You can also enter the fixed value default.
  • For an exclusive microservice engine, enter the fixed value default.

Request

Table 2 Request header parameter

Parameter

Mandatory

Type

Description

Authorization

No

String

This parameter is mandatory if security authentication is enabled for an exclusive microservice engine. Otherwise, this parameter is not required.

The token of an exclusive microservice engine with security authentication enabled is in the following format:

Authorization:Bearer {Token}

For details about how to obtain the token, see Obtaining the User Token of an Exclusive Microservice Engine.

Table 3 Request body parameters

Parameter

Mandatory

Type

Description

service

Yes

MicroService object

Microservice information.

rules

No

Array of Rule objects

Blacklist and whitelist.

instances

No

Array of MicroServiceInstance objects

Instance information.

tags

No

Object

Extended attribute. You can customize a key and value. The value must be at least 1 byte long.

Table 4 MicroService

Parameter

Mandatory

Type

Description

serviceId

No

String

Microservice ID, which must be unique. The value contains 1 to 64 characters. Regular expression: ^.*$

environment

No

String

Microservice environment. Value: development, testing, acceptance, or production. You can use the API for uploading schemas in batches to add or modify an existing schema only when the value is development, testing, or acceptance. Default value: development.

appId

No

String

Application ID, which must be unique. The value contains 1 to 160 characters. Regular expression: ^[a-zA-Z0-9]$|^[a-zA-Z0-9][a-zA-Z0-9_-.][a-zA-Z0-9]$

serviceName

Yes

String

Microservice name, which must be unique in an application. The value contains 1 to 128 characters. Regular expression: ^[a-zA-Z0-9]$|^[a-zA-Z0-9][a-zA-Z0-9_-.][a-zA-Z0-9]$

version

No

String

Microservice version. The value contains 1 to 64 characters. Regular expression: ^[0-9]$|^[0-9]+(.[0-9]+)$

description

No

String

Microservice description. The value contains a maximum of 256 characters.

level

No

String

Microservice level. Value: FRONT, MIDDLE, or BACK.

registerBy

No

String

Microservice registration mode. Value: SDK, PLATFORM, SIDECAR, or UNKNOWN.

schemas

No

Array of strings

Foreign key ID of a microservice access schema. The array length supports a maximum of 100 schemas.

status

No

String

Microservice status. Value: UP or DOWN. Default value: UP.

timestamp

No

String

Microservice registration time.

modTimestamp

No

String

Latest modification time (UTC).

framework

No

Framework object

Development framework.

paths

No

Array of ServicePath objects

Service path.

Table 5 Framework

Parameter

Mandatory

Type

Description

name

No

String

Microservice development framework. Default value: UNKNOWN.

version

No

String

Version of the microservice development framework.

Table 6 ServicePath

Parameter

Mandatory

Type

Description

Path

No

String

Route address.

Property

No

Object

Extended attribute. You can customize a key and value. The value must be at least 1 byte long.

Table 7 Rule

Parameter

Mandatory

Type

Description

ruleId

No

String

Customized rule ID.

ruleType

No

String

Rule type. Value: WHITE or BLACK.

attribute

No

String

If the value starts with tag_xxx, the attributes are filtered by Tag. Otherwise, the attributes are filtered by serviceId, AppId, ServiceName, Version, Description, Level, or Status.

pattern

No

String

Matching rule. The value is a regular expression containing 1 to 64 characters.

description

No

String

Rule description.

timestamp

No

String

Time when a rule is created. This parameter is used only when you query rules.

modTimestamp

No

String

Update time.

Table 8 MicroServiceInstance

Parameter

Mandatory

Type

Description

instanceId

No

String

Instance ID, which must be unique. The instance ID is generated by the service center.

serviceId

No

String

Microservice ID, which must be unique. During instance creation, use the service ID in the URL instead of the service ID here.

version

No

String

Microservice version.

hostName

Yes

String

Host information.

endpoints

Yes

Array of strings

Access address information.

status

No

String

Instance status. Value: UP, DOWN, STARTING, or OUTOFSERVICE. Default value: UP.

properties

No

Object

Extended attribute. You can customize a key and value. The value must be at least 1 byte long.

healthCheck

No

HealthCheck object

Health check information.

dataCenterInfo

No

DataCenterInfo object

Data center information.

timestamp

No

String

Time when an instance is created, which is automatically generated.

modTimestamp

No

String

Update time.

Table 9 HealthCheck

Parameter

Mandatory

Type

Description

mode

Yes

String

Heartbeat mode. Value: push or pull.

port

No

Integer

Port.

interval

Yes

Integer

Heartbeat interval. Unit: s. If the value is less than 5s, the registration is performed at an interval of 5s.

times

Yes

Integer

Maximum retries.

Table 10 DataCenterInfo

Parameter

Mandatory

Type

Description

name

Yes

String

Region name.

region

Yes

String

Region.

availableZone

Yes

String

AZ.

Response

Status code: 200

Table 11 Response body parameter

Parameter

Type

Description

serviceId

String

Microservice ID, which must be unique.

Status code: 400

Table 12 Response body parameters

Parameter

Type

Description

errorCode

String

Error code.

errorMessage

String

Error message.

detail

String

Location details.

Status code: 500

Table 13 Response body parameters

Parameter

Type

Description

errorCode

String

Error code.

errorMessage

String

Error message.

detail

String

Location details.

Example Request

Create static information about a microservice: microservice name is test, microservice version is 1.0.0, rule type is whitelist, host information of the instance is instanceTest, and access address is 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"
	}
}

Example Response

Status code: 200

Successfully created. serviceId indicates the ID generated for the microservice. Subsequent operations are operated based on the microservice ID.

{
  "serviceId" : "8aed80ea052ac04a64dfc79c24f2170224d074f5"
}

Status Code

Status Code

Description

200

OK

400

Bad Request

500

Internal Server Error

Error Code

See ServiceComb Error Codes.