使用PHP cURL连接Monday.com API创建线索或交易

本文详细介绍了如何使用PHP cURL与Monday.com API进行交互，以创建新的线索或交易（即项目）。教程涵盖了API密钥配置、GraphQL mutation的构建、不同类型列数据的JSON格式化，以及通过cURL发送POST请求的完整实现，旨在帮助开发者高效地将外部数据集成到Monday.com平台。

1. Monday.com API集成概述

Monday.com作为一个强大的工作操作系统，提供了丰富的API接口，允许开发者通过编程方式与其平台进行交互。本教程将重点讲解如何利用PHP的cURL扩展，向Monday.com发送GraphQL mutation请求，从而在指定的看板（Board）上创建新的项目（Item），这通常用于自动化线索（Lead）或交易（Deal）的录入。

2. 环境准备与API凭证配置

在开始之前，您需要从Monday.com账户获取API密钥，并准备好相关的看板ID（Board ID）和列ID（Column ID）。

2.1 获取API密钥

登录您的Monday.com账户，导航至“管理员”设置，然后找到“API”部分，即可生成或查看您的API密钥。请妥善保管此密钥，因为它拥有访问您账户数据的权限。

2.2 配置API参数

为了代码的模块化和安全性，建议将API密钥、API端点和看板ID等配置信息存储在一个单独的文件中，例如 config.php。

立即学习“PHP免费学习笔记（深入）”；

config.php 示例：

<?php // Monday.com API 密钥，请替换为您的实际密钥 $token = '[YOUR_MONDAY_API_KEY]';   // Monday.com API v2 端点 $apiUrl = 'https://api.monday.com/v2';  // API 请求头 $headers = [     'Content-Type: application/json',     'Authorization: ' . $token ];  // 示例看板ID，请替换为您的实际看板ID $boards = array(     "testBoard" => 1234567890, // 替换为您的实际看板ID     // 您可以添加更多看板的ID ); ?>

在实际应用中，$boards 数组可以存储多个看板的ID，以便根据业务需求选择不同的看板。

3. 构建API请求头与GraphQL Mutation

与Monday.com API交互主要通过GraphQL进行。我们需要构建一个GraphQL mutation来创建项目，并将其作为JSON请求体的一部分发送。

3.1 GraphQL create_item Mutation

创建项目的GraphQL mutation通常如下所示：

mutation ($itemName: String!, $columnVals: JSON!) {   create_item (board_id: [YOUR_BOARD_ID], item_name: $itemName, column_values: $columnVals) {     id   } }

$itemName: 表示新创建项目的名称。
$columnVals: 一个JSON字符串，包含所有列的值。
board_id: 您要创建项目的看板ID。
id: 表示成功创建后返回的项目ID。

3.2 构造 column_values JSON

column_values 是一个JSON字符串，其结构取决于您看板中列的类型。以下是一些常见列类型的示例：

状态列 (Status Column):
```
"status_column_id": { "label": "Status Label" }
```
例如：”status”: { “label”: “New Lead” }
日期列 (Date Column):
```
"date_column_id": { "date": "YYYY-MM-DD" }
```
例如：”date4″: { “date”: “2023-10-27” }
文本列 (Text Column):

Swapface人脸交换

一款创建逼真人脸交换的AI换脸工具

45

查看详情
```
"text_column_id": "Your Text Value"
```
例如：”text__1″: “John”
邮箱列 (Email Column):
```
"email_column_id": { "email": "email@example.com", "text": "email@example.com" }
```
例如：”email__1″: { “email”: “contact@example.com”, “text”: “contact@example.com” }
电话列 (Phone Column):
```
"phone_column_id": { "phone": "1234567890", "countryShortName": "US" }
```
例如：”phone__1″: { “phone”: “1234567890”, “countryShortName”: “US” }
长文本列 (Long Text Column):
```
"long_text_column_id": "Your long text message."
```
例如：”long_text4__1″: “Project details here.”

重要提示：

column_id 必须与您的Monday.com看板中的实际列ID完全匹配。您可以通过Monday.com的开发者模式或API文档找到这些ID。
某些列类型（如URL、文件）可能需要更复杂的JSON结构或不同的API端点来处理。

4. PHP cURL实现API请求

现在，我们将结合 config.php 和 GraphQL mutation 来构建一个完整的PHP脚本，该脚本可以从一个HTML表单接收数据，并使用cURL将其发送到Monday.com。

create_lead.php 示例：

