Help Center> ServiceStage> API Reference> ServiceComb API> Microservice Instance> Registering a Microservice Instance
Updated on 2024-06-14 GMT+08:00
View PDF

Registering a Microservice Instance

Function

This API is used to register a microservice instance after a microservice is created.

Information about the instance must be provided during registration.

instanceid can be customized. If it is customized, the new instance ID will overwrite the original one. If it is not customized, the system automatically generates an ID. If the endpoints are duplicate, the original ID is used.

URI

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

Table 1 Path parameters

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.

service_id

Yes

String

Microservice ID, which must be unique. The value contains 1 to 64 characters. Regular expression: ^.*$. See Querying Information About All Microservices.

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 parameter

Parameter

Mandatory

Type

Description

instance

Yes

MicroServiceInstance object

Microservice instance information.
Table 4 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 microservice ID in the URL instead of the microservice ID specified here.

version

No

String

Microservice version.

hostName

Yes

String

Host information.

endpoints

No

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 5 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 6 DataCenterInfo

Parameter

Mandatory

Type

Description

name

Yes

String

Region name.

region

Yes

String

Region.

availableZone

Yes

String

AZ.

Response

Status code: 200

Table 7 Response body parameter

Parameter

Type

Description

instanceId

String

Instance ID.

Status code: 400

Table 8 Response body parameters

Parameter

Type

Description

errorCode

String

Error code.

errorMessage

String

Error message.

detail

String

Location details.

Status code: 500

Table 9 Response body parameters

Parameter

Type

Description

errorCode

String

Error code.

errorMessage

String

Error message.

detail

String

Location details.

Example Request

Register a microservice instance: host information is localhost, heartbeat mode is push, heartbeat interval is 30s, region is r1, name is dc, and AZ is az1.

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",
    "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
    }
  }
}

Example Response

Status code: 200

Successfully registered.

{
  "instanceId" : "8540bb8b693c4ad1a7fb6a756c415244"
}

Status Code

Status Code

Description

200

OK

400

Bad Request

500

Internal Server Error

Error Code

See ServiceComb Error Codes.

Parent topic: Microservice Instance