通过数据映射任务，您可以在集成中执行变量分配、获取和设置 json 对象的属性以及将嵌套转换函数应用于值。变量可以是集成变量或任务变量。
例如，您可以将集成变量 X 的值分配给任务变量 Y，或将任务变量 Y 的数据值分配给集成变量 X。如需详细了解 Apigee Integration 集成中的变量，请参阅在 Apigee Integration 集成中使用变量。
配置数据映射任务
如需配置数据映射任务，请执行以下步骤：
- 在 Apigee 界面中，选择您的 Apigee 组织。
- 点击开发 > 集成。
- 选择现有集成，或通过点击创建集成来创建新集成。
要创建新的集成，请执行以下操作：
- 在创建 Integrations对话框中输入名称和说明。
- 从支持的区域列表中选择集成的区域。
- 点击创建。
这将在集成设计器中打开集成。
- 在集成设计器导航栏中，点击 + 添加任务/触发器 > 任务以查看可用任务列表。
- 点击数据映射元素，并将其放置到集成编辑器中。
- 点击设计器上的数据映射元素以查看数据映射任务配置窗格。
-
点击打开数据映射编辑器以查看任务的默认值并添加新映射。如需了解添加映射的详细步骤，请参阅添加映射。
如需详细了解数据映射编辑器布局，请参阅数据映射概览。
添加映射
如需添加映射，请执行以下步骤：
- 在数据映射任务配置窗格中，点击打开数据映射编辑器。
- 配置映射输入：
- 将变量或其子字段从变量列表拖动到“输入”行中。如需查看变量的可用子字段，请在变量列表中点击相应变量旁边的 （展开）。
- 或者，在“输入”行中，点击变量或值并执行以下操作：
- 选择变量以搜索和使用现有变量。如需创建新变量，请点击 + 添加新变量，然后输入新变量的名称和数据类型。
- 选择值，输入
string、integer、double或Boolean类型的字面量值。 - 选择函数以搜索并使用基本函数。
基本函数用于在集成执行期间检索或生成值。例如，生成随机 UUID 或检索当前集成区域。如需了解支持的基本函数，请参阅支持的基本函数。
- 点击保存。
- 点击“输入”行中任意输入变量、值或基本函数的 +（添加函数），从可用映射函数列表中添加映射函数。映射函数可以有一个或多个参数。每个参数可以进一步具有值、变量或基本函数，后跟映射函数。
- 如需添加嵌套函数，请点击函数参数旁边的 +（添加函数）。同样地，如需移除或删除最近添加的函数，请点击 -（删除上一个函数）。
- 如需在映射表达式之间添加、移除或更改函数，请点击一个函数，然后相应地选择添加函数、移除函数或更改函数。
- 如需移除映射表达式中的变量，请点击“变量”行旁边的 （移除）。
- 如需移除整个“输入”行，请点击该行中的 （清除）。
如需详细了解映射函数，请参阅映射函数。
如需了解受支持的映射函数，请参阅受支持的数据类型和映射函数。
- 配置映射输出：
- 将变量从变量列表拖动到“输出”行中。如果该变量不可用，请点击创建新变量以配置新变量的名称和数据类型。或者，您可以点击输出变量，然后选择是使用该变量作为集成的输出还是用作其他集成的输入。
- 如需移除输出变量，请点击 （清除）。
- （可选）如需删除映射行，请点击（删除此映射）。
- 映射完成后，关闭数据映射编辑器。所有更改都将自动保存。
已完成的数据映射可通过数据映射任务配置窗格进行查看，如下图所示：
受支持的数据类型和映射函数
对于数据映射任务中的变量，Apigee Integration 支持以下数据类型：
- 字符串和字符串数组
- 整数和整数数组
- 双精度型和双精度型数组
- 布尔值和布尔值数组
- JSON
支持的基本函数
下表列出了可用的数据映射基本函数：| 数据类型 | 支持的基本函数 |
|---|---|
| 整数 | NOW_IN_MILLIS |
| 整数数组 | INT_LIST |
| 字符串 | GENERATE_UUID、GET_EXECUTION_ID、GET_INTEGRATION_NAME、GET_INTEGRATION_REGION、GET_PROJECT_ID |
最佳做法
使用数据映射任务可以有效地将键变量传递给集成中的各种任务。构建集成时，请牢记以下几点提示：
- 系统会按顺序从上到下依次运行映射。也就是说，如果输入变量
A映射到第一行中的输出变量B，则变量B可在后续行中用于映射。 - 在每一行中，“输入”行的数据类型必须与“输出”行的数据类型相匹配。如需转换类型，请使用转换函数，如
TO_STRING和TO_INT。 - 转换链长度不受限制。但是，调试大型链式转换可能很困难。我们建议确保输入转换可读，并将复杂转换拆分为多个映射。
- 如果映射需要回退值，请为映射设置回退值。如果您未提供回退值，则当输入值或转换返回
null时，映射将返回错误。 - 删除变量时，请确保删除包含此变量的所有映射。
如需了解适用于数据映射任务的用量限额，请参阅用量限额。
注意事项
对于 JSON 变量，在以下情况下，Apigee Integration 集成会基于 JSON 架构将变量的子属性解释为 JSON 类型：
- 如果子属性类型指定 null。例如：
{ "properties": { "PersonID": { "type": [ "double", "null" ], "readOnly": false } } }。 - 如果子属性的类型指定多种数据类型。例如：
{ "properties": { "PersonID": { "type": [ "integer", "string", "number" ], "readOnly": false } } }。
在这些情况下，您必须使用数据映射函数将子变量明确转换为所需的类型。
以下示例演示了各种类型的属性声明，并说明了如何使用数据映射函数获取所需的类型：
示例 1
{
"type": "object",
"properties": {
"dbIntegers": {
"type": "array",
"items": {
"type": [
"integer",
"null"
]
}
},
"dbBooleans": {
"type": [
"array"
],
"items": {
"type": "boolean"
}
}
}
}
Apigee Integration 将 dbIntegers 解释为 JSON 类型，并将 dbBooleans 解释为 BOOLEAN_ARRAY 类型。
若要转换 dbIntegers，请使用：
dbIntegers.TO_INT_ARRAY()
示例 2
{
"type": "object",
"properties": {
"dbId": {
"type": [
"number",
"null"
],
"readOnly": false
},
"dbStatus": {
"type": [
"boolean",
"null"
],
"readOnly": false
}
}
}
Apigee Integration 可将 dbId 和 dbStatus 识别为 JSON 类型，但 dbId 是可以接受单个双精度值或 null 值的参数，而 dbStatus 是可以接受单个布尔值或 null 值的参数。
若要转换 dbId 和 dbStatus，请使用：
dbId.TO_DOUBLE()
dbStatus.TO_BOOLEAN()
示例 3
{
"type": "object",
"properties": {
"dbString": {
"type": [
"string"
],
"readOnly": false
}
}
}
Apigee Integration 将 dbString 识别为字符串类型。
错误处理策略
任务的错误处理策略指定当任务因暂时性错误而失败时要执行的操作。如需了解如何使用错误处理策略，以及了解不同类型的错误处理策略，请参阅错误处理策略。