Creates a shipper.

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

POST /openapi/collectors HTTP/1.1

Request parameters

Parameter Type Location Required Example Description
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 value, but you must ensure that the value is unique among different requests. The token can contain only ASCII characters and cannot exceed 64 characters in length.

Object Body No

The request body parameters. Used to specify the configuration information of the crawker to be created.

dryRun Boolean Body Yes true

Specifies whether to verify and create a crawler. This parameter is used only when you create or update a crawler. Valid values:

  • true: only verifies but does not update the data.
  • false: verifies and updates.
name String Body Yes ct-test

The name of the collector. The name must be 1 to 30 characters in length and can contain letters, digits, underscores (_), and hyphens (-). The name must start with a letter.

resType String Body Yes fileBeat

The type of the collector. Valids: fileBeat, metricBeat, heartBeat, and auditBeat.

vpcId String Body Yes vpc-bp12nu14urf0upaf*****

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

resVersion String Body Yes 6.8.5_with_community

The version of the collector. Valid values:

  • ECS-based deployment:6.8.5_with_community
  • Deployment based on ACK 6.8.13 _with_community
collectorPaths Array of String Body No ["/var/log"]

The path of the fileBeat collection. This parameter is required only when the collector is installed on an ECS instance.

configs Array Body Yes

The configuration file information of the collector.

fileName String Body Yes filebeat.yml

The name of the file.

content String Body Yes "filebeat.inputs:xxx"

The content of the file.

extendConfigs Array of Object Body Yes { "instanceId": "es-cn-nif201ihd0012****", "instanceType": "elasticsearch", "configType": "collectorTargetInstance", "hosts": [ "es-cn-nif201ihd0012****.elasticsearch.aliyuncs.com:9200" ], "userName": "elastic", "password": "*****", "protocol": "HTTP" }, { "type": "ECSInstanceId", "configType": "collectorDeployMachine", "machines": [ { "instanceId": "i-bp11u91xgubypcuz****" } ] } ]

The extended configuration of the collector. For more information, see the following section of the extendConfigs parameter.

Description of the extendConfigs parameter

The following table describes the parameters in extendConfigs.

Parameter

Type

Required

Example

Description

extendConfigs

Array

The extended configuration of the collector.

└configType

String

Yes

collectorElasticsearchForKibana

The configuration type. Valid values: collectorTargetInstance (Collector Output), collectorDeployMachine (Collector Deployment Machine), and collector Elasticsearch ForKibana (Elasticsearch instance information that supports the Kibana dashboard).

└type

String

No

ECSInstanceId

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

└instanceType

String

No

elasticsearch

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

└instanceId

String

Yes

es-cn-nif201ihd0012****

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 of the crawler. 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

No

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

└└instanceId

String

Yes

i-bp11u91xgubypcuz****

The IDs of ECS instances.

└groupId

String

default_ct-cn-5i2l75bz4776****

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

└protocol

String

No

HTTP

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

└userName

String

No

elastic

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

└password

String

No

*****

The password of the corresponding username.

└enableMonitoring

Boolean

No

true

Indicates whether monitoring is enabled. This parameter is required when configType is collectorTargetInstance and instanceType is Elasticsearch. Valid values: true (enabled) and false (disabled).

└hosts

List<String>

No

["es-cn-nif201i*****.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.

└host

String

No

es-cn-nif201ihd0012****-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-nif201ihd0012****.kibana.elasticsearch.aliyuncs.com:5601

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

Note └ indicates a child parameter.

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, and instanceId

Response parameters

Element Type Example Description
RequestId String 8466BDFB-C513-4B8D-B4E3-5AB256AB****

The ID of the request.

Result Object

The returned result.

resId String ct-cn-4135is2tj194p****

The ID of the created crawer.

Examples

Sample requests

POST /openapi/collectors?clientToken=5A2CFF0E-5718-45B5-9D4D-70B3FF**** HTTP/1.1
Host:elasticsearch.aliyuncs.com
Content-Type:application/json

{
    "dryRun": false, 
    "name": "test_beats_1", 
    "resType": "fileBeat", 
    "resVersion": "6.8.5_with_community", 
    "vpcId": "vpc-bp12nu14urf0upaf*****", 
    "collectorPaths": [
        "/var/log"
    ], 
    "extendConfigs": [
        {
            "instanceId": "es-cn-nif201ihd0012****", 
            "instanceType": "elasticsearch", 
            "configType": "collectorTargetInstance", 
            "hosts": [
                "es-cn-nif201ihd0012****.elasticsearch.aliyuncs.com:9200"
            ], 
            "userName": "elastic", 
            "password": "*****", 
            "protocol": "HTTP"
        }, 
        {
            "type": "ECSInstanceId", 
            "configType": "collectorDeployMachine", 
            "machines": [
                {
                    "instanceId": "i-bp11u91xgubypcuz****"
                }
            ]
        }
    ], 
    "configs": [
        {
            "fileName": "filebeat.yml", 
            "content": "filebeat.inputs:xxx"
        }, 
        {
            "fileName": "fields.yml", 
            "content": "- key: log\n title: Log file content\n description: >\n Contains log file lines.\n ...."
        }
    ]
}

Sample success responses

JSON format 

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

{
  "Result" : {
    "resId" : "ct-cn-4135is2tj194p****"
  },
  "RequestId" : "8466BDFB-C513-4B8D-B4E3-5AB256AB****"
}

Error code

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