本示例将展示如何使用 Entity 的构造函数构造一个 JSON 格式的 Entity，并使用 Entity 选择器获取 Entity 的属性和数据。

• 输入
  Dataway 的运行环境依赖于组件的运行，假定在"配置 Payload"组件前已经有一个"Transform"组件，对流的运行消息 msg 的 payload 进行了设置。msg.payload 为一个字典类型对象，内部结构如下。
  

  {
  
  "name": "zhangsan",
  
  "age": 10,
  
  "male": True,
  
  "brothers": ["lisi", "zhaowu"]
  }

  
  

• Dataway 脚本
  以下 Dataway 脚本使用值构造方法将字典数据类型的 msg.payload 转换成 Entity 对象，然后用选择器获取 Entity 的元数据和元素，并返回。
  

  def
  dw_process(msg):
      entity = Entity.from_value(msg.payload, mime_type='application/json', encoding='utf-8')
  
  return {
  
  'blob': entity['^blob'],
  
  'mimeType': entity['^mime_type'],
  
  'name': entity['name'],
  
  'brother': entity['brothers'][0],
  
  'male': entity['^value']['age'],
  
  'other': entity.get('other', 'other_default')
      }

  
  

• 输出
  Dataway 的脚本输出为一个字典, 其结果如下。
  

  {
  
  "blob": b'{"name":"zhangsan","age":10,"male":true,"brothers":["lisi","zhaowu"]}',
  
  "mimeType": "application/json",
  
  "name": "zhangsan",
  
  "brother": "lisi",
  
  "male": 10,
  
  "other": "other_default"
  }

  
  :::
  ::: 示例2：复杂的 JSON 结构使用
  本示例将对复杂的 JSON 结构进行解析，并运行在”配置 Payload"组件中。
  

• 输入
  Dataway 的运行环境依赖于组件的运行，假定在”配置 Payload"组件前已经有一个"Transform"组件，对流的运行消息 msg 的 payload 进行了设置。msg.payload 为一个 Entity 类型对象，内部结构如下：
  

  {
  
  'mime_type': 'application/json',
  
  'encoding': 'utf-8',
  
  'blob': b'{"name":"zhangsan","age":10,"male":true,"brothers":["lisi","zhaowu"]'
  }

  
  

• Dataway 脚本
  以下 Dataway 脚本将对 msg 进行处理，获取对应的元素，最终返回一个 Entity 对象。
  

  def
  dw_process(msg):
      val = {
  
  "k0": msg.payload['^blob'].decode(msg.payload['^encoding']),
  
  "k1": {
  
  "str": "str",
  
  "list": [123, "abc", 12.34],
  
  "dict": {
  
  "k1": "v1"
              }
          },
  
  "k2": math.sqrt(10),
  
  "k3": json.dumps({"a": 1, "b": [1, "d"]}),
  
  "k4": time.strftime('%Y-%m-%d %H:%M:%S'),
  
  "k5": "hello"
  +
  "world",
  
  "k6": ["12", 3] + [[1, 2], 4.5],
  
  "k8": msg.payload['^mime_type'],
      }
  
  if val['k8'] ==
  'application/json':
          val['k7'] = msg.payload.get('gbk')
          val['k9'] = time.time()
  
  return Entity.from_value(val, mime_type='application/json', encoding='utf-8')

  
  

• 输出
  Dataway 脚本的输出结果为一个 Entity 类型对象，为方便说明，我们将 Entity 中的原始数据进行解析后赋值给 value 属性。
  

   {
  
  "mime_type": "application/json",
  
  "encoding": "utf-8",
  
  "value": {
  
  "k0": "{\"name\":\"zhangsan\",\"age\":10,\"male\":true,\"brothers\":[\"lisi\",\"zhaowu\"]}",
  
  "k1": {
  
  "str": "str",
  
  "list": [
  
  123,
  
  "abc",
  
  12.34
              ],
  
  "dict": {
  
  "k1": "v1"
              }
          },
  
  "k2": 3.1622776601683795,
  
  "k3": "{\"a\": 1, \"b\": [1, \"d\"]}",
  
  "k4": "2021-04-27 10:49:54",
  
  "k5": "helloworld",
  
  "k6": [
  
  "12",
  
  3,
              [
  
  1,
  
  2
              ],
  
  4.5
          ],
  
  "k8": "application/json",
  
  "k7": None,
  
  "k9": 1619491794.670995
      }
  }

  
  :::
  </dx-tabs>

