Google Forms

通过受管 OAuth 认证访问 Google Forms API。创建表单、添加问题，并获取响应数据。

快速开始

# 获取表单
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/google-forms/v1/forms/{formId}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

基础 URL

https://api.maton.ai/google-forms/{native-api-path}

Maton 将请求代理至 forms.googleapis.com，并自动注入您的 OAuth Token。

认证

所有请求均需在 Authorization 请求头中提供 Maton API 密钥：

Authorization: Bearer $MATON_API_KEY

环境变量：请将您的 API 密钥设置为 MATON_API_KEY：

export MATON_API_KEY="YOUR_API_KEY"

获取您的 API 密钥

1. 在 maton.ai 登录或注册账户
2. 访问 maton.ai/settings
3. 复制您的 API 密钥

连接管理

在 https://api.maton.ai 管理您的 Google OAuth 连接。

列出连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections?app=google-forms&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

创建连接

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'google-forms'}).encode()
req = urllib.request.Request('https://api.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

获取连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

响应示例：

{
  "connection": {
    "connection_id": "{connection_id}",
    "status": "ACTIVE",
    "creation_time": "2025-12-08T07:20:53.488460Z",
    "last_updated_time": "2026-01-31T20:03:32.593153Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "google-forms",
    "metadata": {}
  }
}

在浏览器中打开返回的 url 以完成 OAuth 授权流程。

删除连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

指定连接

若您拥有多个 Google Forms 连接，请使用 Maton-Connection 请求头指定目标连接：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/google-forms/v1/forms/{formId}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '{connection_id}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

当存在多个连接时，请始终包含该请求头，以确保请求路由至预期的 Google 账户。

安全与权限

• 访问范围限定于已连接 Google Forms 账户内的表单、问题、响应及表单元数据。
• 所有写操作均需用户显式授权。 在执行任何创建（create）、更新（update）或删除（delete）调用前，请向用户确认目标资源及其预期影响。

API 参考

获取表单

GET /google-forms/v1/forms/{formId}

创建表单

POST /google-forms/v1/forms
Content-Type: application/json

{
  "info": {
    "title": "Customer Feedback Survey"
  }
}

批量更新表单

POST /google-forms/v1/forms/{formId}:batchUpdate
Content-Type: application/json

{
  "requests": [
    {
      "createItem": {
        "item": {
          "title": "What is your name?",
          "questionItem": {
            "question": {
              "required": true,
              "textQuestion": {"paragraph": false}
            }
          }
        },
        "location": {"index": 0}
      }
    }
  ]
}

列出响应

GET /google-forms/v1/forms/{formId}/responses

获取单条响应

GET /google-forms/v1/forms/{formId}/responses/{responseId}

常用 batchUpdate 请求示例

创建文本题

{
  "createItem": {
    "item": {
      "title": "Question text",
      "questionItem": {
        "question": {
          "required": true,
          "textQuestion": {"paragraph": false}
        }
      }
    },
    "location": {"index": 0}
  }
}

创建多项选择题

{
  "createItem": {
    "item": {
      "title": "Select an option",
      "questionItem": {
        "question": {
          "choiceQuestion": {
            "type": "RADIO",
            "options": [
              {"value": "Option A"},
              {"value": "Option B"}
            ]
          }
        }
      }
    },
    "location": {"index": 0}
  }
}

创建量表题

{
  "createItem": {
    "item": {
      "title": "Rate your experience",
      "questionItem": {
        "question": {
          "scaleQuestion": {
            "low": 1,
            "high": 5,
            "lowLabel": "Poor",
            "highLabel": "Excellent"
          }
        }
      }
    },
    "location": {"index": 0}
  }
}

问题类型

• textQuestion — 短文本或段落文本
• choiceQuestion — 单选（RADIO）、多选（CHECKBOX）或下拉（DROPDOWN）
• scaleQuestion — 线性量表
• dateQuestion — 日期选择器
• timeQuestion — 时间选择器

代码示例

JavaScript

const response = await fetch(
  'https://api.maton.ai/google-forms/v1/forms/FORM_ID/responses',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);

Python

import os
import requests

response = requests.get(
    f'https://api.maton.ai/google-forms/v1/forms/FORM_ID/responses',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
)

注意事项

• 表单 ID 可在表单 URL 中找到
• 使用 updateMask 指定需更新的字段
• 位置索引（location index）为 0 起始
• 重要：使用 curl 命令时，若 URL 包含方括号，请使用 curl -g 参数禁用 glob 解析
• 重要：将 curl 输出管道传递给 jq 或其他命令时，在部分 shell 环境中环境变量（如 $MATON_API_KEY）可能无法正确展开，导致“Invalid API key”错误

错误处理

故障排查：API 密钥问题

1. 检查 MATON_API_KEY 环境变量是否已设置：

echo $MATON_API_KEY

2. 通过列出连接验证 API 密钥有效性：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

故障排查：应用名称无效

1. 确保您的 URL 路径以 google-forms 开头。例如：

• 正确：https://api.maton.ai/google-forms/v1/forms/{formId}
• 错误：https://api.maton.ai/forms/v1/forms/{formId}

相关资源

• Forms API 概览
• 获取表单
• 创建表单
• 批量更新
• 列出响应
• Maton 社区
• Maton 支持