Call the UpdateCollector operation to modify the configurations of a crawler.

Debugging

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

PUT /openapi/collectors/{ResId} HTTP/1.1

Request parameters

Parameter Type Position Required Example Description
ResId String Path Yes ct-cn-77uqof2s7rg5c****

The ID of the shipper.

ClientToken String Query No 5A2CFF0E-5718-45B5-9D4D-70B3FF****

The client token that is used to ensure the idempotence of the request. You can use the client to generate the token, but you must make sure that the token is unique among different requests. The token can contain only ASCII characters and cannot exceed 64 characters in length.

String Body No { "dryRun": false, "name": "fileBeat", "resVersion": "6.8.5_with_community", "extendConfigs": [ { "instanceId": "es-cn-sfd", "configType": "collectorElasticsearchForKibana", "hosts": [ "es-cn-abc.elasticsearch.aliyuncs.com:9200", "es-cn-abd.elasticsearch.aliyuncs.com:9200" ], "userName": "elastic", "password": "******", "protocol": "https" }, { "instanceId": "ec-cn-targ", "instanceType": "elasticsearch", "configType": "collectorTargetInstance", "hosts": [ "es-cn-abc.elasticsearch.aliyuncs.com:9200", "es-cn-abd.elasticsearch.aliyuncs.com:9200" ], "userName": "elastic", "password": "******", "protocol": "https" }, { "values": [ { "instanceId": "id1" }, { "instanceId": "id2" } ], "type": "ECSInstanceId", "configType": "collectorDeployMachine" } ], "resType": "fileBeat", "vpcId": "vpc-cn-abc", "configs": [ { "fileName": "filebeat.yml", "content": "filebeat.inputs:xxx" } ] }

The configurations of the crawler to be updated.

RequestBody

You must also enter the following parameters in the RequestBody parameter to specify the configuration information of the crawler to be updated.

Field

Type

Required

Example

Description

dryRun

boolean

Yes

false

Specifies whether to verify and update the collector. Validation values: true (only verified but not updated) and false (verified and updated).

name

String

Yes

ct-test

The name of the collector.

status

String

Yes

activing

The status of the collector. Valid values: activating and active.

resType

String

Yes

fileBeat

The shipper type. Validated values: fileBeat, metricBeat, heartBeat, and auditBeat.

vpcId

String

Yes

vpc-bp16k1dvzxtma*****

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

resVersion

String

Yes

6.8.5_with_community

The shipper version.

ownerId

String

Yes

16852099488*****

The account ID.

gmtCreatedTime

Date

Yes

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

The time when the crawer was created.

gmtUpdateTime

Date

Yes

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

The time when the collector was updated.

collectorPaths

List<String>

No

["/var/log"]

Filebeat collection path.

configs

List

Yes

The configuration file information of the collector.

└fileName

String

Yes

filebeat.yml

The name of the file.

└content

String

Yes

"filebeat.inputs:xxx"

The content of the file.

extendConfigs

Array

Yes

The extended configuration of the collector.

└configType

String

Yes

collectorElasticsearchForKibana

The configuration type. Valid values: collectorTargetInstance (Collector Output), collectorDeployMachine (Collector Deployment Machine), and collectorElasticsearchForKibana (Elasticsearch Instance Information that Supports Kibana Dashboard).

└type

String

Yes

ECSInstanceId

The type of the machine on which the Collector is deployed. Valid values: ECSInstanceId(ECS) and ACKCluster (Container Kubernetes). This field is required when the configType is set to collectorDeployMachine.

└machines

Array

No

The list of ECS instances where the crawer is deployed. This field is required when the configType is collectorDeployMachines and the type is ECSInstanceId.

└└instanceId

String

No

i-bp13y63575oypr9d****

The IDs of ECS instances.

└└agentStatus

String

No

failed

The status of the shipper on the ECS instance. Valaps: heartOk, heartLost, uninstalled, and failed.

└groupId

String

default_ct-cn-5i2l75bz4776****

The ID of the host group. This field is required when the configType is set to collectorDeployMachine.

└instanceId

String

Yes

es-cn-nif1z89fz003i****

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

└protocol

String

Yes

HTTP

