Python向Azure存储队列添加项时遇类型错误问题排查

问题重现 #

运行Python Azure Function向存储队列发送消息时，触发如下错误：

System.Private.CoreLib: 执行函数Functions.applyNewSurvey123时发生异常。System.Private.CoreLib: 结果：失败
异常：TypeError: unable to encode outgoing TypedData: unsupported type "<class 'azure_functions_worker.bindings.generic.GenericBinding'>" for Python type "list"

即使将msg.set()的参数改为纯文本，仍会报相同错误，但msg.set()后的日志可正常输出。

相关代码：

import logging
import azure.functions as func

def main(req: func.HttpRequest, 
         msg: func.Out[str]) -> func.HttpResponse:
    jsonString = req.get_json()

    try:
        msg.set(jsonString)
        return func.HttpResponse("HTTP triggered successfully.", status_code=200)
    except Exception as e:
        logging.error(f"Error: {e}")
        return func.HttpResponse("NOPE", status_code=500)

解决方案 #

1. 校验function.json的队列绑定配置 #

确保输出绑定的类型、参数名完全匹配代码声明，示例正确配置如下：

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": ["post"]
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "msg",
      "queueName": "your-target-queue",
      "connection": "AzureWebJobsStorage"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    }
  ]
}

• 重点确认type为queue，name与代码中的msg参数一致，connection指向正确的存储账户连接字符串配置。

2. 修正代码中的类型匹配问题 #

方式一：使用func.QueueMessage类型声明

针对Azure Functions v4+版本，推荐直接使用队列消息类型绑定：

import logging
import azure.functions as func
import json

def main(req: func.HttpRequest, 
         msg: func.Out[func.QueueMessage]) -> func.HttpResponse:
    json_data = req.get_json()

    try:
        # 将JSON对象转为字符串后封装为QueueMessage
        msg.set(func.QueueMessage(body=json.dumps(json_data)))
        return func.HttpResponse("HTTP triggered successfully.", status_code=200)
    except Exception as e:
        logging.error(f"Error: {e}")
        return func.HttpResponse("NOPE", status_code=500)

方式二：确保传入字符串类型

如果坚持使用func.Out[str]声明，必须保证传入set()的参数是字符串类型：

import logging
import azure.functions as func
import json

def main(req: func.HttpRequest, 
         msg: func.Out[str]) -> func.HttpResponse:
    json_data = req.get_json()

    try:
        # 显式将JSON对象转为字符串
        msg.set(json.dumps(json_data))
        return func.HttpResponse("HTTP triggered successfully.", status_code=200)
    except Exception as e:
        logging.error(f"Error: {e}")
        return func.HttpResponse("NOPE", status_code=500)

3. 升级运行环境版本 #

确保使用Azure Functions Runtime v4及最新版Python Worker，旧版本存在类型绑定的兼容性问题，可能导致GenericBinding类型错误。

错误原因 #

1. 绑定配置不匹配：如果function.json中输出绑定的type未设为queue，Worker会将其识别为GenericBinding，无法处理代码中声明的str类型，导致编码失败。
2. 参数类型不兼容：直接将req.get_json()返回的list/dict类型传入msg.set()，即使声明了func.Out[str]，也会触发类型不匹配错误，必须转为字符串。

内容的提问来源于stack exchange，提问作者Roger Asbury