引言
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 文件。
<?php
// config.php
// 您的 Monday.com API 密钥
// 请替换为您的实际 API 密钥
$token = '[YOUR API KEY]';
// Monday.com API 端点 URL
$apiUrl = 'https://api.monday.com/v2';
// HTTP 请求头，指定内容类型为 JSON 并包含授权令牌
$headers = ['Content-Type: application/json', 'Authorization: ' . $token];
// 定义您的看板 ID，可以根据需要添加多个
$boards = array(
"boardName1" => 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。
<?php
// create_lead.php
include('config.php'); // 引入配置信息
if ($_SERVER["REQUEST_METHOD"] == "POST") {
// 1. 从表单获取输入值
$companyName = $_POST['companyName'] ?? 'Unnamed Company'; // 公司名称
$firstName = $_POST['firstName'] ?? ''; // 姓氏
$lastName = $_POST['lastName'] ?? ''; // 名字
$contactEmail = $_POST['contactEmail'] ?? ''; // 联系邮箱
$contactPhone = $_POST['contactPhone'] ?? ''; // 联系电话
$projectState = $_POST['projectState'] ?? ''; // 项目状态/地区
$contactWebSite = $_POST['contactWebSite'] ?? ''; // 网站 (注意：URL列可能需要特殊处理)
$projectMessage = $_POST['projectMessage'] ?? ''; // 项目信息/留言
// 从配置中获取目标看板 ID
// 假设我们要将数据发送到 'testBoard'
$boardId = $boards['testBoard'];
// 获取当前日期，用于日期列
$todaysDate = date("Y-m-d");
// 2. 构建 GraphQL 变异查询
// 注意：`create_item` 变异的 `board_id` 参数直接在查询字符串中，
// 而 `itemName` 和 `columnVals` 通过变量传递。
$query = 'mutation ($itemName: String!, $columnVals: JSON!) {
create_item (board_id: ' . $boardId . ', item_name:$itemName, column_values:$columnVals) {
id
name
}
}';
// 3. 构造 GraphQL 变量
// `columnVals` 是一个 JSON 字符串，包含所有列的值。
// 请务必将以下列 ID 替换为您的 Monday.com 看板中实际的列 ID。
// 例如：'status' -> '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 '
<form method="POST">
<label>公司名称: <input type="text" name="companyName" value="测试公司"></label><br>
<label>名字: <input type="text" name="firstName" value="张"></label><br>
<label>姓氏: <input type="text" name="lastName" value="三"></label><br>
<label>邮箱: <input type="email" name="contactEmail" value="zhangsan@example.com"></label><br>
<label>电话: <input type="text" name="contactPhone" value="1234567890"></label><br>
<label>项目状态: <input type="text" name="projectState" value="New York"></label><br>
<label>网站: <input type="url" name="contactWebSite" value="https://example.com"></label><br>
<label>留言: <textarea name="projectMessage">这是一个测试留言。</textarea></label><br>
<button type="submit">创建潜在客户</button>
</form>
';
}
?>发送 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，其基本结构如下：
<?php // 示例 cURL 请求（替代 file_get_contents 部分） $ch = curl_init($apiUrl); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST"); curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['query' => $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 中，从而提高效率并减少手动数据输入。
