文档首页/微服务引擎 CSE/API参考/ServiceComb API/微服务实例/批量查询微服务实例 - QueryMicroserviceInstancesInBatches
更新时间：2025-12-31 GMT+08:00
查看PDF
分享

批量查询微服务实例 - QueryMicroserviceInstancesInBatches

功能介绍

实例注册后可以根据微服务字段条件批量发现多个微服务的实例。

授权信息

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

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

URI

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

表1 路径参数

参数

是否必选

参数类型

描述

project_id

是

String

请填固定值：default。

表2 Query参数

参数

是否必选

参数类型

描述

type

是

String

操作类型，目前仅有“query”，表示查询。

请求参数

表3 请求Header参数

参数

是否必选

参数类型

描述

X-consumerId

否

String

微服务消费者的微服务唯一标识。

Authorization

否

String

若ServiceComb引擎专享版开启了安全认证，此参数必填。否则，无此参数。

开启了安全认证的ServiceComb引擎专享版Token，格式为：

Authorization:Bearer {Token}

Token获取方法，请参考获取ServiceComb引擎专享版用户Token。

表4 请求Body参数

参数

是否必选

参数类型

描述

services

两个参数至少必须选择一个。

Array of FindService objects

查询服务信息结构体。

instances

Array of FindInstance objects

查询实例信息结构体。

表5 FindService

参数

是否必选

参数类型

描述

service

是

DependencyKey object

依赖关系条目。

rev

否

String

客户端缓存的版本号，用于判断本地缓存和服务中心微服务的差异。

  • 首次传值0。
  • 若传入的rev值与当前的微服务的rev一致，则返回notModified；若不一致，则返回updated信息。
  • 下次请求若需要传入rev，则该值为当前返回body体中的updated中的rev的值 。
表6 DependencyKey

参数

是否必选

参数类型

描述

environment

是

String

环境信息。

取值范围：

  • development
  • testing
  • acceptance
  • production

appId

是

String

应用app唯一标识。

serviceName

是

String

微服务名称。

表7 FindInstance

参数

是否必选

参数类型

描述

instance

否

HeartbeatSetElement object

微服务实例请求结构体。

rev

否

String

客户端缓存的版本号，用于判断本地缓存和服务中心微服务实例的差异。

  • 首次传值0。
  • 若传入的rev值与当前的微服务实例的rev一致，则返回notModified；若不一致，则返回updated信息。
  • 下次请求若需要传入rev，则该值为当前返回body体中的updated中的rev的值 。
表8 HeartbeatSetElement

参数

是否必选

参数类型

描述

serviceId

否

String

微服务ID。

instanceId

否

String

微服务实例ID。

响应参数

状态码： 200

表9 响应Body参数

参数

参数类型

描述

services

BatchFindResult object

批量查询结果结构体。

instances

BatchFindResult object

批量查询结果结构体。

表10 BatchFindResult

参数

参数类型

描述

failed

Array of FindFailedResult objects

查询失败结果结构体。

notModified

Array of integers

与请求数组对应的索引集合。

updated

Array of FindResult objects

查询结果结构体列表。

表11 FindFailedResult

参数

参数类型

描述

indexes

Array of integers

与请求数组对应的索引集合。

error

Error object

异常错误结构体。

表12 Error

参数

参数类型

描述

errorCode

String

错误代码。

errorMessage

String

错误信息。

detail

String

详细定位信息。

表13 FindResult

参数

参数类型

描述

index

Integer

与请求数组对应的索引。

rev

String

服务端返回集合版本，如跟客户端缓存版本号一致，则instances为空。

instances

Array of MicroServiceInstance objects

实例列表。

表14 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：实例停止对外提供服务。

properties

Object

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

healthCheck

HealthCheck object

健康检查信息。

dataCenterInfo

DataCenterInfo object

数据中心信息。

timestamp

String

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

modTimestamp

String

更新时间。

表15 HealthCheck

参数

参数类型

描述

mode

String

心跳模式push/pull。

port

Integer

端口。

interval

Integer

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

times

Integer

最大尝试请求次数。

表16 DataCenterInfo

参数

参数类型

描述

name

String

区域名称。

region

String

区域。

availableZone

String

可用区。

状态码： 400

表17 响应Body参数

参数

参数类型

描述

errorCode

String

错误代码。

errorMessage

String

错误信息。

detail

String

详细定位信息。

状态码： 500

表18 响应Body参数

参数

参数类型

描述

errorCode

String

错误代码。

errorMessage

String

错误信息。

detail

String

详细定位信息。

请求示例

查询应用ID为default，微服务名称为test的微服务的所有实例。

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

响应示例

状态码： 200

查询成功。

{
    "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"
                    }
                ]
            }
        ]
    }
}

状态码

状态码

描述

200

查询成功。

400

错误的请求。

500

服务内部错误。

错误码

请参见ServiceComb错误码。

父主题：微服务实例