引言
monday.com 作为一个强大的工作操作系统，广泛应用于项目管理、crm 等领域。通过其开放的 graphql api，我们可以实现与其他系统的深度集成，例如从外部表单自动创建潜在客户或交易。本教程将详细介绍如何使用 php 语言，结合 monday.com 的 graphql api，实现这一自动化流程。
准备工作
在开始之前，请确保您已具备以下条件：
- Monday.com API 密钥 (Token)：这是访问 Monday.com API 的凭证。您可以在 Monday.com 账户的“管理”->“开发者”->“个人访问令牌”中生成。
- Monday.com 看板 (Board) ID：您希望创建潜在客户或交易项的看板 ID。
- PHP 运行环境：确保您的服务器或本地环境已安装 PHP。
- 了解 GraphQL 基础：Monday.com API 基于 GraphQL，了解其查询和变异 (mutation) 概念将有助于理解。
Monday.com GraphQL API 概览
Monday.com API 允许您通过 GraphQL 语言与平台进行交互。创建新的项（item，例如潜在客户或交易）是通过执行一个 mutation 操作来完成的。核心的 mutation 是 create_item，它需要以下参数：
- board_id：要创建项的看板 ID。
- item_name：新项的名称。
- column_values：一个 JSON 字符串，包含所有列的值。这是最关键的部分，需要根据您的看板列类型和 ID 进行精确构造。
配置 API 访问 (config.php)
为了更好地管理 API 密钥和常用配置，我们首先创建一个 config.php 文件。
1918282734, // 示例看板1 ID
"boardName2" => 1987654321, // 示例看板2 ID
"testBoard" => 6376637288 // 您的测试看板 ID
);
// 如果您需要指定某个组（Group）ID，可以在这里定义
// "testGroup" => 6376637288
?>重要提示：请务必将 [YOUR API KEY] 替换为您的实际 Monday.com API 密钥。为了安全起见，API 密钥不应直接硬编码在生产环境中，而应通过环境变量或其他安全方式管理。
立即学习“PHP免费学习笔记（深入）”；
构建数据提交逻辑 (create_lead.php)
接下来，我们将创建主脚本，它将接收表单数据，构建 GraphQL 变异，并发送请求到 Monday.com API。
'status_1', 'date4' -> 'date_column', 'text__1' -> 'text_column' 等。
$vars = [
'itemName' => $companyName, // 新项的名称，通常是公司名或主要联系人
'columnVals' => json_encode([
// 状态列：需要一个包含 'label' 的数组
'status' => [
'label' => 'New Lead' // 例如：'New Lead', 'Contacted' 等
],
// 日期列：需要一个包含 'date' 的数组，格式为 YYYY-MM-DD
'date4' => [ // 假设您的日期列 ID 是 'date4'
'date' => $todaysDate
],
// 文本列：直接传递字符串
'text__1' => $firstName, // 假设您的名字列 ID 是 'text__1'
'text5__1' => $lastName, // 假设您的姓氏列 ID 是 'text5__1'
// 邮箱列：需要一个包含 'email' 和 'text' 的数组
'email__1' => [ // 假设您的邮箱列 ID 是 'email__1'
'email' => $contactEmail,
'text' => $contactEmail // 邮箱列的显示文本
],
// 电话列：需要一个包含 'phone' 和 'countryShortName' 的数组
'phone__1' => [ // 假设您的电话列 ID 是 'phone__1'
'phone' => $contactPhone,
'countryShortName' => 'US' // 国家简称，例如 'US', 'CN'
],
// 文本列
'text7__1' => $projectState, // 假设您的项目状态列 ID 是 'text7__1'
// 长文本列
'long_text4__1' => $projectMessage // 假设您的长文本列 ID 是 'long_text4__1'
// 'link_column' => ['url' => $contactWebSite, 'text' => $contactWebSite] // URL 列可能需要特殊处理，原问题中提到此项未成功。
])
];
// 4. 发送 API 请求
// 使用 file_get_contents 结合 stream_context_create 发送 POST 请求
$data = @file_get_contents($apiUrl, false, stream_context_create([
'http' => [
'method' => 'POST',
'header' => $headers, // 包含授权和内容类型
'content' => json_encode([
'query' => $query,
'variables' => $vars
]),
'ignore_errors' => true // 即使 HTTP 状态码表示错误也读取响应
]
]));
// 5. 处理 API 响应
$responseContent = json_decode($data, true);
echo json_encode($responseContent, JSON_PRETTY_PRINT); // 以美观的格式输出响应
} else {
// 如果不是 POST 请求，可以显示一个简单的表单或错误信息
echo "请通过 POST 请求提交数据。";
// 示例 HTML 表单（用于测试）
echo '
';
}
?>发送 API 请求
在上述代码中，我们使用了 file_get_contents 函数结合 stream_context_create 来发送 HTTP POST 请求。这种方法对于简单的 API 调用是有效的。
stream_context_create 允许我们定义 HTTP 请求的各种选项，包括：
- method：指定为 POST。
- header：包含 Content-Type: application/json 和 Authorization: Bearer YOUR_TOKEN。
- content：请求体，这里是 JSON 编码后的 GraphQL 查询和变量。
关于 cURL 的说明： 虽然原始问题提到了 cURL，但提供的解决方案使用了 file_get_contents。PHP 的 cURL 扩展是进行复杂 HTTP 请求的更强大和灵活的工具，特别是在需要处理文件上传、代理、SSL 证书验证等高级功能时。如果您需要使用 cURL，其基本结构如下：
$query, 'variables' => $vars])); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); // $headers 数组需要调整为 ['Content-Type: application/json', 'Authorization: Bearer ' . $token] $data = curl_exec($ch); $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); // 继续处理 $data ?>
两种方法都能实现 API 请求，您可以根据个人偏好和项目需求选择。
处理 API 响应
Monday.com API 会返回一个 JSON 格式的响应。在我们的示例中，responseContent 将包含新创建项的 id 和 name。
{
"data": {
"create_item": {
"id": "1234567890",
"name": "测试公司"
}
},
"account_id": 987654321
}您可以根据 responseContent 中的 data 字段来判断操作是否成功，并获取新创建项的信息。
注意事项
- 列 ID 匹配是关键：Monday.com 看板中的每一列都有一个唯一的 ID。您必须在 columnVals 中使用正确的列 ID 来更新相应的值。这些 ID 通常可以在列设置中或通过 Monday.com API 浏览器查询获取。例如，text__1、email__1、phone__1 等都是示例 ID，您需要替换为实际的 ID。
-
数据类型与格式：
- 状态列 (Status)：需要一个包含 label 键的数组，label 的值必须是 Monday.com 中实际存在的状态标签。
- 日期列 (Date)：需要一个包含 date 键的数组，日期格式必须是 YYYY-MM-DD。
- 邮箱列 (Email)：需要一个包含 email 和 text 键的数组。
- 电话列 (Phone)：需要一个包含 phone 和 countryShortName 键的数组。countryShortName 遵循 ISO 3166-1 alpha-2 标准，例如 'US'、'CN'。
- URL 列 (Link)：原始问题中提到 URL 列未能成功添加。Monday.com 的 URL 列通常需要一个包含 url 和 text 的对象。如果直接传递字符串无效，尝试使用 ['url' => 'https://example.com', 'text' => 'Example Website'] 这样的结构。如果仍然存在问题，建议查阅最新的 Monday.com API 文档或在 Monday.com 开发者社区寻求帮助。
- 错误处理：在生产环境中，您应该添加健壮的错误处理机制。例如，检查 file_get_contents 的返回值是否为 false，以及 API 响应中是否包含 errors 字段。
- API 密钥安全：切勿将 API 密钥暴露在客户端代码中，也不要将其直接提交到版本控制系统（如 Git）。始终将其存储在服务器端，并通过安全方式访问。
- GraphQL 查询优化：您可以根据需要调整 create_item 变异的返回字段，例如获取更多列的信息，而不仅仅是 id 和 name。
总结
通过本教程，您应该已经掌握了如何使用 PHP 和 Monday.com GraphQL API 自动化创建潜在客户或交易项的基本流程。这包括配置 API 密钥、构建 GraphQL 变异查询、正确映射不同类型的列数据以及发送和处理 API 请求。此集成能力为您的业务流程自动化提供了广阔的可能性，例如将网站表单提交、CRM 数据同步等直接集成到 Monday.com 中，从而提高效率并减少手动数据输入。
