应用的自定义参数透传

工作流与智能体编排应用的参数透传

在工作流应用和智能体编排应用中，您可以自定义开始节点的参数。例如，在一个查询城市天气信息的工作流应用中，您可以定义String类型的参数city和date。系统还设置了一个默认参数query，用于接收您输入的Prompt。

您可以使用prompt传递query参数，使用biz_params传递自定义参数，具体示例如下：

curl --location 'https://dashscope.aliyuncs.com/api/v1/apps/1e06bb0495bb48c3a6a37444e8f1416b/completion' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
	"input": {
		"prompt": "你好",
		"biz_params": {
			"city": "Hangzhou"
                        "date": "2024-08-23"
		}
	},
	"parameters": {},
	"debug": {}
}' --verbose

自定义参数透传的使用

1. 创建支持自定义参数透传的插件

在应用中心 - 应用组件 - 插件管理页面中，创建自定义插件。

2. 指定需要透传的参数

以下是一个指定自定义透传参数的插件接口 YAML 配置文件的例子：

openapi: 3.0.1
info:
    title: 寝室公约查询工具
    description: 寝室公约查询工具，可以根据序号查询特定条目。
    version: "v2"
servers:
    - url: {domain}
paths:
    /article/{username}:
        post:
            operationId: get_article
            summary: 查询寝室公约第几条，用整数数字
            parameters:
            -   in: path
                name: username
                schema:
                    type: string
                required: true
                description: 用户名
                x-source: user	# 透传参数标识
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required: [article_index]
                            properties:
                                article_index:
                                    type: integer
                                    description: 寝室公约第几条，用整数数字
                                    x-source: user  # 透传参数标识
            responses:
                "200":
                    description: 查询成功
                    content:
                        application/json:
                            schema:
                                type: object
                                required: [article]
                                properties:
                                    article:
                                        type: string
                                        description: 寝室公约条款

该配置文件遵循 OpenAPI 3.0 协议，您可以参照文档 创建自定义插件 和 OpenAPI 官方文档 中的指引，了解各个对象和字段的含义，进一步自定义您的插件接口。

在上述配置文件的例子中，插件接口需要两个由应用用户提供的参数，分别为

1. 路径参数 username

2. 请求体参数 article_index

为此，需要在这些参数的属性中添加 schema extension x-source，并赋值为user，即可将这些参数标识为透传参数。

3. 在应用发布窗中测试透传参数

在 应用中心 - 我的应用 中，新建应用并引入您配置的自定义插件。

在插件变量窗口，您可以传入插件自定义的透传参数

4. 在应用 API 接口中传入透传参数

curl --location 'https://dashscope.aliyuncs.com/api/v1/apps/{appId}/completion' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
	"input": {
		"prompt": "你好",
		"biz_params": {
			"user_defined_params": {
				"1999849738269549_plugin_param_test": {
					"username": "my_name",
					"article_index": 10
				}
			}
		}
	},
	"parameters": {},
	"debug": {}
}' --verbose

• 为了使用插件参数透传功能，您需要在调用应用的 API 的 input 对象中，使用 biz_params 传递相关数据

• user_defined_params是一个固定参数，表示这个对象中传入的是自定义插件参数信息

• 接下来，以插件 ID 为键（例如 1999849738269549_plugin_param_test），每一个值的对象即相关插件的待透传参数信息

• 在对象最内侧，将包含多个键值对，每个键值对表示用户自定义的待透传参数名及其指定值。请注意，传入没有x-source属性修饰的参数将不会产生任何效果。

插件用户级鉴权的使用

1. 开启插件的用户级鉴权

如果您的插件接口需要用户自主输入鉴权 Token ，请根据下图所示开启插件用户级鉴权的功能。

2.测试窗透传用户级鉴权token

在 应用中心 - 我的应用 中，新建应用并引入您配置的自定义插件。

如果您配置了插件用户级鉴权的功能，您能够在插件鉴权窗口传入鉴权 Token

3.应用调用api中透传用户级鉴权Token

curl --location 'https://dashscope.aliyuncs.com/api/v1/apps/1e06bb0495bb48c3a6a37444e8f1416b/completion' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
	"input": {
		"prompt": "你好",
		"biz_params": {
			"user_defined_tokens": {
				"1999849738269549_plugin_param_test": {
					"user_token": "my_token1"
				}
			}
		}
	},
	"parameters": {},
	"debug": {}
}' --verbose

• 为了使用插件参数透传功能，您需要在调用应用的 API 的 input 对象中，使用 biz_params 传递相关数据

• user_defined_tokens是一个固定参数，表示这个对象中传入的是用户级鉴权信息

• 接下来，以插件 ID 为键（例如 1999849738269549_plugin_param_test），每一个值的对象即相关插件的鉴权信息

• user_token是一个固定参数，以该参数为键，其值为该插件需要的用户鉴权 Token