Help Center/ Cloud Service Engine/ API Reference/ ServiceComb API/ Microservice Instance/ Querying Microservice Instances in Batches
Updated on 2023-11-08 GMT+08:00

Querying Microservice Instances in Batches

Function

This API is used to query microservice instances in batches based on microservice field filter criteria after the instances are registered.

URI

POST /v4/{project_id}/registry/instances/action

Table 1 Path parameter

Parameter

Mandatory

Type

Description

project_id

Yes

String

Fixed value: default.

Table 2 Query parameter

Parameter

Mandatory

Type

Description

type

Yes

String

Operation type. Currently, only query is supported.

Request

Table 3 Request header parameters

Parameter

Mandatory

Type

Description

X-consumerId

No

String

Microservice consumer ID, which must be unique.

Authorization

No

String

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

The token of an exclusive ServiceComb 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 ServiceComb Engine.

Table 4 Request body parameters

Parameter

Mandatory

Type

Description

services

At least one of the two parameters must be specified.

Array of FindService objects

Structure for querying service information.

instances

Array of FindInstance objects

Structure for querying instance information.

Table 5 FindService

Parameter

Mandatory

Type

Description

service

Yes

DependencyKey object

Dependency item.

rev

No

String

Version number of the client cache, which determines the difference between the local cache and the microservice in the service center.

  • Input 0 for the first time.
  • If the input rev is the same as that of the current microservice, notModified is returned. If they are different, updated is returned.
  • If rev is required in the next request, use the value of rev in updated in the response body.
Table 6 DependencyKey

Parameter

Mandatory

Type

Description

environment

Yes

String

Environment. Value: development, testing, acceptance, or production.

appId

Yes

String

Application ID, which must be unique.

serviceName

Yes

String

Microservice name

Table 7 FindInstance

Parameter

Mandatory

Type

Description

instance

No

HeartbeatSetElement object

Request struct of a microservice instance.

rev

No

String

Version number cached by the client.

Version number of the client cache, which determines the difference between the local cache and the microservice instance in the service center.

  • Input 0 for the first time.
  • If the input rev is the same as that of the current microservice instance, notModified is returned. If they are different, updated is returned.
  • If rev is required in the next request, use the value of rev in updated in the response body.
Table 8 HeartbeatSetElement

Parameter

Mandatory

Type

Description

serviceId

No

String

Microservice ID.

instanceId

No

String

Microservice instance ID.

Response

Status code: 200

Table 9 Response body parameters

Parameter

Type

Description

services

BatchFindResult object

Batch query result structure.

instances

BatchFindResult object

Batch query result structure.

Table 10 BatchFindResult

Parameter

Type

Description

failed

Array of FindFailedResult objects

Query failure result structure.

notModified

Array of integers

Index set corresponding to the request array.

updated

Array of FindResult objects

Query result structure list.

Table 11 FindFailedResult

Parameter

Type

Description

indexes

Array of integers

Index set corresponding to the request array.

error

Error object

Error struct.

Table 12 Error

Parameter

Type

Description

errorCode

String

Error code.

errorMessage

String

Error message.

detail

String

Location details.

Table 13 FindResult

Parameter

Type

Description

index

Integer

Index corresponding to the request array.

rev

String

Versions returned by the server. If the versions are the same as the versions cached on the client, the instances parameter is left empty.

instances

Array of MicroServiceInstance objects

Instance list.

Table 14 MicroServiceInstance

Parameter

Type

Description

instanceId

String

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

serviceId

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

String

Microservice version.

hostName

String

Host information.

endpoints

Array of strings

Access address information.

status

String

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

properties

Object

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

healthCheck

HealthCheck object

Health check information.

dataCenterInfo

DataCenterInfo object

Data center information.

timestamp

String

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

modTimestamp

String

Update time.

Table 15 HealthCheck

Parameter

Type

Description

mode

String

Heartbeat mode. Value: push or pull.

port

Integer

Port.

interval

Integer

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

times

Integer

Maximum retries.

Table 16 DataCenterInfo

Parameter

Type

Description

name

String

Region name.

region

String

Region.

availableZone

String

AZ.

Status code: 400

Table 17 Response body parameters

Parameter

Type

Description

errorCode

String

Error code.

errorMessage

String

Error message.

detail

String

Location details.

Status code: 500

Table 18 Response body parameters

Parameter

Type

Description

errorCode

String

Error code.

errorMessage

String

Error message.

detail

String

Location details.

Example Request

Query all instances of the microservice whose application ID is default and microservice name is test.

POST https://{endpoint}/v4/{project_id}/registry/instances/action?type=query
{
  "services": [
    {
      "service": {
        "environment": "",
        "appId": "default",
        "serviceName": "test"
      },
      "rev": "0"
    }
  ]
}

Example Response

Status code: 200

Successfully queried.

{
    "services": {
        "updated": [
            {
                "index": 0,
                "rev": "0feb784798bca7b2fb4de8351578c4437b516c4b",
                "instances": [
                    {
                        "instanceId": "79cdaf47cacf43a5b2b4185527da2255",
                        "serviceId": "8aed80ea052ac04a64dfc79c24f2170224d074f5",
                        "endpoints": [
                            "rest:127.0.0.1:8080"
                        ],
                        "hostName": "hostNameTest",
                        "status": "UP",
                        "properties": {
                            "engineID": "30c263e5-2eac-4da1-9c72-5abb9ac94550",
                            "engineName": "cse-fkln1-HA"
                        },
                        "healthCheck": {
                            "mode": "push",
                            "interval": 30,
                            "times": 3
                        },
                        "timestamp": "1650546183",
                        "modTimestamp": "1650546183",
                        "version": "1.0.0"
                    }
                ]
            }
        ]
    }
}

Status Code

Status Code

Description

200

OK

400

Bad Request

500

Internal Server Error

Error Code

See ServiceComb Error Codes.