1. Monday.com API 基础与认证
monday.com 提供了一套强大的 graphql api，允许开发者以编程方式与平台进行交互，例如创建、读取、更新和删除看板条目。所有的 api 请求都需要通过认证来确保安全。
API 认证方式： Monday.com API 主要通过个人访问令牌（Personal Access Token）进行认证。这个令牌需要在请求头中以 Authorization: [YOUR_API_KEY] 的形式发送。
GraphQL 概述： Monday.com API 使用 GraphQL 查询语言。这意味着所有的操作（查询数据、创建/更新数据）都通过单个端点进行，并使用 query（读取数据）或 mutation（修改数据）来定义操作类型。
2. 环境准备与配置
在开始之前，我们需要设置一个配置文件来存储 API 密钥、API 端点和看板 ID 等敏感信息，以便于管理和维护。
config.php 文件设置：
创建一个名为 config.php 的文件，并包含以下内容。请务必将 [YOUR API KEY] 替换为您真实的 Monday.com API 密钥。
1918282734, // 示例看板ID "boardName2" => 1987654321, "boardName3" => 4567123890, "testBoard" => 6376637288 // 用于测试的看板ID ); ?>
注意事项：
立即学习“PHP免费学习笔记（深入）”；
- API 密钥安全： 绝不要将您的 API 密钥直接暴露在客户端代码或版本控制中。在生产环境中，应考虑使用环境变量或其他更安全的密钥管理方案。
- 看板 ID： 您可以在 Monday.com 看板的 URL 中找到其 ID（例如 https://monday.com/boards/1234567890/，其中 1234567890 就是看板 ID）。
3. PHP 实现：创建 Monday.com 条目
本节将详细介绍如何编写 PHP 代码来接收表单数据，构建 GraphQL 突变，并将其发送到 Monday.com API 以创建新的销售线索或交易条目。
3.1 接收表单数据
假设您有一个 HTML 表单用于收集销售线索信息。当表单通过 POST 方法提交时，PHP 脚本将接收这些数据。
3.2 构建 GraphQL 突变 (create_item)
要创建一个新的条目，我们将使用 Monday.com API 提供的 create_item 突变。这个突变需要 board_id（看板 ID）、item_name（条目名称）和 column_values（列值）作为参数。
column_values 是一个 JSON 字符串，它将表单数据映射到 Monday.com 看板上的各个列。每个列值都需要根据其类型进行格式化。
// GraphQL 突变字符串
// $itemName 和 $columnVals 是变量，将在 vars 数组中定义
$query = 'mutation ($itemName: String!, $columnVals: JSON!) {
create_item (board_id:'. $boardId . ', item_name:$itemName, column_values:$columnVals) {
id
}
}';
// 定义 GraphQL 突变所需的变量
$vars = [
'itemName' => $companyName, // 使用公司名称作为条目名称
'columnVals' => json_encode([
// 状态列：'status' 是列的 ID，'label' 是状态的文本值
'status' => [
'label' => 'New Lead' // 例如：设置为“新线索”
],
// 日期列：'date4' 是列的 ID，'date' 是日期值
'date4' => [
'date' => $todaysDate
],
// 文本列：'text__1' 是列的 ID，直接传入文本值
'text__1' => $firstName,
'text5__1' => $lastName,
// 邮箱列：'email__1' 是列的 ID，需要 'email' 和 'text' 字段
'email__1' => [
'email' => $contactEmail,
'text' => $contactEmail // 文本显示值
],
// 电话列：'phone__1' 是列的 ID，需要 'phone' 和 'countryShortName' 字段
'phone__1' => [
'phone' => $contactPhone,
'countryShortName' => 'US' // 国家代码，例如 'US' 代表美国
],
// 另一个文本列
'text7__1' => $projectState,
// 长文本列：'long_text4__1' 是列的 ID
'long_text4__1' => $projectMessage
])
];关键点：
- 列 ID (Column ID)： 示例中的 status, date4, text__1 等是 Monday.com 看板中列的唯一标识符。您需要在您的 Monday.com 看板设置中找到这些 ID。通常，可以通过点击列标题 -> 设置 -> 更改列类型 -> 更多设置来找到。
- 数据类型映射： 不同类型的 Monday.com 列需要不同的 JSON 格式来设置其值。例如，状态列需要 label 字段，日期列需要 date 字段，邮箱列需要 email 和 text 字段，而普通文本列可以直接传入字符串。
4. 发送 API 请求与处理响应
在构建好 GraphQL 突变和变量后，我们需要将其作为 POST 请求发送到 Monday.com API 端点。本教程采用 file_get_contents 结合 stream_context_create 的方式来发送 HTTP 请求。
// 构造请求数据
$requestPayload = json_encode([
'query' => $query,
'variables' => $vars
]);
// 使用 stream_context_create 发送 POST 请求
$data = @file_get_contents($apiUrl, false, stream_context_create([
'http' => [
'method' => 'POST',
'header' => $headers, // 使用 config.php 中定义的请求头
'content' => $requestPayload,
]
]));
// 解析 API 响应
$responseContent = json_decode($data, true);
// 输出响应内容，用于调试或进一步处理
echo json_encode($responseContent);
}
?>5. 完整代码示例
以下是整合了 config.php 和主处理逻辑的完整代码示例。
config.php
1918282734, // 示例看板ID "boardName2" => 1987654321, "boardName3" => 4567123890, "testBoard" => 6376637288 // 用于测试的看板ID ); ?>
主处理脚本 (例如 create_lead.php)
$companyName,
'columnVals' => json_encode([
'status' => [
'label' => 'New Lead'
],
'date4' => [
'date' => $todaysDate
],
'text__1' => $firstName,
'text5__1' => $lastName,
'email__1' => [
'email' => $contactEmail,
'text' => $contactEmail
],
'phone__1' => [
'phone' => $contactPhone,
'countryShortName' => 'US' // 示例，根据需要修改
],
'text7__1' => $projectState,
'long_text4__1' => $projectMessage
// 如果需要添加链接列，格式类似：
// 'link_column_id' => [
// 'url' => $contactWebSite,
// 'text' => $contactWebSite
// ]
])
];
// 构造请求数据
$requestPayload = json_encode([
'query' => $query,
'variables' => $vars
]);
// 使用 stream_context_create 发送 POST 请求
// @ 符号用于抑制 file_get_contents 可能产生的警告
$data = @file_get_contents($apiUrl, false, stream_context_create([
'http' => [
'method' => 'POST',
'header' => $headers,
'content' => $requestPayload,
]
]));
// 解析 API 响应
$responseContent = json_decode($data, true);
// 输出响应内容，用于调试或进一步处理
// 实际应用中，您可能需要检查响应是否成功并返回适当的信息给用户
echo json_encode($responseContent);
} else {
// 如果不是 POST 请求，可以返回错误信息或显示表单
echo json_encode(['error' => 'Invalid request method. Please submit a POST request.']);
}
?>6. 注意事项与最佳实践
- 列 ID 匹配： 确保代码中的列 ID（如 status, date4, text__1 等）与您的 Monday.com 看板中的实际列 ID 完全匹配。不匹配会导致数据无法正确写入。
- 数据类型： Monday.com 对不同类型的列有严格的数据格式要求。务必根据列类型（如状态、日期、邮箱、电话、链接、文本等）正确构建 column_values 中的 JSON 结构。例如，链接列需要 url 和 text 字段，而电话列需要 phone 和 countryShortName。
- 错误处理： 在实际应用中，您应该添加更健壮的错误处理机制。检查 file_get_contents 的返回值，以及 Monday.com API 响应中的 errors 字段，以便及时发现并解决问题。
- file_get_contents 与 cURL： 虽然本教程使用了 file_get_contents 结合 stream_context_create 来发送 HTTP 请求，但 PHP 的 cURL 扩展是更强大、更灵活的 HTTP 客户端库，尤其适用于复杂的请求、超时控制、证书验证等场景。对于生产环境，通常推荐使用 cURL。如果您希望使用 cURL，需要进行相应的代码调整。
- 安全性： 除了 API 密钥的保护，还要注意对所有用户输入进行验证和清理，以防止 SQL 注入、XSS 攻击等常见的 Web 安全漏洞。
- 异步处理： 对于大量数据或性能敏感的场景，考虑将 API 请求放入队列进行异步处理，以避免阻塞用户界面。
总结
通过本教程，您应该已经掌握了如何使用 PHP 连接 Monday.com API，并自动化创建销售线索或交易条目的基本方法。这包括了 API 认证、GraphQL 突变的构建、数据映射以及请求的发送和响应处理。通过定制 config.php 文件和调整 column_values 的映射，您可以轻松地将此解决方案应用于不同的 Monday.com 看板和业务场景，从而有效提升工作效率和数据管理能力。
