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 Position 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 it is unique among different requests. The token can only contain ASCII characters and cannot exceed 64 characters in length.

String Body No { "dryRun": false, "name": "test_beats_1", "resType": "fileBeat", "resVersion": "6.8.5_with_community", "vpcId": "vpc-bp12nu14urf0upaf*****", "collectorPaths": [ "/var/log" ], "configs": [ { "fileName": "filebeat.yml", "content": "filebeat.inputs:xxx" } ] }

The request body parameters. For more information, see the RequestBody section.

RequestBody

You must also specify the following parameters in the RequestBody parameter to specify the configurations for which you want to create a shipper.

Parameter

Type

Required

Example

Description

dryRun

Boolean

Yes

true

Specifies whether to verify and create a shipper. Use this parameter only when you create or update a shipper. Valid values: true and false.

name

String

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

Yes

fileBeat

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

resVersion

String

Yes

6.8.5_with_community

The version of the collector.

vpcId

Integer

Yes

vpc-bp12nu14urf0upaf*****

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

collectorPaths

List<String>

No

["/var/log"]

FileBeat collection path. You need to configure this parameter only when the installation machine of the collector is ECS.

configs

List

Yes

The configuration file information of the collector.

└fileName

String

Yes

filebeat.yml

The name of the source file.

└content

String

Yes

"filebeat.inputs:xxx"

The content of the file.

extendConfigs

Array

The extended configuration of the collector.

└configType

String

Yes

collectorElasticsearchForKibana

The type of the configuration. Valid values: collectorTargetInstance (Output), collectorDeployMachine (where the shipper is deployed), collector, Elasticsearch ForKibana (Elasticsearch instance information that supports the Kibana dashboard).

└type

String

No

ECSInstanceId

The type of 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 associated with the shipper. If the configType parameter is set to collectorTargetInstance, it is the instance ID of Shipper Output. If the configType parameter is set to collectorDeployMachines and the type parameter is set to ACKCluster, it is the ID of the ACK cluster.

└machines

Array

No

The information about the ECS instances where the shipper is deployed. This parameter is required if the configType is collectorDeployMachines and the type is ECSInstanceId.

└└instanceId

String

Yes

i-bp11u91xgubypcuz****

The list of ECS machine IDs.

└groupId

String

default_ct-cn-5i2l75bz4776****

The ID of the host group. This parameter is required if the configType is collectorDeployMachine.

└protocol

String

No

HTTP

The transmission protocol, which needs to be consistent with the access protocol of the instance specified by the output collector. Valid values: HTTP and HTTPS. This parameter is required when the configType is set to collectorTargetInstance.

└userName

String

No

elastic

Output specifies the username of the instance. Default value: elastic. This parameter is required when the configType is collectorTargetInstance or collectorElasticsearchForKibana.

└password

String

No

*****

The password of the corresponding username.

└enableMonitoring

Boolean

No

true

Specifies whether to enable Monitoring. This parameter is required when the configType is collectorTargetInstance and the instanceType is Elasticsearch. Valid values: true (enabled) and false (not enabled).

└hosts

List<String>

No

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

Collector Output The list of access addresses of the specified instance. 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 the 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 Kibana Dashboard is enabled. This parameter is required when the configType is set to collectorElasticsearchForKibana.

Note └ indicates a child parameter.

Special parameter description

The extendConfigs includes three configType types: collectorTargetInstance, collectorElasticsearchForKibana, and collectorDeployMachine. The parameters that need to be configured vary depending on the deployment machine. The specific combination method is as follows:

  • collectorTargetInstance
    • ECS

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

    • ACK

      configType, instanceId, instanceType, userName, password, protocol, and 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

Parameter 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 successfully created crawler.

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 codes

For a list of error codes, visit the API Error Center.