注意： 本文适用于 AWS Lambda、Genesys Cloud、Google、Microsoft Dynamics 365、Salesforce、Web 服务和 Zendesk 数据操作集成。

您可以为数据操作集成创建自定义操作。 自定义操作在其配置中包括请求和响应。 有关更多信息，请参阅 创建自定义操作。

本文介绍了响应的各个部分。 有关请求的信息，请参阅请 求配置。

自定义操作使用翻译图和成功模板将来自远程 Web 服务或 AWS Lambda 函数的原始响应转换为符合定义的成功模式的已解决响应。 这些成功模板支持使用宏。 有关详细信息，请参阅数据操作的 Velocity 宏。

未回复

当针对数据操作集成执行操作时，整个响应称为原始响应。 但是，原始响应不一定与操作的成功模式中定义的格式匹配。 如果原始响应不匹配，则可以使用转换图和成功模板重新格式化数据。

注意： Google Cloud Functions 会返回一个字符串化的 JSON 响应，在处理翻译映射之前，操作会转换为 JSON。

翻译地图

转换映射包含键值对，这些键值对将属性名称映射到 JsonPath 表达式求值时返回的值（或对象）。

翻译映射默认值

翻译映射默认值包含将翻译映射键设置为默认值的键值对。 如果在转换映射中配置的 JSONPath 表达式无法解析值，则使用默认值。 空值不会回退到默认值。

成功模板

成功模板使用 Velocity 模板语言中的变量表示法。 成功模板使用转换映射中的属性名称插入 JSONPath 表达式返回的数据。 通常，成功模板中的所有数据在输出中都被视为文字。 $ 中的项目{} 是对翻译映射中的值的引用。 有关更多信息，请参阅 Apache Velocity 项目 文档。

已解决回复

成功模板创建必须符合成功模式的已解决响应。 否则，会导致错误。

成功模式

成功模式定义操作响应所需的格式。 

使用案例

在以下情况下，您通常希望使用翻译映射图和成功模板来转换原始响应：

  • 你的原始响应包含多个对象。 必须将多个对象作为另一个对象的成员返回，才能使解析的输出与成功模式匹配。
  • 原始响应包含要转换为离散值的值或转换类型，例如数组。
  • 您只想返回特定的数据子集。
  • 你想保证返回的属性的顺序。

如果来自第三方的响应与成功模式匹配，则您希望在不进行任何操作的情况下返回原始响应。 在这种情况下，请使用默认请求模板。 如果未提供其他值，则默认请求模板将使用内置的 RawResult 上下文值。 然后，成功模板将传递整个结果，而不使用转换映射来提取值。

${rawResult}

示例 Salesforce 通过电话号码获取联系人操作

新建响应

以下是 Salesforce 通过电话号码获取联系人操作执行时 Salesforce 的原始响应示例。

{
  "searchRecords": [
    {
      "attributes": {
        "type": "Contact",
        "url": "/services/data/v37.0/sobjects/Contact/003G000001LrjlTIAR"
      },
      "Email": null,
      "FirstName": "Jack",
      "HomePhone": null,
      "Phone": "(317) 555-0123",
      "Id": "003G000001LrjlTIAR",
      "LastName": "Teller",
      "MobilePhone": null,
      "OtherPhone": null,
      "MailingStreet": null,
      "MailingCity": null,
      "MailingState": null,
      "MailingCountry": null,
      "MailingPostalCode": null
    }
  ]
}

原始响应包含一个根节点（SearchRecords）。 SearchRecords 对象表示从 Salesforce 返回的联系人信息。

翻译地图

翻译映射从原始响应中提取数据片段。 在这种情况下，我们想拉取整个节点 SearchRecords。 

注释： 
  • 翻译映射中的属性名称必须以字母（a-z、A-Z）开头，并且只能包含字母、数字（0-9）、连字符（-）或下划线（_）。 
  • 如果值的名称包含空格，请在名称周围添加括号和单引号，例如 “contact”： “$。['搜索记录']”。

"translationMap": {
  "contact": "$.searchRecords"
}

JsonPath 表达式 $.searchRecords 从原始响应中 提取 SearchRecords 对象，并为其分配别名 “联系人”。 成功模板使用别名。

成功模板

成功模板引用在翻译映射中创 建的别名 “contact”。 别名指向原始响应中的一个对象，该对象包含与成功模式匹配所需的所有值。

${contact}

已解决回复

成功模板为操作创建已解决的响应。 已解决的响应是操作返回的响应。 

