使用 PHP 与 monday.com API 交互：自动化创建线索与交易

本文将详细指导您如何使用 PHP 脚本，通过 monday.com 的 GraphQL API 自动化创建新的线索或交易。我们将涵盖 API 认证配置、GraphQL 突变（Mutation）的构建、不同列类型的数据格式化，以及如何利用 file_get_contents 函数发送 HTTP POST 请求并处理 API 响应，帮助您高效地将 monday.com 集成到现有业务流程中。

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 示例：

<?php
// monday.com API 令牌
$token = '[YOUR_MONDAY_API_KEY]'; // 请替换为您的实际 API 令牌
// monday.com GraphQL API 端点
$apiUrl = 'https://api.monday.com/v2';
// HTTP 请求头，包含内容类型和授权信息
$headers = [
'Content-Type: application/json',
'Authorization: ' . $token
];
// 存储您的看板 ID，可以根据需要添加更多
$boards = [
"testBoard"  => 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 突变，并发送请求。

<?php
include('config.php'); // 包含配置信息
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'] ?? '';
// 2. 选择目标看板 ID
// 假设我们想将线索添加到 config.php 中定义的 'testBoard'
$boardId = $boards['testBoard'];
// 3. 获取当前日期，用于日期列
$todaysDate = date("Y-m-d");
// 4. 构建 column_values JSON 字符串
// 请确保这里的键（如 'status', 'date4', 'text__1' 等）与您 monday.com 看板中的实际列 ID 匹配
$columnValsArray = [
'status'        => [
'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 '<form method="POST">
<input type="text" name="companyName" placeholder="公司名称" required><br>
<input type="text" name="firstName" placeholder="名"><br>
<input type="text" name="lastName" placeholder="姓"><br>
<email type="email" name="contactEmail" placeholder="邮箱"><br>
<input type="tel" name="contactPhone" placeholder="电话"><br>
<input type="text" name="projectState" placeholder="项目状态"><br>
<input type="url" name="contactWebSite" placeholder="公司网址"><br>
<textarea name="projectMessage" placeholder="项目消息"></textarea><br>
<button type="submit">创建线索</button>
</form>';
*/
}
?>

5. 注意事项与最佳实践

1. 安全性：API 令牌管理

   • 在生产环境中，API 令牌绝不能直接硬编码在代码中。应使用环境变量、密钥管理服务（如 AWS Secrets Manager、Azure Key Vault）或配置文件（并确保该文件不被版本控制）来存储和加载。
   • 限制 API 令牌的权限，只授予完成所需任务的最小权限。

2. 错误处理

   • 上述代码中的 @file_get_contents 会抑制错误，这不利于调试。在开发阶段，移除 @ 符号，并添加更健壮的错误检查机制。
   • 检查 $responseContent 是否为 null 或包含 errors 键，以判断 API 请求是否成功或出现错误。
   • HTTP 状态码：file_get_contents 配合 stream_context_create 允许通过 $http_response_header 变量访问响应头，从而获取 HTTP 状态码。

3. 列 ID 的准确性

   • monday.com 的列 ID 是区分大小写的，且可能包含特殊字符或下划线。务必使用 API Playground 或通过查询获取的准确列 ID。
   • 如果列 ID 不匹配或列类型不正确，API 将返回错误。

4. 链接列 (Link Column)

   • 原始问题中提到链接列的添加存在问题。monday.com API 对于某些复杂列类型可能需要特定的格式或权限。如果遇到问题，请仔细查阅 monday.com 的最新 API 文档，或在 monday.com 开发者社区寻求帮助。通常，链接列的 column_values 结构类似于 {“url”: “…”, “text”: “…”}。

5. 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 ...

6. 异步处理

   • 如果您的表单提交后需要快速响应用户，而 monday.com API 请求可能耗时较长，可以考虑将 API 调用放在后台异步处理（例如使用消息队列或 exec 命令启动一个独立的 PHP 进程）。

6. 总结

通过本教程，您应该已经掌握了如何使用 PHP 脚本与 monday.com 的 GraphQL API 进行交互，以自动化创建新的线索或交易。关键在于正确配置 API 令牌、构建符合 GraphQL 规范的突变查询，以及根据 monday.com 列类型正确格式化 column_values 参数。通过这些基础知识，您可以进一步扩展功能，实现更复杂的 monday.com 自动化集成，提升工作效率。