产品定价 立即试用
IoT网关
社区版 专业版 云平台 边缘 PE边缘 IoT网关 许可证服务器 Trendz Analytics 移动应用 PE移动应用 MQTT Broker PE MQTT Broker
文档 > 配置指南 > FTP连接器
入门
安装
目录

FTP连接器配置

本指南将帮助您熟悉ThingsBoard IoT Gateway的FTP连接器配置。 请使用通用配置启用此连接器。 该连接器的用途是连接外部FTP服务器并从指定路径的文件中获取数据。 连接器还能根据ThingsBoard的更新或命令将数据推送到FTP服务器文件。

当您的设备上有FTP服务器或外部资源中有数据并希望将这些数据推送至ThingsBoard时，此连接器非常有用。

下面我们将详细介绍连接器配置文件。

连接器配置：ftp.json

连接器配置是一个JSON文件，包含如何连接到外部FTP服务器、读取数据时使用哪些路径以及如何处理数据的信息。 让我们通过以下示例来了解配置文件的格式。

FTP连接器配置文件示例。

以下示例将连接到部署在IP为0.0.0.0的服务器上的本地网络FTP服务器。 连接器将使用用户名和密码进行基本FTP认证。 然后，连接器将订阅映射部分中的路径列表。更多信息请参阅下方描述。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

{
  "host": "0.0.0.0",
  "port": 21,
  "TLSSupport": false,
  "security": {
    "type": "basic",
    "username": "admin",
    "password": "admin"
  },
  "paths": [
    {
      "devicePatternName": "asd",
      "devicePatternType": "Device",
      "delimiter": ",",
      "path": "fol/*_hello*.txt",
      "readMode": "FULL",
      "maxFileSize": 5,
      "pollPeriod": 5,
      "txtFileDataView": "SLICED",
      "withSortingFiles": true,
      "attributes": [
        {
          "key": "temp",
          "value": "[1:]"
        },
        {
          "key": "tmp",
          "value": "[0:1]"
        }
      ],
      "timeseries": [
        {
          "type": "int",
          "key": "[0:1]",
          "value": "[0:1]"
        },
        {
          "type": "int",
          "key": "temp",
          "value": "[1:]"
        }
      ]
    }
  ],
  "attributeUpdates": [
    {
      "path": "fol/hello.json",
      "deviceNameFilter": ".*",
      "writingMode": "WRITE",
      "valueExpression": "{'${attributeKey}':'${attributeValue}'}"
    }
  ],
  "serverSideRpc": [
    {
      "deviceNameFilter": ".*",
      "methodFilter": "read",
      "valueExpression": "${params}"
    },
    {
      "deviceNameFilter": ".*",
      "methodFilter": "write",
      "valueExpression": "${params}"
    }
  ]
}

通用配置部分

参数 默认值 描述
host localhost 服务器的域名地址或IP。
port 21 服务器的端口。
TLSSupport true 验证服务器是否支持TLS。

子配置”security”

“security”子配置提供FTP服务器客户端授权的配置。

基本认证推荐
匿名无安全认证

Basic 是一种安全配置方式。 授权时将使用本配置节中提供的 username 和 password 组合。

参数 默认值 说明
type basic 授权类型。
username username 授权用户名。
password password 授权密码。

配置文件中的 security 配置小节将如下所示：

1
2
3
4
5

    "security": {
      "type": "basic",
      "username": "username",
      "password": "password"
    }

Anonymous 认证是最简单的选项，适合在公共 FTP 服务器上测试。

参数 默认值 说明
type anonymous 授权类型。

配置文件中的 security 配置小节将如下所示：

1
2
3

    "security": {
      "type": "anonymous"
    }

“paths”配置部分

此配置部分包含一个路径对象数组，网关连接到服务器后将尝试读取这些路径。 此外，该部分还包含处理传入消息（转换器）的设置。

参数 默认值 描述
path data/log.txt 用于读取数据的文件路径。

注意：请确保您的文件扩展名是FTP连接器支持的扩展名之一（.txt、.json、.csv）。

path支持特殊符号，例如’*‘，允许订阅多个路径和文件。 让我们看看使用path参数的其他示例：

