本文将详细指导您如何使用 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 示例：
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 自动化集成，提升工作效率。
以上就是使用 PHP 与 monday.com API 交互：自动化创建线索与交易的详细内容，更多请关注php中文网其它相关文章！
版权声明：本文内容由互联网用户自发贡献，该文观点仅代表作者本人。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。
如发现本站有涉嫌抄袭侵权/违法违规的内容， 请发送邮件至 chuangxiangniao@163.com 举报，一经查实，本站将立刻删除。
发布者：程序猿，转转请注明出处：https://www.chuangxiangniao.com/p/1321724.html
微信扫一扫 
支付宝扫一扫 
