1. Monday.com API 简介与集成目标
monday.com 是一款流行的工作管理平台，通过其强大的 api，用户可以实现与外部系统的无缝集成，自动化工作流程。本教程的目标是演示如何使用 php 脚本，通过 monday.com 的 graphql api 创建新的“项”（item），例如将网站表单提交的潜在客户信息直接添加到 monday.com 的看板中。尽管标题提及 curl，但本教程将采用 php 内置的 file_get_contents 函数结合 stream_context_create 来发送 http post 请求，这种方法在许多简单场景下与 curl 具有相似的功能。
2. API 认证与配置
与 Monday.com API 交互的第一步是进行认证。Monday.com API 使用个人访问令牌（Personal Access Token）进行认证。为了代码的清晰性和安全性，建议将 API 密钥、API 端点以及常用的看板 ID 存储在一个单独的配置文件中。
config.php 文件示例：
<?php
// Monday.com API 访问令牌
// 请替换为您的实际 API 密钥
$token = '[YOUR API KEY]';
// Monday.com API 端点
$apiUrl = 'https://api.monday.com/v2';
// HTTP 请求头，指定内容类型为 JSON 并包含认证令牌
$headers = ['Content-Type: application/json', 'Authorization: ' . $token ];
// 常用的看板 ID 映射，方便通过名称引用
$boards = array(
"boardName1" => 1918282734,
"boardName2" => 1987654321,
"boardName3" => 4567123890,
"testBoard" => 6376637288 // 示例测试看板 ID
);
?>注意事项：
- API 密钥安全： 您的 API 密钥是敏感信息，请务必妥善保管，不要将其直接暴露在客户端代码或公共仓库中。
- 看板 ID： boards 数组中的 ID 应替换为您 Monday.com 账号中实际的看板 ID。您可以在 Monday.com 看板的 URL 中找到 ID，或者通过 API 查询获取。
3. 构建 GraphQL 突变：创建新项
Monday.com API 基于 GraphQL。要创建一个新的项（例如一个潜在客户），我们需要使用 create_item 突变（mutation）。这个突变需要至少两个参数：board_id（要创建项的看板 ID）和 item_name（项的名称）。此外，我们还可以通过 column_values 参数来设置各项列的值。
立即学习“PHP免费学习笔记（深入）”；
create_item 突变结构：
mutation ($itemName: String!, $columnVals: JSON!) {
create_item (board_id: [YOUR_BOARD_ID], item_name: $itemName, column_values: $columnVals) {
id
}
}- $itemName: String!: 定义了一个名为 itemName 的变量，类型为非空字符串，用于项的名称。
- $columnVals: JSON!: 定义了一个名为 columnVals 的变量，类型为非空 JSON 字符串，用于设置列的值。
- board_id: [YOUR_BOARD_ID]: 直接在查询字符串中指定看板 ID。
- item_name: $itemName: 将项的名称绑定到 $itemName 变量。
- column_values: $columnVals: 将列的值绑定到 $columnVals 变量。
- { id }: 表示在创建成功后，我们希望返回新创建项的 ID。
4. PHP 脚本实现：处理表单数据并创建项
下面的 PHP 脚本演示了如何接收一个 HTML 表单提交的数据，并将其格式化后发送到 Monday.com API 以创建新的潜在客户。
<?php
// 引入配置文件，获取 API 密钥、端点和请求头
include('config.php');
// 确保请求方法为 POST
if ($_SERVER["REQUEST_METHOD"] == "POST") {
// 1. 从表单获取输入值
$companyName = $_POST['companyName'] ?? '新潜在客户'; // 默认值以防未提供
$firstName = $_POST['firstName'] ?? '';
$lastName = $_POST['lastName'] ?? '';
$contactEmail = $_POST['contactEmail'] ?? '';
$contactPhone = $_POST['contactPhone'] ?? '';
$projectState = $_POST['projectState'] ?? '';
$contactWebSite = $_POST['contactWebSite'] ?? ''; // 网站列的处理需要额外注意
$projectMessage = $_POST['projectMessage'] ?? '';
// 从 config.php 获取目标看板 ID
// 假设 'testBoard' 是我们想要创建项的看板
$boardId = $boards['testBoard'];
// 获取当前日期，用于日期列
$todaysDate = date("Y-m-d");
// 2. 构建 GraphQL 突变查询字符串
// board_id 直接拼接，itemName 和 columnVals 作为变量传递
$query = 'mutation ($itemName: String!, $columnVals: JSON!) {
create_item (board_id:'. $boardId . ', item_name:$itemName, column_values:$columnVals) {
id
}
}';
// 3. 准备 GraphQL 变量
// columnVals 需要是一个 JSON 字符串，其中包含列的 ID 和对应的值
$vars = [
'itemName' => $companyName, // 项的名称，通常是公司名或主要联系人
'columnVals' => json_encode([
// 状态列 (Status Column)
// 'label' 对应 Monday.com 状态列的标签文本
'status' => [
'label' => 'New Lead'
],
// 日期列 (Date Column)
// 'date4' 是日期列的 ID，'date' 字段是日期值
'date4' => [
'date' => $todaysDate
],
// 文本列 (Text Column)
// 'text__1' 是文本列的 ID
'text__1' => $firstName, // 名
'text5__1' => $lastName, // 姓
// 电子邮件列 (Email Column)
// 'email__1' 是电子邮件列的 ID，需要 'email' 和 'text' 字段
'email__1' => [
'email' => $contactEmail,
'text' => $contactEmail // 'text' 字段通常与 'email' 相同
],
// 电话列 (Phone Column)
// 'phone__1' 是电话列的 ID，需要 'phone' 和 'countryShortName' 字段
'phone__1' => [
'phone' => $contactPhone,
'countryShortName' => 'US' // 国家简称，例如 'US', 'CN'
],
// 另一个文本列
'text7__1' => $projectState, // 项目状态或地区
// 长文本列 (Long Text Column)
// 'long_text4__1' 是长文本列的 ID
'long_text4__1' => $projectMessage // 项目消息或备注
// 注意：链接列（URL Column）的处理可能更复杂，示例中未完全实现
// 'link_column_id' => ['url' => $contactWebSite, 'text' => $contactWebSite]
// 如果上述链接列不工作，请查阅 Monday.com 最新 API 文档
])
];
// 4. 发送 POST 请求到 Monday.com API
// 使用 file_get_contents 结合 stream_context_create 模拟 POST 请求
$data = @file_get_contents($apiUrl, false, stream_context_create([
'http' => [
'method' => 'POST',
'header' => $headers, // 从 config.php 获取的请求头
'content' => json_encode([
'query' => $query,
'variables' => $vars
]),
'ignore_errors' => true // 忽略 HTTP 错误，以便始终读取响应体
]
]));
// 5. 解析 API 响应并输出
$responseContent = json_decode($data, true);
echo json_encode($responseContent);
} else {
// 如果不是 POST 请求，可以返回错误或显示一个表单
echo json_encode(['error' => '请通过 POST 方法提交数据。']);
}
?>5. 关键点与注意事项
- 列 ID (Column IDs)： 代码中的 'status', 'date4', 'text__1', 'email__1', 'phone__1', 'long_text4__1' 等都是 Monday.com 看板中具体列的 ID。这些 ID 必须与您的 Monday.com 看板中的实际列 ID 严格匹配。您可以通过 Monday.com 的 API 探索器或在看板设置中检查列的开发者 ID 来获取它们。
-
列值格式 (Column Values Format)：
- 文本列 (Text/Long Text)： 直接传递字符串即可。
- 状态列 (Status)： 需要一个包含 label 字段的对象，label 的值必须是该状态列中已存在的标签文本。
- 日期列 (Date)： 需要一个包含 date 字段的对象，日期格式为 YYYY-MM-DD。
- 电子邮件列 (Email)： 需要一个包含 email 和 text 字段的对象。
- 电话列 (Phone)： 需要一个包含 phone 和 countryShortName 字段的对象，countryShortName 是 ISO 3166-1 alpha-2 国家代码（例如 'US', 'CN', 'GB'）。
- 链接列 (URL)： 示例中提到链接列可能比较棘手。通常需要 url 和 text 字段，但具体实现可能因 API 版本而异。如果上述示例不工作，请务必查阅 Monday.com 最新的 API 文档。
- 错误处理： 示例代码中 @file_get_contents 抑制了错误，并且 ignore_errors 设置为 true。在生产环境中，应移除 @ 并添加更健壮的错误检查机制，例如检查 file_get_contents 的返回值是否为 false，并解析 API 响应中的 errors 字段来获取详细的错误信息。
- HTTP 请求方式： 尽管本教程使用了 file_get_contents，但对于更复杂的 HTTP 请求（例如需要设置超时、代理、更详细的错误处理等），PHP 的 cURL 扩展是更强大和灵活的选择。基本用法类似，只是将 stream_context_create 部分替换为 curl_init(), curl_setopt(), curl_exec() 等 cURL 函数。
- 表单验证： 在处理 $_POST 数据之前，进行严格的输入验证和清理是至关重要的，以防止 SQL 注入、XSS 攻击或其他安全漏洞。
6. 总结
通过本教程，您应该已经掌握了如何使用 PHP 脚本，结合 Monday.com 的 GraphQL API 来创建新的项。这包括了 API 认证、构建 GraphQL 突变、正确格式化列数据以及发送 HTTP POST 请求。掌握这些基础知识后，您可以进一步扩展功能，例如更新现有项、查询看板数据、实现更复杂的自动化工作流，从而将 Monday.com 与您的业务系统紧密集成。在开发过程中，请始终参考 Monday.com 官方的 API 文档，以获取最新的 API 规范和最佳实践。