The transmission protocol, which must be the same as the access protocol of the instance specified by Output. Valic values: HTTP and HTTPS. This field is required when the configType is set to collectorTargetInstance.

└userName

String

Yes

elastic

The username that is used to access the instance. The default value is elastic. This field is required when the configType is set to collectorTargetInstance or collectorElasticsearchForKibana.

└enableMonitoring

Boolean

Yes

true

Whether to enable monitoring. This field is required when the configType is collectorTargetInstance and the instanceType is Elasticsearch. Valic values: true (enabled) and false (disabled).

└hosts

List<String>

No

["es-cn-n6w1o1x*****.elasticsearch.aliyuncs.com:9200"]

The list of access addresses of the specified instance for the output of the collector. This parameter is required when the configType is set to collectorTargetInstance.

└instanceType

String

Yes

elasticsearch

The instance type specified by Collector Output. Valides: Elasticsearch and logstash. This parameter is required when the configType is set to collectorTargetInstance.

└host

String

No

es-cn-n6w1o1x0w001c****-kibana.internal.elasticsearch.aliyuncs.com:5601

The private endpoint of Kibana after you enable Kibana Dashboard. This parameter is required when the configType is set to collectorElasticsearchForKibana.

└kibanaHost

String

No

https://es-cn-nif1z89fz003i****.kibana.elasticsearch.aliyuncs.com:5601

The public endpoint of Kibana after you enable Kibana Dashboard. This field is required when the configType is set to collectorElasticsearchForKibana.

Note └ indicates a child parameter.

Special parameter description

The extendConfigs includes three configTypes: collectorTargetInstance, collectorElasticsearchForKibana, and collectorDeployMachine. The parameters to be configured vary with the deployment machine. The specific combination is as follows:

  • collectorTargetInstance

    • ECS

      configType, instanceId, instanceType, hosts, userName, password, protocol, enableMonitoring

    • ACK

      configType, instanceId, instanceType, userName, password, protocol, enableMonitoring

  • collectorElasticsearchForKibana

    • ECS

      configType, instanceId, host, kibanaHost, userName, password, and protocol

    • ACK

      configType

  • collectorDeployMachine

    • ECS

      configType, type, machines, and groupId

    • ACK

      configType, type, instanceId, totalPodsCount, and successPodsCount

Response parameters

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

The ID of the request.

Result Object

The returned result.

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

The ID of the shipper.

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

The time when the collector was updated.

dryRun Boolean false

Specifies whether to verify and update the collector. Valid values:

  • true: only verifies but does not update the data.
  • false: verifies and updates the data.
ownerId String 16852099488*****

The account ID.

vpcId String vpc-bp16k1dvzxtma*****

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

resType String fileBeat

The shipper type. FileBeat, metricBeat, heartBeat, and auditBeat are supported.

resVersion String 6.8.5_with_community

The shipper version.

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

The time when the crawer was created.

status String active

The status of the collector. Valid values:

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

The name of the collector.

configs Array of configs

The configuration file information of the collector.

content String filebeat.inputs:xxx

The file contains the following content:
fileName String filebeat.yml

File name
extendConfigs Array of extendConfigs

The information about the extended parameter.

successPodsCount String 8

The number of collected pods in the ACK cluster. Displayed when the configType is collectorDeployMachines and the type is ACKCluster.

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.

totalPodsCount String 10

The number of collected pods in the ACK cluster. Displayed when the configType is collectorDeployMachines and the type is ACKCluster.

type String ECSInstanceId

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

  • ECSInstanceId:ECS
  • ACKCluster: Container Kubernetes
kibanaHost String https://es-cn-nif1z89fz003i****.kibana.elasticsearch.aliyuncs.com:5601

The public endpoint of Kibana after you enable Kibana Dashboard. Displayed when the configType is collectorElasticsearchForKibana.

enableMonitoring Boolean true

Whether Monitoring is enabled. This field is displayed when the configType is collectorTargetInstance and the instanceType is Elasticsearch. You can set this parameter to true or false.

configType String collectorDeployMachine

The configuration type. Valid values:

  • collectorTargetInstance: Collector Output
  • collectorDeployMachine: Collector Deployment Machine
  • collectorElasticsearchForKibana: 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.