HTTP 表单格式

HTTP 表单格式的数据代表 MIME 类型为 application/x-www-form-urlencoded 的 Entity 中数据解析后得到的类型。

• 使用 原始数据构造方法，则 Dataway 对输入的字符串或 bytes 类型最终解析成一个字典类型数据。

• 使用 值构造方法，支持字典或多值字典两种输入类型，并最终解析成一个多值字典类型数据。

对 HTTP 表单格式数据，由于其内部实现为多值字典数据类型，因此除了通用的 Entity 选择器语法，还支持特殊的选择器语法。

示例：构造并使用 HTTP 表单格式的 Entity

本示例将展示如何使用 Entity 的构造函数构造一个 HTTP 表单格式的 Entity，并使用 Entity 选择器语法获取 Entity 的属性和数据。

• 输入
  msg.payload 存储了 HTTP 表单格式的数据：k1=123&k2=helloworld&k3=2&k3=abc，在 Dataway 中以多值字典类型呈现，可转化为字典类型数据：
  

  {
  
  "k1": 123,
  
  "k2": "helloworld",
  
  "k3": [2, "abc"]
  }

  
  

• Dataway 脚本
  以下 Dataway 脚本使用值构造方法将字典类型数据转换成 Entity 对象，然后用选择器获取 Entity 的元数据和元素。
  

  def
  dw_process(msg):
      entity = Entity.from_value(msg.payload, mime_type='application/x-www-form-urlencoded', encoding='utf-8')
  
  return {
  
  'blob': entity['^blob'],
  
  'mimeType': entity['^mime_type'],
  
  'k1': entity['k1'],
  
  'k3': entity['^value']['k3'],
  
  'k3multi_selector': entity['^value']['*k3'],
  
  'k5': entity.get('k5', 'default_value')
      }

  
  

• 输出
  Dataway 的脚本输出为一个字典类型数据 , 结果如下。
  

  {
  
  "blob": b'k1=123&k2=helloworld&k3=2&k3=abc',
  
  "mimeType": "application/x-www-form-urlencoded",
  
  "k1": 123,
  
  "k3": 2,
  
  "k3multi_selector": [2, "abc"],
  
  "k5": "default_value"
  }

文本格式

文本格式的数据代表 MIME 类型为 text/plain 的 Entity 中数据解析后得到的类型。无论是 值构造方法 还是 原始数据构造方法，data 参数均为字符串或 bytes 类型，entity 内容均为字符串数据类型。

示例：构造文本格式的 Entity

本示例将展示如何使用 Entity 的构造函数构造一个文本格式的 Entity，并使用 Entity 选择器语法获取 Entity 的属性和数据。

• 输入
  msg. payload 存储了文本格式的数据： "This is a text plain message"。
  

• Dataway 脚本
  以下 Dataway 脚本使用值构造方法将字符串数据转换成 Entity 对象，然后用选择器获取 Entity 的元数据和元素。
  

  def
  dw_process(msg):
      entity = Entity.from_value(msg.payload, mime_type='text/plain', encoding='utf-8')
  
  return entity['^value']

  
  

• 输出
  Dataway 的脚本输出为一个字符串，结果为"This is a text plain message"。

XML 格式

XML 格式的数据代表 MIME 类型为 application/xml 的 Entity 中数据序列化后得到的类型。

• 使用 原始数据构造方法 方法，则 Dataway 对输入的字符串或 bytes 类型最终解析成一个字典数据类型。

• 使用 值构造方法，仅支持字典输入类型，并最终解析成一个字典数据结构。同时，输入的字典仅包含一个默认的键"root"，值则为内置的 MultiMap，在 MultiMap 中可以自由操作 msg 属性。

