PHP 集成 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
?>

注意事项：

• 请务必将 [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. 注意事项与最佳实践

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 自动化集成，提升工作效率。