<?php // 引入配置文件 include('config.php');  // 检查是否为POST请求 if ($_SERVER["REQUEST_METHOD"] == "POST") {     // 从表单获取输入值     $companyName    = $_POST['companyName'] ?? 'Default Company';     $firstName      = $_POST['firstName'] ?? '';     $lastName       = $_POST['lastName'] ?? '';     $contactEmail   = $_POST['contactEmail'] ?? '';     $contactPhone   = $_POST['contactPhone'] ?? '';     $projectState   = $_POST['projectState'] ?? '';     $contactWebSite = $_POST['contactWebSite'] ?? ''; // 待实现     $projectMessage = $_POST['projectMessage'] ?? '';      // 获取目标看板ID     // 假设我们使用 config.php 中定义的 "testBoard"     $boardId = $boards['testBoard'];       // 获取当前日期     $todaysDate = date("Y-m-d");      // 构建 GraphQL mutation 查询     $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([             // 确保这些列ID与您的Monday.com看板中的实际列ID匹配             'status'        => [ // 状态列ID                 'label' => 'New Lead'             ],             'date4'         => [ // 日期列ID                 'date' => $todaysDate             ],             'text__1'       => $firstName, // 文本列ID (FirstName)             'text5__1'      => $lastName,  // 文本列ID (LastName)             'email__1'      => [ // 邮箱列ID                 'email' => $contactEmail,                 'text'  => $contactEmail             ],             'phone__1'      => [ // 电话列ID                 'phone' => $contactPhone,                 'countryShortName' => 'US' // 根据需要调整国家代码             ],             'text7__1'      => $projectState, // 文本列ID (ProjectState)             'long_text4__1' => $projectMessage // 长文本列ID (ProjectMessage)             // 如果需要添加网站URL，可以尝试以下方式，但可能需要根据Monday.com API文档调整             // 'link__1' => [ 'url' => $contactWebSite, 'text' => $contactWebSite ]          ])     ];      // 构建 cURL 请求数据     $postData = json_encode([         'query'     => $query,         'variables' => $vars     ]);      // 初始化 cURL 会话     $ch = curl_init();      // 设置 cURL 选项     curl_setopt($ch, CURLOPT_URL, $apiUrl); // API 端点     curl_setopt($ch, CURLOPT_POST, true); // POST 请求     curl_setopt($ch, CURLOPT_POSTFIELDS, $postData); // 请求体     curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); // 请求头     curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // 返回响应内容而不是直接输出      // 执行 cURL 请求并获取响应     $response = curl_exec($ch);      // 检查 cURL 错误     if (curl_errno($ch)) {         echo 'cURL Error: ' . curl_error($ch);     } else {         // 解码 JSON 响应         $responseContent = json_decode($response, true);         echo json_encode($responseContent); // 输出 API 响应     }      // 关闭 cURL 会话     curl_close($ch); } else {     echo "This script only accepts POST requests."; } ?>

对应的HTML表单示例 (例如 lead_form.html):

<!DOCTYPE html> <html lang="en"> <head>     <meta charset="UTF-8">     <meta name="viewport" content="width=device-width, initial-scale=1.0">     <title>创建 Monday.com 线索</title> </head> <body>     <h1>创建新的 Monday.com 线索</h1>     <form action="create_lead.php" method="POST">         <label for="companyName">公司名称:</label><br>         <input type="text" id="companyName" name="companyName" required><br><br>          <label for="firstName">名:</label><br>         <input type="text" id="firstName" name="firstName"><br><br>          <label for="lastName">姓:</label><br>         <input type="text" id="lastName" name="lastName"><br><br>          <label for="contactEmail">联系邮箱:</label><br>         <input type="email" id="contactEmail" name="contactEmail"><br><br>          <label for="contactPhone">联系电话:</label><br>         <input type="tel" id="contactPhone" name="contactPhone"><br><br>          <label for="projectState">项目状态:</label><br>         <input type="text" id="projectState" name="projectState"><br><br>          <label for="contactWebSite">公司网站:</label><br>         <input type="url" id="contactWebSite" name="contactWebSite"><br><br>          <label for="projectMessage">项目描述:</label><br>         <textarea id="projectMessage" name="projectMessage" rows="5"></textarea><br><br>          <input type="submit" value="提交线索到 Monday.com">     </form> </body> </html>

5. 注意事项与最佳实践

列ID匹配： 这是最常见的错误源。请务必核对PHP代码中的列ID与Monday.com看板中的实际列ID完全一致。列ID通常是类似 text__1、status、date4 这样的字符串。
数据类型处理： 不同类型的Monday.com列需要不同的JSON格式。例如，URL列的格式可能与文本列不同。如果遇到特定列类型无法写入的问题，请查阅Monday.com的官方API文档以获取正确的JSON结构。
错误处理： 生产环境中，应添加更健壮的错误处理机制。例如，检查API响应中的 errors 字段，捕获cURL错误，并记录详细日志。
安全性： API密钥是敏感信息，不应直接暴露在客户端代码中。在服务器端（如PHP）处理API请求是最佳实践。
动态Board ID和Group ID： 对于复杂的应用，您可能需要根据用户输入或业务逻辑动态选择看板ID或组ID。可以通过API查询获取这些ID，而不是硬编码。
API速率限制： Monday.com API有速率限制。在进行大量请求时，请注意API响应中的速率限制信息，并考虑实现重试逻辑和退避策略。
使用环境变量： 在生产环境中，API密钥等敏感信息最好通过环境变量来管理，而不是直接写入 config.php，以提高安全性。

6. 总结

通过本教程，您应该已经掌握了如何使用PHP cURL连接Monday.com API，并成功创建新的线索或交易项目。这种集成能力为自动化数据录入、表单提交处理以及与其他业务系统的数据同步提供了强大的基础。您可以根据自己的具体需求，进一步探索Monday.com API提供的其他功能，如更新项目、查询数据、管理用户等，从而构建更复杂的自动化工作流。

以上就是使用PHP cURL连接Monday.com API创建线索或交易的详细内容，更多请关注php html js json 操作系统编码 app curl ai 环境变量配置文件邮箱 html表单 php graphql json html 数据类型 date cURL 字符串接口 column 自动化