对 XML 格式数据，除了通用的 Entity 选择器语法，还支持特殊的选择器语法。

以下将通过两个示例来说明如何使用 XML 格式数据。

示例1：构造 XML 格式的 Entity

本示例将展示如何使用 Entity 的构造函数构造一个 XML 数据格式的 Entity，并使用 Entity 选择器语法获取 Entity 的属性和数据。

• 输入
  Dataway 输入参数 msg 的 payload 值为常量1，同时 msg.vars 中包含一个键为 "abc" ,值为 "123" 的键值对。
  

  {
  
  "payload": 1,
  
  "vars": {
  
  "abc": "123"
      }
  }

  
  

• Dataway 脚本
  以下 Dataway 脚本使用值构造方法将字典类型转换成 Entity 对象，并返回。
  

  def
  dw_process(msg):
      a = math.floor(1.4)
  
  return Entity.from_value({
  
  'root': {
  
  'k1': msg.vars['abc'],
  
  'k2': json.dumps('哈哈', ensure_ascii=False),
  
  'k3': a +
  1,
  
  '@id': "hello",
  
  '#text': "<a>dwad</a>",
  
  'k4': ['abc', 'def', None],
          }
      }, mime_type
  =
  'application/xml')

  
  

• 输出
  Dataway 脚本的输出结果为一个 Entity 类型对象，其中原始数据（blob）为符合 XML 语法的二进制数据，如下所示。
  

  {
  
  "mime_type": "application/xml",
  
  "encoding": "utf-8",
  
  "blob": b'<?xml version="1.0" encoding="utf-8"?>
  
  <root id="hello"><k1>123</k1><k2>"哈哈"</k2><k3>2</k3><k4>abc</k4><k4>def</k4><k4></k4><a>dwad</a></root>'
  }

示例2：使用 XML 特定选择器

本示例将示范如何在 XML 格式数据中使用特定语法的选择器。

• 输入
  Dataway 输入参数 msg 的 payload 值为常量1，同时 msg.vars 中包含一个键为 "abc" ,值为 "123" 的键值对。
  

  {
  
  "payload": 1,
  
  "vars": {
  
  "abc": "123"
      }
  }

  
  

• Dataway 脚本
  以下 Dataway 脚本使用值构造方法将字典类型转换成 Entity 对象，然后用选择器获取 Entity 的数据。
  

  def
  dw_process(msg):
      a = math.floor(1.4)
      entity =  Entity.from_value({
  
  'root': {
  
  'k1': msg.vars['abc'],
  
  'k2': json.dumps('哈哈', ensure_ascii=False),
  
  'k3': a +
  1,
  
  '@id': "hello",
  
  '#text': "<a>dwad</a>",
  
  'k4': ['abc', 'def', None],
          }
      }, mime_type
  =
  'application/xml')
  
  return {
  
  'k1': entity['root']['#text'] + entity['root']['@id'],
  
  'k2': entity['root']['k1'],
  
  'k3': entity['root']['*k4']['^value'],
  
  'k4': entity['root']['k4'],
  
  'k5': entity['^mime_type']
      }

  
  

• 输出
  Dataway 脚本的输出结果为一个字典类型数据，如下所示。

{

"k1": "<a>dwad</a>hello",

"k2": "123",

"k3": ['abc', 'def', None],

"k4": "abc",

"k5": "application/xml"
}

?在 XML 格式数据中，root 节点为默认节点，其属性使用 @id=123 的方式指定，文本使用 #text 的方式指定。root 节点值为一个 MultiMap 类型，其中键为每一个子节点名称，值为相应子节点的值。

CSV 格式

CSV 格式的数据代表 MIME 类型为 application/csv 的 Entity 中数据序列化后得到的类型。

• 使用原始数据构造方法，则 Dataway 对输入的字符串或 bytes 类型最终解析成一个列表类型数据结构，其中每一项元素均为一个字典。

• 使用值构造方法，支持列表类型输入，并最终解析成一个列表类型数据结构，其中每一项元素均为一个字典。