示例名称 路径 说明
示例1 data/log.txt 从单个文件读取数据（如果存在）
示例2 data/*/log.txt 从包含data文件夹的所有文件夹中读取所有log.txt文件
示例3 data/*/*_log.txt 从包含data文件夹的所有文件夹中读取文件名包含_log.txt的所有文件
示例3 data/*.* 读取data文件夹中所有支持扩展名的所有文件

现在让我们查看path部分中的其他必需参数。

参数 可用值 描述
delimiter , 用于分割文件中数据的符号
readMode FULL/PARTIAL 如果参数等于FULL，文件将从头读到尾。如果参数等于PARTIAL，文件将从上次读取的行开始读取
maxFileSize 5 将被读取的最大文件大小（MB）（如果文件大小超过5MB，将被跳过）
pollPeriod 60 读取路径中文件的时间周期（秒）
txtFileDataView TABLE/SLICED txtFileDataView参数仅用于.txt文件
withSortingFiles true/false 路径中找到的文件将如何追加到数组中
attributes   此子配置包含传入消息的参数，将被解释为设备的属性。
timeseries   此子配置包含传入消息的参数，将被解释为设备的遥测数据。

让我们看看如何为不同的文件扩展名配置此部分：

1.用于TABLE数据视图的.txt文件和.csv文件 json "paths": [ { "devicePatternName": "${temp}", "devicePatternType": "Device", "delimiter": ",", "path": "fol/*.*", "readMode": "FULL", "maxFileSize": 5, "pollPeriod": 60, "txtFileDataView": "TABLE", "withSortingFiles": true, "attributes": [ { "type": "int", "key": "key", "value": "${temp}" } ], "timeseries": [ { "type": "int", "key": "${hum}", "value": "${temp}" }, { "type": "int", "key": "temp", "value": "${hum}" } ] } ] 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111

这意味着FTP转换器将查找以下文件结构：
```txt
temp,hum
1,2
23,34
``` 2.用于SLICED数据视图的.txt文件
```json
  "paths": [
    {
      "devicePatternName": "DeviceName",
      "devicePatternType": "[0:1]",
      "delimiter": ",",
      "path": "fol/table.txt",
      "readMode": "FULL",
      "maxFileSize": 5,
      "pollPeriod": 60,
      "txtFileDataView": "SLICED",
      "withSortingFiles": true,
      "attributes": [
        {
          "key": "temp",
          "value": "[1:]"
        },
        {
          "key": "tmp",
          "value": "[0:1]"
        }
      ],
      "timeseries": [
        {
          "type": "int",
          "key": "[0:1]",
          "value": "[0:1]"
        },
        {
          "type": "int",
          "key": "temp",
          "value": "[1:]"
        }
      ]
    }
  ]    
```

这意味着FTP转换器将查找以下文件结构：
```txt
1,2
23,34
``` 3.用于.json文件
```json
"paths": [
    {
      "devicePatternName": "${temp}",
      "devicePatternType": "Device",
      "delimiter": ",",
      "path": "fol/*.json",
      "readMode": "FULL",
      "maxFileSize": 5,
      "pollPeriod": 60,
      "withSortingFiles": true,
      "attributes": [
        {
          "type": "int",
          "key": "key",
          "value": "${temp}"
        }
      ],
      "timeseries": [
        {
          "type": "int",
          "key": "key",
          "value": "${temp}"
        },
        {
          "type": "int",
          "key": "temp",
          "value": "${tmp}"
        }
      ]
    }
  ]
``` 4.组合attributes、telemetry和serverSideRpc部分，例如在.json文件中：   ```json   "paths": [
      {
        "devicePatternName": "${temp}",
        "devicePatternType": "Device",
        "delimiter": ",",
        "path": "fol/*.json",
        "readMode": "FULL",
        "maxFileSize": 5,
        "pollPeriod": 60,
        "withSortingFiles": true,
        "attributes": [],
        "timeseries": [
          {
            "type": "int",
            "key": "hum",
            "value": "${hum}"
          },
          {
            "type": "int",
            "key": "temp",
            "value": "${tmp}"
          },
          {
            "type": "string",
            "key": "combine",
            "value": "${tmp}::${hum}"
          }
        ]
      }
    ]   ```

子配置”converter”

此配置部分是可选的，仅在您希望使用自定义FTP转换器处理传入数据时使用。

典型使用场景：

-默认不支持扩展名的文件，或支持的扩展名但数据结构不同的文件，例如： -没有标题行的CSV文件 -字段位于固定列位置的CSV行

在此示例中，我们展示了一个无标题CSV文件的配置，其中设备名称、属性和遥测值通过列索引获取。

配置中的映射子部分如下所示：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

{
  "converter": {
    "type": "custom",
    "extension": "CustomFTPtUplinkConverter",
    "extension-config": {
      "devicePatternName": 0,
      "devicePatternType": 1,
      "attributes": [
        {
          "key": "meterAddress",
          "column": 0,
          "type": "string"
        }
      ],
      "timeseries": [
        {
          "key": "meterReading",
          "column": 2,
          "type": "double"
        },
        {
          "key": "batteryAlert",
          "column": 3,
          "type": "int"
        }
      ]
    }
  }
}

以下是此配置中用于自定义转换器的每个参数的描述。

顶层converter参数：

  1. converter.type
    必须设置为custom。这会告诉FTP连接器使用自定义转换器而非内置转换器。

  2. converter.extension
    实现自定义转换器的Python类名称，例如CustomFTPtUplinkConverter。

extension-config字段：

  1. devicePatternName
    用于解析设备名称的列索引。在示例中，0表示设备名称取自第0列。

  2. devicePatternType
    用于解析设备类型的列索引或字面值。在示例中，1表示设备类型取自第1列。

  3. attributes
    属性映射数组。每个元素描述如何从特定CSV列读取单个设备属性。

  4. timeseries
    遥测映射数组。每个元素描述如何从特定CSV列读取单个遥测值。

attributes和timeseries元素： attributes和timeseries的每个元素具有相同的结构：

  1. key
    将出现在ThingsBoard平台已创建设备上的属性或遥测键（例如meterAddress、meterReading）。

  2. column
    CSV行中取值的从零开始的列索引。

  3. type
    目标值类型。自定义转换器会将原始字符串转换为此类型（例如string、int、double）。

文档信息图标

具体行为取决于您自己的CustomFTPtUplinkConverter实现，但此配置展示了一个适用于无标题CSV文件的可用示例。 您很可能需要更改映射值（devicePatternName、devicePatternType、attributes、timeseries）以匹配您的文件格式，但参数名称和结构必须保持不变。

“attributeUpdates”配置部分

此配置部分是可选的。 ThingsBoard允许配置设备属性并从设备应用程序获取部分属性。您可以将其视为设备的远程配置，使设备能够从ThingsBoard请求共享属性。详见用户指南。

“attributeRequests”配置允许您配置将写入特定文件的相应属性数据的格式。

参数 默认值 描述
path fol/${attributeKey}/${attributeValue}.txt 用于查找特定文件的JSON路径表达式
deviceNameFilter .* 正则表达式设备名称过滤器，用于确定执行哪个功能。
writingMode OVERRIDE/WRITE 如果writingMode等于OVERRIDE，找到的文件将被覆盖。如果writingMode等于WRITE，新数据将追加到找到的文件末尾。
valueExpression ,,,,${attributeKey},,,${attributeValue} 用于创建将发送到FTP服务器的消息数据的表达式。’,’作为分隔符，您可以在其前面插入数据。

配置文件中此部分如下所示：

1
2
3
4
5
6
7
8

  "attributeUpdates": [
    {
      "path": "fol/${attributeKey}/${attributeValue}.txt",
      "deviceNameFilter": ".*",
      "writingMode": "OVERRIDE",
      "valueExpression": ",,,,${attributeKey},,,${attributeValue}"
    }
  ]

服务端RPC命令

ThingsBoard允许向直接连接到ThingsBoard或通过网关连接的设备发送RPC命令。

此部分提供的配置用于从ThingsBoard向设备发送RPC请求。

参数 默认值 描述
deviceNameFilter .* 正则表达式设备名称过滤器，用于确定执行哪个功能。
methodFilter read/write 文件打开模式
valueExpression ,,,,${attributeKey},,,${attributeValue} JSON路径表达式，用于创建发送到FTP服务器的数据，当methodFilter等于write时使用。如果methodFilter等于read，则忽略此字段。

配置文件中此部分如下所示：

1
2
3
4
5
6
7
8
9
10
11
12

"serverSideRpc": [
  {
    "deviceNameFilter": ".*",
    "methodFilter": "read",
    "valueExpression": "${params}"
  },
  {
    "deviceNameFilter": ".*",
    "methodFilter": "write",
    "valueExpression": "${params}"
  }
]

让我们来看一些示例。

读取数据示例

假设您想从已连接的FTP服务器上的文件中读取数据。前往已启用的FTP连接器RPC页面，使用以下配置填写字段并点击”Send“按钮：

image

之后，响应将显示在”Response“字段中：

image

写入数据示例

文档信息图标

请确保您要写入数据的文件具有适当的权限。 否则，您将收到550 Permission denied错误。

假设您想向已连接的FTP服务器上的文件写入一些数据。前往已启用的FTP连接器RPC页面，使用以下配置填写字段并点击”Send“按钮：

image

之后，响应将显示在”Response“字段中：

image

让我们检查数据是否已写入FTP服务器上的文件，为此请使用之前描述的”读取数据“示例：

image

您的响应应包含您写入文件的数据，如下图所示：

image

下一步

浏览与ThingsBoard主要功能相关的指南：