[
    {
      "attributes": {
        "type": "Contact",
        "url": "/services/data/v37.0/sobjects/Contact/003G000001LrjlTIAR"
      },
      "Email": null,
      "FirstName": "Jack",
      "HomePhone": null,
      "Phone": "(317) 555-0123",
      "Id": "003G000001LrjlTIAR",
      "LastName": "Teller",
      "MobilePhone": null,
      "OtherPhone": null,
      "MailingStreet": null,
      "MailingCity": null,
      "MailingState": null,
      "MailingCountry": null,
      "MailingPostalCode": null
    }
]

与支付提供商一起使用的示例操作

新建响应

以下是一个示例原始响应，其中包含我们向信用卡收费时的操作。

{
  "id": "ch_1AS7Iv2eZvKYlo2CmgEX0bHw",
  "object": "charge",
  "amount": 999,
  "amount_refunded": 0,
  "application": null,
  "application_fee": null,
  "balance_transaction": "txn_1AS7Iv2eZvKYlo2CjrARHR6C",
  "captured": true,
  "created": 1496854005,
  "currency": "usd",
  "customer": "cus_AFEwvtMn3H17af",
  "description": null,
  "destination": null,
  "dispute": null,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {
  },
  "invoice": "in_1AS6Mf2eZvKYlo2C9QEibbxz",
  "livemode": false,
  "metadata": {
  },
  "on_behalf_of": null,
  "order": null,
  "outcome": {
    "network_status": "approved_by_network",
    "reason": null,
    "risk_level": "normal",
    "seller_message": "Payment complete.",
    "type": "authorized"
  },
  "paid": true,
  "receipt_email": null,
  "receipt_number": null,
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [
 
    ],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/charges/ch_1AS7Iv2eZvKYlo2CmgEX0bHw/refunds"
  },
  "review": null,
  "shipping": null,
  "source": {
    "id": "card_19ukSY2eZvKYlo2CHlYUs1DM",
    "object": "card",
    "address_city": null,
    "address_country": null,
    "address_line1": null,
    "address_line1_check": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": "94301",
    "address_zip_check": "pass",
    "brand": "Visa",
    "country": "US",
    "customer": "cus_AFEwvtMn3H17af",
    "cvc_check": null,
    "dynamic_last4": null,
    "exp_month": 12,
    "exp_year": 2018,
    "fingerprint": "Xt5EWLLDS7FJjR1c",
    "funding": "credit",
    "last4": "4242",
    "metadata": {
    },
    "name": null,
    "tokenization_method": null
  },
  "source_transfer": null,
  "statement_descriptor": null,
  "status": "succeeded",
  "transfer_group": null
}

翻译地图

翻译映射从原始响应中提取数据片段。 在这种情况下，我们想从原始响应中提取四个字段。

"translationMap": {
  "idValue": "$.id",
  "paidValue": "$.paid",
  "outcomeValue": "$.outcome",
  "sourceValue": "$.source"
}

JsonPath 表达式 $.id、 $.paid、 $.结果和 $.source 从原始响应中 提取值并将其分配给别名 IDValue、 paidValue、 结果值和 来源值。 翻译映射默认设置 SourceValue 的默认值。 成功模板使用所有这些别名。

翻译映射默认值

翻译映射默认设置翻译映射中的关键帧为默认值。 在这种情况下，响应不包含 source 属性，因此我们将 sourceValue 设置 为默认值 “UNKNOWN”。

"translationMapDefaults": {
  "sourceValue": "\"UNKNOWN\""
}

来自支付提供商的回复可能包含也可能不会在翻译映射图中包含 source 属性。 为确保在响应包含 source 属性的情况下使用 source 属性，如果响应不包含它，则不会抛出错误，请在翻译映射 中将 sourceValue 默认设置为 “UNKNOWN”。

如果响应不包括翻译映射中的任何其他字段，则操作将失败。

成功模板

成功模板会构建一个有效的 JSON 响应，该响应引用在翻译映射中创建的别名 ID Value、paidValue 和 OutcomValue 。 别名指向原始响应中匹配成功模式所需的值。

{
   "id": ${idValue},
   "outcome": ${outcomeValue},
   "paid": ${paidValue},
   "source": ${sourceValue}
}
注意： $ 以外的文本{} 被视为文字。

已解决回复

成功模板为操作创建已解决的响应。 已解决的响应是操作返回的响应。

{
   "id": "ch_1AS7Iv2eZvKYlo2CmgEX0bHw",
   "outcome": {
      "network_status": "approved_by_network",
      "reason": null,
      "risk_level": "normal",
      "seller_message": "Payment complete.",
      "type": "authorized"
   },
   "paid": true,
   "source": "UNKNOWN"
}

有关自定义操作中的配置的信息，请参阅 添加配置 和 修改配置。

有关更多信息，请参阅 关于集成的自定义操作。

有关集成的更多信息，请参阅 关于数据操作集成。