以下将通过示例来说明如何使用 CSV 格式数据。

示例：构造 CSV 格式的 Entity

本示例将展示如何使用 Entity 的构造函数构造一个 CSV 格式的 Entity，并使用 Entity 选择器语法获取 Entity 的属性和数据。

-
输入
Dataway 输入参数 msg 的 payload 值为常量1，同时 msg.vars 中包含一个键为 "abc" , 值为 "123" 的键值对。

{

"payload": 1,

"vars": {

"abc": "123"
    }
}

-
Dataway 脚本
以下 Dataway 脚本使用值构造方法将字典类型转换成 Entity 对象，并使用选择器语法获取 Entity 对象的属性值。

def
dw_process(msg):
    entity = Entity.from_value([
        {'k1':'abcd','k2':123.0,'k3':True},
        {'k1':'defs','k2':'dwdw,2e','k3':10},
    ], mime_type
=
'application/csv')

return {

'var1': entity['^blob'],

'var2': entity['^mime_type'],

'var3': entity['^encoding'],

'var4': entity[0]['k2'] + entity[1]['k3'],

'var5': entity[1]['k2']
    }

-
输出
Dataway 脚本的输出结果为一个字典类型数据，如下所示。

{

"var1": b'k1,k2,k3\r\nabcd,123.0,True\r\ndefs,"dwdw,2e",10\r\n',

"var2": "application/csv",

"var3": "utf-8",

"var4": "133",

"var5": "dwdw,2e"
}

?对于 CSV 数据格式，接收的列表每一项元素均为字典类型。每一项元素中的键需保持相同，作为 CSV 文本的标题行；每一项元素中的值则代表该行的数据值，用逗号分隔。

HTTP Form-Data表单

HTTP Form-Data表单格式的数据代表 mime-type 为 multipart/form-data 的 Entity 中数据序列化后得到的类型。

浏览器中的 multipart/form-data

在浏览器发送 Content-Type 为 multipart/form-data 的请求时，实际传输的 byte 数组转换成字符串如下所示。

每一项参数由一个 boundary 开头，标识着这一项的开始，如 --34b21 。注意 -- 为固定开头，34b21 为浏览器随机的一个不超过70位的字符串。

下面两行分别是 Content-Disposition 和 Content-Type 的固定 headers。其中 Content-Disposition 包含 name 和filename 两项，Content-Type 即为输入内容的Content-Type。name 为参数名，filename 为文件名。如果filename 为"*.txt"或者为空，则 Content-Type 默认为 text/plain；如果 filename 为其他，则 Content-Type 会根据后缀名自动判断。同时，也支持其他的扩展 headers。

再往下是实际的内容，如果 Content-Type 为 text/plain ，则为普通字符串，如"Book"; 如果 Content-Type 为application/json ，则为一个 json 类型的字符串，如下方的file1 对应的 json 结构。

最后，会用--34b21--来标识这段请求的结束。

--34b21
Content-Disposition: form-data; name="text"
Content-Type: text/plain

Book
--34b21
Content-Disposition: form-data; name="file1"; filename="a.json"
Content-Type: application/json

{
    "title": "Java 8 in Action",
    "author": "Mario Fusco",
    "year": 2014
}
--34b21
Content-Disposition: form-data; name="file2"; filename="a.html"
Content-Type: text/html

<!DOCTYPE html>
<title>
Available for download!
</title>
--34b21--

Form-Data 的构造和使用

• 使用 原始数据构造方法，则 Dataway 对输入的字符串或 bytes 类型最终解析成一个 FormDataParts 数据结构。

• 使用值构造方法，支持 Entity、Formdata、列表/字典输入类型，并最终解析成一个 FormDataParts 数据结构。

?
- 如果为 Entity 类型，则会首先判断 MIME 类型是否为 multipart/form-data 。如果为是，直接返回这个 Entity ；否则将报错。
- 如果为 FormdataParts 类型（即上文提到的列表/字典结构），则直接赋值给 Entity。
- 如果为列表类型，则需要保证为以下数据结构：每一项的第一个元素为参数名。第二个元素如果为列表，则第二个元素的第一项为文件名，第二项为实际的内容，第三项为 Content-Type ，第四项为一个字典，代表 extra_headers；如果第二个元素类型为字符串， 则文件名为空，实际内容即为字符串内容，Content-Type 默认为 text/plain。