groupId String default_ct-cn-5i2l75bz4776****

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

host String es-cn-n6w1o1x0w001c****-kibana.internal.elasticsearch.aliyuncs.com:5601

The private endpoint of Kibana after you enable Kibana Dashboard. Displayed when the configType is collectorElasticsearchForKibana.

instanceId String es-cn-nif1z89fz003i****

The ID of the instance that is associated with the crawer. 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

collectorDeployMachine Type Specific:

Deploy ECS instances /ACK clusters
agentStatus String heartOk

The status of the shipper on the ECS instance. Valid values:

  • heartOk: The heartbeat is normal.
  • heartLost: The heartbeat is abnormal.
  • uninstalled: The shipper is not installed.
  • failed: The shipper fails to be installed.
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.

Examples

Sample requests

PUT /openapi/collectors/ct-cn-77uqof2s7rg5c**** HTTP/1.1
Common request headers

{
    "dryRun": false, 
    "name": "fileBeat", 
    "resVersion": "6.8.5_with_community", 
    "extendConfigs": [
        {
            "instanceId": "es-cn-sfd", 
            "configType": "collectorElasticsearchForKibana", 
            "hosts": [
                "es-cn-abc.elasticsearch.aliyuncs.com:9200", 
                "es-cn-abd.elasticsearch.aliyuncs.com:9200"
            ], 
            "userName": "elastic", 
            "password": "******", 
            "protocol": "https"
        }, 
        {
            "instanceId": "ec-cn-targ", 
            "instanceType": "elasticsearch", 
            "configType": "collectorTargetInstance", 
            "hosts": [
                "es-cn-abc.elasticsearch.aliyuncs.com:9200", 
                "es-cn-abd.elasticsearch.aliyuncs.com:9200"
            ], 
            "userName": "elastic", 
            "password": "******", 
            "protocol": "https"
        }, 
        {
            "values": [
                {
                    "instanceId": "id1"
                }, 
                {
                    "instanceId": "id2"
                }
            ], 
            "type": "ECSInstanceId", 
            "configType": "collectorDeployMachine"
        }
    ], 
    "resType": "fileBeat", 
    "vpcId": "vpc-cn-abc", 
    "configs": [
        {
            "fileName": "filebeat.yml", 
            "content": "filebeat.inputs:xxx"
        }
    ]
}

Sample success responses

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

{
  "RequestId" : "5FFD9ED4-C2EC-4E89-B22B-1ACB6FE1D***",
  "Result" : {
    "configs" : {
      "fileName" : "filebeat.yml",
      "content" : "filebeat.inputs:xxx"
    },
    "dryRun" : false,
    "resType" : "fileBeat",
    "ownerId" : "16852099488*****",
    "resId" : "ct-cn-0v3xj86085dvq****",
    "collectorPaths" : [ "/var/log" ],
    "gmtUpdateTime" : "2020-06-20T07:26:47.000+0000",
    "extendConfigs" : [ {
      "enableMonitoring" : true,
      "groupId" : "default_ct-cn-5i2l75bz4776****",
      "instanceType" : "elasticsearch",
      "type" : "ECSInstanceId",
      "userName" : "elastic",
      "configType" : "collectorDeployMachine",
      "protocol" : "HTTP",
      "instanceId" : "es-cn-nif1z89fz003i****",
      "host" : "es-cn-n6w1o1x0w001c****-kibana.internal.elasticsearch.aliyuncs.com:5601",
      "kibanaHost" : "https://es-cn-nif1z89fz003i****.kibana.elasticsearch.aliyuncs.com:5601",
      "totalPodsCount" : 10,
      "successPodsCount" : 8
    }, {
      "machines" : {
        "agentStatus" : "heartOk",
        "instanceId" : "i-bp13y63575oypr9d****"
      }
    }, {
      "hosts" : [ "es-cn-n6w1o1x*****.elasticsearch.aliyuncs.com:9200" ]
    } ],
    "resVersion" : "6.8.5_with_community",
    "vpcId" : "vpc-bp16k1dvzxtma*****",
    "name" : "ct-test",
    "gmtCreatedTime" : "2020-06-20T07:26:47.000+0000",
    "status" : "active"
  }
}

Error codes

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