When you create a Beats collector, call the ListEcsInstances to obtain the list of ECS instances.

Important To call this operation, you must create the Aliyun Elasticsearch AccessingOOSRole and the system service role AliyunOOSAccessingECS 4ESRole to Elasticsearch the service account to obtain the ECS access permissions of the primary account. For more information, see Collect ECS service logs.


OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request headers

This operation uses only common request headers. For more information, see Common request headers.

Request syntax

GET /openapi/ecs HTTP/1.1

Request parameters

Parameter Type Location Required Example Description
page Integer Query No 1

The number of returned result pages. The maximum value is 500.

size Integer Query No 10

The number of results contained per page. Default value: 10. Maximum value: 500.

ecsInstanceIds String Query No ["i-bp13y63575oypr9d****","i-bp1gyhphjaj73jsr****"]

The ID of ECS instance N. The value can be a JSON array that consists of up to 100 instance IDs. Separate the instance IDs with commas (,).

ecsInstanceName String Query No test

The name of the ECS instance.

tags String Query No [{ "tagKey":"a","tagValue":"b"}]

The tags of the ECS instance, which must contain:

  • tagKey: tag key
  • tagValue: tag value
vpcId String Query No vpc-bp16k1dvzxtmagcva****

The ID of the VPC to which the ECS instance belongs.

Response parameters

Parameter Type Example Description
RequestId String 5FFD9ED4-C2EC-4E89-B22B-1ACB6FE1D***

The ID of the request.

Headers Object

The header of the response.

X-Total-Count Integer 11

The number of returned records.

Result Array of Result

The returned data.

cloudAssistantStatus String true

Cloud Assistant the installation status, support:

  • true: The Prometheus agent was installed.
  • false: The Prometheus agent was not installed.
ecsInstanceName String ecsTestName

The name of the ECS instance.

ecsInstanceId String i-bp14ncqge8wy3l3d****

The ID of the ECS instance.

tags String [ { "tagKey": "a", "tagValue": "b" } ]

The tags of the ECS instance.

osType String linux

The operating system type of the ECS instance. Valid values:

  • windows:Windows operating system
  • linux:Linux operating system
status String running

The status of the ECS instance. Valid values:

  • running: The master instance is running
  • starting
  • stopping: The task is being stopped.
  • stopped: The node is stopped.
ipAddress Array of ipAddress

The IP address of the ECS instance.

ipType String private

The type of the IP address that is used by the instance. Valid values:

  • public: public endpoint
  • private: private network address
host String 172.16.xx.xx

The IP address of the endpoint.

collectors Array of collectors

The information about the collectors on the ECS instance.

resId String ct-cn-0v3xj86085dvq****

The ID of the collector instance.

gmtUpdateTime String 2020-06-20T07:26:47.000+0000

The time when the collector was updated.

dryRun Boolean false

Specifies whether to verify and create a crawer. Valid values:

  • true: only verifies and does not create a
  • false: verifies and creates a
ownerId String 16852***488*****

The ID of the Alibaba Cloud account.

vpcId String vpc-bp16k1dvzxtm******

The ID of the Virtual Private Cloud to which the collector belongs.

resType String fileBeat

The type of the collector. FileBeat, metricBeat, heartBeat, and auditBeat are supported.

resVersion String 6.8.5_with_community

The version of the collector. If the machine type of the collector is ECS, only 6.8.5_with_community is supported.

gmtCreatedTime String 2020-06-20T07:26:47.000+0000

The time when the crawl collector was created.

status String activing

The status of the collector. Valid values:

  • activating: The project is taking effect.
  • active: The instance has taken effect.
name String ct-testAbc

The name of the collector.

configs Array of configs

The configuration file information of the collector.

content String - key: log\n title: Log file content\n description: >\n Contains log file lines.\n ....

The content of the file.

fileName String fields.yml

The name of the file.

extendConfigs Array of extendConfigs

The information about the extended parameter.

enableMonitoring Boolean true

Whether Monitoring is enabled. This field is displayed when the configType is collectorTargetInstance and the instanceType is Elasticsearch. Valid values:

  • true
  • false
groupId String default_ct-cn-5i2l75bz4776****

The ID of the host group. Displayed when the configType is collectorDeployMachine.

configType String collectorDeployMachine

