如何在FreePBX中使用fwconsole发起GraphQL API请求？

问题再现 #

FreePBX提供GraphQL API可执行相关操作，但使用fwconsole api命令在命令行发起请求时遇到报错，请求被错误转发到fwconsole ma子命令，示例命令及错误如下：

尝试命令1：

$ fwconsole api gql voicemail 'mutation { moduleOperations(input: { module: "voicemail", action: "enableVoiceMail", extensionId: "1081", password: "1234" }) { status message }}'
sh: -c: line 0: syntax error near unexpected token `('
sh: -c: line 0: `/usr/sbin/fwconsole ma mutation { moduleoperations(input: { module: "voicemail", action: "enablevoicemail", extensionid: "1081", password: "1234" }) { status message }} voicemail --'

尝试命令2：

$ fwconsole api gql voicemail 'mutation { enableVoiceMail(input: {extensionId: "1081", password: "1234" }) { status message }}'
sh: -c: line 0: syntax error near unexpected token `('
sh: -c: line 0: `/usr/sbin/fwconsole ma mutation { enablevoicemail(input: {extensionid: "1081", password: "1234" }) { status message }} voicemail --'

问题分析 #

1. Shell特殊字符解析问题：GraphQL语句中的{、}、(、)属于shell特殊字符，未正确转义时会被shell错误解析，导致命令参数混乱。
2. fwconsole api参数路由错误：从错误输出看，命令参数被错误传递给fwconsole ma（模块管理）子命令，说明fwconsole api gql的参数解析逻辑可能存在问题，或者参数格式不符合预期。

解决思路与方案 #

1. 正确转义GraphQL语句中的特殊字符 #

通过转义特殊字符或使用合适的引号包裹，避免shell解析错误：

• 方案A：用双引号包裹整个GraphQL语句，内部双引号转义

fwconsole api gql voicemail "mutation { moduleOperations(input: { module: \"voicemail\", action: \"enableVoiceMail\", extensionId: \"1081\", password: \"1234\" }) { status message }}"

• 方案B：用单引号包裹，内部单引号用'\''拼接（bash单引号无法嵌套，需用此方式）

fwconsole api gql voicemail 'mutation { moduleOperations(input: { module: '\''voicemail'\'', action: '\''enableVoiceMail'\'', extensionId: '\''1081'\'', password: '\''1234'\'' }) { status message }}'

2. 使用--分隔命令与参数 #

添加--可告诉fwconsole后面的内容是参数，避免被错误路由到其他子命令：

fwconsole api gql voicemail -- 'mutation { moduleOperations(input: { module: "voicemail", action: "enableVoiceMail", extensionId: "1081", password: "1234" }) { status message }}'

3. 检查fwconsole api的官方用法 #

执行fwconsole api --help和fwconsole api gql --help查看参数说明，确认gql子命令的正确调用格式，比如是否需要指定其他参数，或者请求体的传递方式是否有特殊要求。

4. 替代方案：直接用curl调用GraphQL API #

如果fwconsole api确实存在功能限制，可直接通过curl向FreePBX的GraphQL端点发送请求：

# 步骤1：获取CSRF令牌（需先登录FreePBX后台，或使用API密钥认证）
CSRF_TOKEN=$(curl -s -c cookies.txt http://你的PBX地址/admin/config.php | grep csrf_token | awk -F '"' '{print $4}')

# 步骤2：发送GraphQL请求
curl -s -b cookies.txt -X POST http://你的PBX地址/admin/api/api/gql \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  -d '{
    "query": "mutation { moduleOperations(input: { module: \"voicemail\", action: \"enableVoiceMail\", extensionId: \"1081\", password: \"1234\" }) { status message }}"
  }'

若使用API密钥认证，可替换CSRF头为Authorization: Bearer <你的API密钥>。

5. 升级FreePBX版本 #

部分旧版本的FreePBX可能存在fwconsole api gql的功能bug，升级到最新稳定版后再测试命令是否正常工作。

内容的提问来源于stack exchange，提问作者Eli Courtwright