请求数据操作的配置

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

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

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

自定义操作使用请求模板来定义向远程终端节点或 AWS Lambda 函数发出的 POST、PUT 和 PATCH 请求的正文。 远程端点由 requestURLTemplate 定义。 这些请求模板支持使用宏。 有关详细信息,请参阅数据操作的 Velocity 宏

注释:
  • GET 请求不使用请求模板。 请 求模板 字段显示默认值 “$ {input.rawRequest}”
  • 过度嵌套的 JSON 对象会影响数据操作服务的性能。 为了保持性能,JSON 对象的深度限制为 50 级。 有关更多信息,请参阅 Genesys Cloud 开发者中心中的限制。

警告: 在请求 模板成功模板或 requestURLTemplate中转义对输入或输出变量的任何使用如果您没有正确转义带有特殊字符的变量,则数据操作在执行时会失败。

请求模板

请求模板使用 Velocity 来定义 POST、PUT 和 PATCH 请求的正文。 保存请求模板后,API 响应会将其引用为 requestTemplateuri

  • 对于 AWS Lambda 数据操作集成,您在 requestTemplate 下指定的任何输入都 将在调用的 AWS Lambda 函数的 事件 参数中提供。
  • 对于谷歌云端函数, $esc.jsonString 宏会将请求中的字符串转换为 JSON。

标头

标头是键值对,在发送到远程终端节点的请求中作为 HTTP 标头添加。 标头值支持 Velocity 替换。

注意: 如果您依赖 API 来处理授权,请不要在请求标头中包含授权。 集成将自动填充标题。 否则,请在请求标头中包含您自己的授权。

AWS Lambda 数据操作集成将键值对添加为调用上下文对 象上的 Client Context 项目。 如果存在这些属性,则会在上下文对象上自动设置以下属性:

  • 在对话中 ID
  • 组织内 ID
  • 在家中组织 ID
  • inin-关系-ID
  • inin-User-ID
  • Inin-InIn-Integration-ID

请求类型

RequestType 在数据操作中 定义 HTTP 请求的类型。 可用的 HTTP 请求类型包括 POST、PUT 和 PATCH。

注意: 对于 AWS Lambda 和谷歌数据操作集成,请使用 POST。 此 HTTP 方法可确保发送任何请求正文。

请求URL模板

RequestURLTemplate 是您的 HTTP 请求点击的远程终端节点或 AWS 数据操作集成调用的 AWS Lambda 函数的 ARN。 requestURLTemplate 使用 Velocity 模板进行变量替换。 

注意: 如果请求 URL 模板引用 HTTP 终端节点,则 请求 URL 模板 必须引用 HTTP 安全 (HTTPS) 终端节点。

请求模板 URI

RequestTemplateuri 是您的 请求模板的参考 URI。 当您保存 RequestTemplate 时,集成会折叠它。 要在保存请 求模板 后查看请求模板的内容,请对 requestTemplateuri 发出 GET 操作

示例 请求模板

动作执行体

以下 REST 调用将触发操作 SampleAction123,并在示例操作中传递 输入模式 中定义的三个属性。 

curl -X POST https://api.mypurecloud.com/api/v2/integrations/actions/sampleAction123/execute \
  -H 'authorization: bearer *****' \
  -d '{
    "USER_ID": 123,
    "FIRST_NAME":"John",
    "LAST_NAME": "Smith"
}'

操作服务查找并替换示例操作中引用这三个属性的任何值,包括 requestURLTemplaterequestTemplate。 

请求模板

操作配置为具有以下 请求模板: 

"{"firstName": "$esc.jsonString(${input.FIRST_NAME})","lastName": "$esc.jsonString(${input.LAST_NAME})"},

有关转义的更多信息,请参阅 Velocity 宏中的 ESC.jsonString 部分了解数据操作

操作服务将替换示例操作中的 Velocity 模板占位符,结果如下:

{
  "firstName": "John",
  "lastName": "Smith"
}

RequestTemplate 成为发送到远程终端节点的 HTTP POST 的正文。 

Web 服务调用

修改后的示例操作将导致以下 Web 服务调用:

curl -X POST \
  https://sample.com/users/123 \
  -H 'content-type: application/json' \
  -H 'UserAgent: GenesysCloudIntegrations/1.0' \
  -H 'Company: My company' \
  -d '{
  "firstName": "John",
  "lastName": "Smith"}'

请求创建新操作

以下是配置为执行 POST 到 https://sample.com/users/${input.USER_ID} 的操作inputSchema 定义了用于构造请求的三个属性: USER_ID名字姓氏请求模板requestURLTemplate 中引用了这三个属性

{
  "category": "Sample",
  "contract": {
    "input": {
      "inputSchema": {
        "$schema": "http://json-schema.org/draft-04/schema#",
        "description": "Update user's first and/or last name",
        "properties": {
          "USER_ID": {
            "description": "User Id",
            "type": "number"
          },
          "FIRST_NAME": {
            "description": "Users first name",
            "type": "string"
          },
          "LAST_NAME": {
            "description": "User last name",
            "type": "string"
          }
        },
        "required": [
          "USER_ID",
          "FIRST_NAME",
          "LAST_NAME"
        ],
        "title": "Update name request",
        "type": "object"
      }
    },
    "output": {
      ...
    }
  },
  "config": {
    "request": {
      "headers": {
        "Content-Type": "application/json",
        "UserAgent": "GenesysCloudIntegrations/1.0",
        "Company": "My company"
      },
      "requestTemplate" : "{\"firstName\": \"${input.FIRST_NAME}\",\"lastName\": \"${input.LAST_NAME}\"}",
      "requestType": "POST",
      "requestUrlTemplate": "https://sample.com/users/${input.USER_ID}"
    },
    "response": {
      ...
    }
  },
  "name": "Sample Action",
  "secure": true
}

获取操作定义的结果

{
    "id": "<action ID>",
    "name": "Sample Action", 
    ...
    "config: {
        "request": {
            "requestUrlTemplate": "https://sample.com/users/${input.USER_ID}",
            "requestTemplateUri": "/api/v2/integrations/actions/<action ID>/templates/requesttemplate.vm",
            "requestType": "POST",
            "headers": {
                "Content-Type": "application/json",
        	    "UserAgent": "GenesysCloudIntegrations/1.0",
        	    "Company": "My company"
         },
         "response": {
             ...
         }
    },
    "category": "Sample",
    "version": 1,
    "secure": true,
    "selfUri": "/api/v2/integrations/actions/<action ID>"
}

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

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

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