The configuration type. Valid values:

  • collectorTargetInstance: Collector Output
  • collectorDeployMachine: Collector Deployment Machine
  • Collector Elasticsearch ForKibana: Elasticsearch instance information that supports the Kibana dashboard
instanceType String elasticsearch

The instance type specified by Collector Output. Supports Elasticsearch and Logstash. Displayed when the configType is collectorTargetInstance.

protocol String HTTP

The transmission protocol, which must be the same as the access protocol of the instance specified by Output. HTTP and HTTPS. Displayed when the configType is collectorTargetInstance.

userName String elastic

The username that is used to access the instance. The default value is elastic. Displayed when the configType is collectorTargetInstance or collectorElasticsearchForKibana.

type String ECSInstanceId

The type of the machine on which the Collector is deployed. This parameter is displayed when the configType is collectorDeployMachine. Valid values:

  • ECSInstanceId:ECS
  • ACKCluster: Container Kubernetes
instanceId String es-cn-nif1z89fz003i****

The ID of the instance that is associated with the crawker. If the configType parameter is set to collectorTargetInstance, the value of this parameter is the ID of the output collector. If the configType parameter is set to collectorDeployMachines and the type parameter is set to ACKCluster, the value of this parameter is the ID of the ACK cluster.

machines Array of machines

The list of ECS instances on which the collector is deployed. Displayed when the configType is collectorDeployMachines and the type is ECSInstanceId.

agentStatus String heartOk

The status of each crawl on the ECS instance. Valid values:

  • heartOk: The heartbeat is normal.
  • heartLost: The heartbeat is abnormal.
  • uninstalled
  • failed: The installation failed.
instanceId String i-bp13y63575oypr9d****

The IDs of ECS instances.

hosts Array of String ["es-cn-n6w1o1x*****.elasticsearch.aliyuncs.com:9200"]

The list of access addresses of the specified instance for the output of the collector. Displayed when the configType is collectorTargetInstance.

collectorPaths Array of String ["/var/log"]

The path in which Filebeat is collected.


Sample requests

GET /openapi/ecs?page=1&size=10 HTTP/1.1

Sample success responses

JSON format

HTTP/1.1 200 OK

  "Result" : [ {
    "ecsInstanceId" : "i-bp1gyhphjaj73jsr****",
    "ecsInstanceName" : "test",
    "status" : "running",
    "ipAddress" : [ {
      "host" : "47.98.xx.xx",
      "ipType" : "public"
    }, {
      "host" : "172.16.xx.xx",
      "ipType" : "private"
    } ],
    "tags" : [ ],
    "collectors" : [ {
      "gmtCreatedTime" : "2020-12-30T08:04:32.000+0000",
      "gmtUpdateTime" : "2020-12-30T08:20:48.000+0000",
      "name" : "uptime-test",
      "resId" : "ct-cn-4135is2tj194p****",
      "resVersion" : "6.8.5_with_community",
      "vpcId" : "vpc-bp16k1dvzxtmagcva****",
      "resType" : "heartBeat",
      "ownerId" : "168520994880****",
      "configs" : [ {
        "fileName" : "fields.yml"
      }, {
        "fileName" : "heartbeat.yml"
      } ],
      "status" : "active",
      "extendConfigs" : [ {
        "configType" : "collectorTargetInstance",
        "instanceId" : "es-cn-n6w1o1x0w001c****",
        "instanceType" : "elasticsearch",
        "hosts" : [ "es-cn-n6w1o1x0w001c****.elasticsearch.aliyuncs.com:9200" ],
        "protocol" : "HTTP",
        "userName" : "elastic",
        "enableMonitoring" : true
      }, {
        "configType" : "collectorDeployMachine",
        "type" : "ECSInstanceId",
        "machines" : [ {
          "instanceId" : "i-bp1gyhphjaj73jsr****",
          "agentStatus" : "heartOk"
        } ],
        "groupId" : "default_ct-cn-4135is2tj194p****"
      } ],
      "dryRun" : false
    } ],
    "osType" : "linux",
    "cloudAssistantStatus" : "true"
  } ],
  "RequestId" : "58E5DE98-33B0-4D9B-B5F6-E70A77C5933E",
  "Headers" : {
    "X-Total-Count" : 2

Error codes

For a list of error codes, see Service error codes.