对 HTTP Form-Data 格式数据，除了通用的 Entity 选择器语法，还支持特殊的选择器语法。

应用示例

以下将通过两个示例来说明如何使用 HTTP FORM-DATA 表单格式数据。

<dx-tabs>
::: 示例1：构造 HTTP Form-Data 格式的 Entity
本示例将展示如何使用 Entity 的构造函数构造一个 HTTP Form-Data 数据格式的 Entity。

-
输入
Dataway 输入参数 msg 的变量（vars）中包含一个键为“abc”，值为“123”的键值对。

{

"vars": {

"abc": "123"
    }
}

-
Dataway 脚本
以下 Dataway 脚本使用 值构造方法 将字典类型转换成 Entity 对象，并返回。

def
dw_process(msg):
    a = math.floor(1.4)
    c = Entity.from_value({

'k1': msg.vars['abc'],

'k2': json.dumps('哈哈', ensure_ascii=False),

'k3': a +
1,
    }, mime_type
=
'application/json')

return Entity.from_value(
        [
            ('a', ('test.json', '{"a": a}', 'application/json', {'Test111': 1})),
            ('b', '333'),
            ('c', ('c.json', c, c['^mime_type']))
        ],

mime_type='multipart/form-data; boundary=123333333'
    )

-
输出
Dataway 脚本的输出结果为一个 Entity 类型对象，其中原始数据（blob）为符合 multipart/form-data 结构的二进制数据，如下所示。

{

"mime_type": "multipart/form-data; boundary=12345",

"encoding": "utf-8",

"blob": b'''--123333333
Content-Disposition: form-data; name="a"; filename="test.json"
Content-Type: application/json
Test111: 1

{"a": a}
--123333333
Content-Disposition: form-data; name="b"

333
--123333333
Content-Disposition: form-data; name="c"; filename="c.json"
Content-Type: application/json

{"k1":"123","k2":"\"哈哈\"","k3":2}
--123333333--
'''
}

本示例将示范如何在 FORM-DATA 格式数据中使用特定语法的选择器。

-
输入
Dataway 输入参数 msg 的 payload 为一个 Entity 类型，其 MIME 类型为 multipart/form-data，通过 值构造方法 创建。

def
dw_process(msg):

return Entity.from_value(
        [('a', ('test', '1233', 'application/json', {'test111':1})),
        ('b', (None, '2333', 'text/plain')),],

mime_type="multipart/form-data; boundary=ce560532019a77d83195f9e9873e16a1"
    )

-
Dataway 脚本
以下 Dataway 脚本将使用 FORM-DATA 选择器对 msg.payload 进行处理，并返回一个字典。

def
dw_process(msg):

return {

'k1': str(type(msg.payload)),

'k2': msg.payload['^mime_type'],

'k3': msg.payload['^encoding'],

'k4': msg.payload['^blob'],

'k5': msg.payload['boundary'],

'k6': msg.payload['parts']['a']['headers']['Content-Disposition']['name']

+
'-'
+ msg.payload['parts'][1]['headers']['Content-Type']
    }

-
输出
Dataway 脚本的输出结果为一个字典类型数据，结果如下。

{

'k1': 'Entity',

'k2': 'multipart/form-data;boundary=ce560532019a77d83195f9e9873e16a1',

'k3': 'utf-8',

'k4': b'''--ce560532019a77d83195f9e9873e16a1
Content-Disposition: form-data; name="a"; filename="test"
Content-Type: application/json
test111: 1

1233
--ce560532019a77d83195f9e9873e16a1
Content-Disposition: form-data; name="b"
Content-Type: text/plain

2333
--ce560532019a77d83195f9e9873e16a1--
''',

'k5': 'ce560532019a77d83195f9e9873e16a1',

'k6': 'a-text/plain'
}