1. 引言
monday.com 作为一个强大的工作管理平台，提供了丰富的 api 接口，允许开发者与平台进行编程交互。本教程将聚焦于一个常见的业务需求：通过 php 脚本，从外部系统（例如网站表单）接收数据，并将其作为新的线索或交易自动添加到 monday.com 的指定看板中。尽管问题中提到了 curl php，但本文将基于提供的解决方案，使用 php 内置的 file_get_contents 函数配合 stream_context_create 来发送 http 请求，这在很多场景下也是一个可行的选择。
2. 环境准备与 API 配置
在开始之前，您需要准备以下信息：
- monday.com API 令牌 (API Key)：这是您访问 monday.com API 的凭证。您可以在 monday.com 账户的“管理”->“API”部分找到或生成您的个人 API 令牌。
- 看板 ID (Board ID)：您希望创建线索或交易的 monday.com 看板的唯一标识符。
- 列 ID (Column IDs)：看板中各个列的唯一标识符。不同的列类型（如状态、文本、日期、邮箱、电话等）在 API 中有不同的数据结构要求。
为了更好地组织配置信息，建议创建一个 config.php 文件来存储这些敏感数据和常用设置。
config.php 示例：
1234567890, // 替换为您的实际看板 ID
"boardName1" => 1918282734,
"boardName2" => 1987654321,
// ...更多看板
];
// 假设您可能还需要组 ID，尽管本教程主要关注看板中的项目创建
// "testGroup" => 6376637288 // 示例组 ID
?>注意事项：
立即学习“PHP免费学习笔记（深入）”；
- 请务必将 [YOUR_MONDAY_API_KEY] 替换为您的真实 API 令牌。
- 出于安全考虑，在生产环境中，API 令牌不应直接硬编码在代码中，而应通过环境变量或其他安全机制进行管理。
- testBoard 只是一个示例键名，您可以根据实际看板名称进行命名，并替换为您的实际看板 ID。
3. monday.com API 交互基础
monday.com API 主要基于 GraphQL。这意味着您需要构建一个 GraphQL 查询（Query）或突变（Mutation）来执行操作。创建新项目（线索或交易）属于突变操作。
3.1 GraphQL 突变：创建项目 (create_item)
要创建一个新项目，我们将使用 create_item 突变。它通常需要以下参数：
- board_id：目标看板的 ID。
- group_id (可选)：目标组的 ID。如果未指定，项目将添加到默认组。
- item_name：新项目的名称（例如，公司名称或线索标题）。
- column_values：一个 JSON 字符串，包含所有列的值。这是最关键的部分，因为不同类型的列需要特定的 JSON 结构。
3.2 列值 (column_values) 的结构
column_values 参数是一个 JSON 字符串，其内部结构取决于您要更新的列类型。以下是一些常见列类型的示例：
-
状态列 (Status Column)：
"status": { "label": "New Lead" // 标签文本 } -
日期列 (Date Column)：
"date4": { // 这里的 "date4" 是列 ID "date": "2023-10-27" // YYYY-MM-DD 格式 } -
文本列 (Text Column)：
"text__1": "John" // 这里的 "text__1" 是列 ID，直接传递字符串
-
邮箱列 (Email Column)：
"email__1": { // 这里的 "email__1" 是列 ID "email": "john.doe@example.com", "text": "john.doe@example.com" // 显示文本 } -
电话列 (Phone Column)：
"phone__1": { // 这里的 "phone__1" 是列 ID "phone": "+15551234567", "countryShortName": "US" // 国家代码 } -
长文本列 (Long Text Column)：
"long_text4__1": "这是一个详细的项目描述。" // 直接传递字符串
如何获取列 ID？ 您可以通过 monday.com 的 API Playground (通常在 API 文档中提供) 或通过一个简单的 GraphQL 查询来获取看板的列 ID：
query {
boards(ids: [YOUR_BOARD_ID]) {
columns {
id
title
type
}
}
}4. PHP 实现：从表单数据创建项目
接下来，我们将编写 PHP 脚本来接收表单数据，构建 GraphQL 突变，并发送请求。
[
'label' => 'New Lead' // 设置状态为“新线索”
],
'date4' => [ // 假设这是您的日期列 ID
'date' => $todaysDate
],
'text__1' => $firstName, // 假设这是您的名字文本列 ID
'text5__1' => $lastName, // 假设这是您的姓氏文本列 ID
'email__1' => [ // 假设这是您的邮箱列 ID
'email' => $contactEmail,
'text' => $contactEmail
],
'phone__1' => [ // 假设这是您的电话列 ID
'phone' => $contactPhone,
'countryShortName' => 'US' // 根据需要调整国家代码
],
'text7__1' => $projectState, // 假设这是您的项目状态文本列 ID
'long_text4__1' => $projectMessage // 假设这是您的长文本消息列 ID
// 'link__1' => [ // 链接列在原始问题中未成功，但结构通常如下
// 'url' => $contactWebSite,
// 'text' => $contactWebSite
// ]
];
// 将 PHP 数组编码为 JSON 字符串，作为 column_values 参数
$columnValsJson = json_encode($columnValsArray);
// 5. 构建 GraphQL 突变查询
// 注意：这里的 $itemName 和 $columnVals 是 GraphQL 变量，不是 PHP 变量
$query = 'mutation ($itemName: String!, $columnVals: JSON!) {
create_item (
board_id:' . $boardId . ',
item_name:$itemName,
column_values:$columnVals
) {
id
name
column_values {
id
value
text
}
}
}';
// 6. 定义 GraphQL 变量
$vars = [
'itemName' => $companyName, // 新项目的名称
'columnVals' => $columnValsJson // 包含所有列值的 JSON 字符串
];
// 7. 准备 HTTP 请求内容
$requestContent = json_encode([
'query' => $query,
'variables' => $vars
]);
// 8. 使用 stream_context_create 和 file_get_contents 发送 POST 请求
$context = stream_context_create([
'http' => [
'method' => 'POST',
'header' => $headers, // 从 config.php 获取的请求头
'content' => $requestContent,
'ignore_errors' => true // 允许获取错误响应体
]
]);
$data = @file_get_contents($apiUrl, false, $context);
// 9. 处理 API 响应
$responseContent = json_decode($data, true);
// 输出响应，用于调试或进一步处理
header('Content-Type: application/json');
echo json_encode($responseContent, JSON_PRETTY_PRINT);
} else {
// 如果不是 POST 请求，可以显示一个简单的表单或者错误信息
echo "请通过 POST 请求提交数据。";
// 示例 HTML 表单 (仅用于测试目的)
/*
echo '';
*/
}
?>5. 注意事项与最佳实践
-
安全性：API 令牌管理
- 在生产环境中，API 令牌绝不能直接硬编码在代码中。应使用环境变量、密钥管理服务（如 AWS Secrets Manager、Azure Key Vault）或配置文件（并确保该文件不被版本控制）来存储和加载。
- 限制 API 令牌的权限，只授予完成所需任务的最小权限。
-
错误处理
- 上述代码中的 @file_get_contents 会抑制错误，这不利于调试。在开发阶段，移除 @ 符号，并添加更健壮的错误检查机制。
- 检查 $responseContent 是否为 null 或包含 errors 键，以判断 API 请求是否成功或出现错误。
- HTTP 状态码：file_get_contents 配合 stream_context_create 允许通过 $http_response_header 变量访问响应头，从而获取 HTTP 状态码。
-
列 ID 的准确性
- monday.com 的列 ID 是区分大小写的，且可能包含特殊字符或下划线。务必使用 API Playground 或通过查询获取的准确列 ID。
- 如果列 ID 不匹配或列类型不正确，API 将返回错误。
-
链接列 (Link Column)
- 原始问题中提到链接列的添加存在问题。monday.com API 对于某些复杂列类型可能需要特定的格式或权限。如果遇到问题，请仔细查阅 monday.com 的最新 API 文档，或在 monday.com 开发者社区寻求帮助。通常，链接列的 column_values 结构类似于 {"url": "...", "text": "..."}。
-
file_get_contents 与 cURL 扩展
- 本教程使用了 PHP 的 file_get_contents 函数配合 stream_context_create 来发送 HTTP 请求。这种方法简单易用，但对于更复杂的 HTTP 请求（如处理文件上传、更细粒度的超时控制、重定向跟踪等），PHP 的 cURL 扩展通常是更强大和灵活的选择。如果您需要更专业的 HTTP 客户端功能，建议切换到 cURL 扩展。
- 使用 cURL 扩展的基本结构如下：
// ... 配置 $token, $apiUrl, $headers, $requestContent ... $ch = curl_init($apiUrl); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST"); curl_setopt($ch, CURLOPT_POSTFIELDS, $requestContent); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $data = curl_exec($ch); $http_status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); // ... 处理 $data 和 $http_status ...
-
异步处理
- 如果您的表单提交后需要快速响应用户，而 monday.com API 请求可能耗时较长，可以考虑将 API 调用放在后台异步处理（例如使用消息队列或 exec 命令启动一个独立的 PHP 进程）。
6. 总结
通过本教程，您应该已经掌握了如何使用 PHP 脚本与 monday.com 的 GraphQL API 进行交互，以自动化创建新的线索或交易。关键在于正确配置 API 令牌、构建符合 GraphQL 规范的突变查询，以及根据 monday.com 列类型正确格式化 column_values 参数。通过这些基础知识，您可以进一步扩展功能，实现更复杂的 monday.com 自动化集成，提升工作效率。
