通过 PHP 连接 Monday.com API：自动化创建销售线索与交易-php教程-PHP中文网

通过 PHP 连接 Monday.com API：自动化创建销售线索与交易

本文提供了一份详细的 PHP 教程，指导您如何利用 Monday.com API 自动化创建销售线索或交易。内容涵盖了 API 认证、GraphQL 突变构建、表单数据到 Monday.com 列的映射，以及如何通过 file_get_contents 发送 API 请求。通过具体的代码示例，您将学会配置 API 密钥、定义看板 ID 和列 ID，并实现动态添加新条目的功能，有效提升业务流程效率。

1. Monday.com API 基础与认证

monday.com 提供了一套强大的 graphql api，允许开发者以编程方式与平台进行交互，例如创建、读取、更新和删除看板条目。所有的 api 请求都需要通过认证来确保安全。

API 认证方式： Monday.com API 主要通过个人访问令牌（Personal Access Token）进行认证。这个令牌需要在请求头中以 Authorization: [YOUR_API_KEY] 的形式发送。

GraphQL 概述： Monday.com API 使用 GraphQL 查询语言。这意味着所有的操作（查询数据、创建/更新数据）都通过单个端点进行，并使用 query（读取数据）或 mutation（修改数据）来定义操作类型。

2. 环境准备与配置

在开始之前，我们需要设置一个配置文件来存储 API 密钥、API 端点和看板 ID 等敏感信息，以便于管理和维护。

config.php 文件设置：

创建一个名为 config.php 的文件，并包含以下内容。请务必将 [YOUR API KEY] 替换为您真实的 Monday.com API 密钥。

<?php
// config.php

// 您的 Monday.com API 密钥
$token = '[YOUR API KEY]'; 

// Monday.com API 端点 URL
$apiUrl = 'https://api.monday.com/v2';

// 请求头，包含内容类型和授权令牌
$headers = ['Content-Type: application/json', 'Authorization: ' . $token];

// 定义您要操作的看板及其对应的 ID
// 替换为您的实际看板名称和 ID
$boards = array(
  "boardName1" => 1918282734, // 示例看板ID
  "boardName2" => 1987654321,
  "boardName3" => 4567123890,
  "testBoard"  => 6376637288  // 用于测试的看板ID
);
?>

登录后复制

注意事项：

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

API 密钥安全： 绝不要将您的 API 密钥直接暴露在客户端代码或版本控制中。在生产环境中，应考虑使用环境变量或其他更安全的密钥管理方案。
看板 ID： 您可以在 Monday.com 看板的 URL 中找到其 ID（例如 https://monday.com/boards/1234567890/，其中 1234567890 就是看板 ID）。

3. PHP 实现：创建 Monday.com 条目

本节将详细介绍如何编写 PHP 代码来接收表单数据，构建 GraphQL 突变，并将其发送到 Monday.com API 以创建新的销售线索或交易条目。

3.1 接收表单数据

假设您有一个 HTML 表单用于收集销售线索信息。当表单通过 POST 方法提交时，PHP 脚本将接收这些数据。

<?php
// 包含配置文件
include('config.php');

if ($_SERVER["REQUEST_METHOD"] == "POST") {
    // 从表单中获取输入值
    $companyName    = $_POST['companyName'];
    $firstName      = $_POST['firstName'];
    $lastName       = $_POST['lastName'];
    $contactEmail   = $_POST['contactEmail'];
    $contactPhone   = $_POST['contactPhone'];
    $projectState   = $_POST['projectState'];
    $contactWebSite = $_POST['contactWebSite']; // 尽管示例代码未完全使用，但保留
    $projectMessage = $_POST['projectMessage'];

    // 从配置中获取目标看板ID
    // 确保 'testBoard' 对应 config.php 中定义的实际看板ID
    $boardId = $boards['testBoard']; 

    // 获取当前日期，用于日期列
    $todaysDate = date("Y-m-d");

    // ... 后续构建 GraphQL 突变和发送请求的代码
}
?>

登录后复制

3.2 构建 GraphQL 突变 (create_item)

易企秀

易企秀，一体化创意设计营销平台。超100万模板1键套用3分钟制作，随时随地完成创意设计营销。

查看详情

要创建一个新的条目，我们将使用 Monday.com API 提供的 create_item 突变。这个突变需要 board_id（看板 ID）、item_name（条目名称）和 column_values（列值）作为参数。

column_values 是一个 JSON 字符串，它将表单数据映射到 Monday.com 看板上的各个列。每个列值都需要根据其类型进行格式化。

    // GraphQL 突变字符串
    // $itemName 和 $columnVals 是变量，将在 vars 数组中定义
    $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([
            // 状态列：'status' 是列的 ID，'label' 是状态的文本值
            'status'        => [
                'label' => 'New Lead' // 例如：设置为“新线索”
             ], 
            // 日期列：'date4' 是列的 ID，'date' 是日期值
            'date4'         => [
                'date' => $todaysDate
            ],
            // 文本列：'text__1' 是列的 ID，直接传入文本值
            'text__1'       => $firstName,
            'text5__1'      => $lastName,
            // 邮箱列：'email__1' 是列的 ID，需要 'email' 和 'text' 字段
            'email__1'      => [
                'email' => $contactEmail,
                'text'  => $contactEmail // 文本显示值
            ],
            // 电话列：'phone__1' 是列的 ID，需要 'phone' 和 'countryShortName' 字段
            'phone__1'      => [
                'phone'            => $contactPhone,
                'countryShortName' => 'US' // 国家代码，例如 'US' 代表美国
            ],
            // 另一个文本列
            'text7__1'      => $projectState,
            // 长文本列：'long_text4__1' 是列的 ID
            'long_text4__1' => $projectMessage
        ])
    ];

登录后复制

关键点：

列 ID (Column ID)： 示例中的 status, date4, text__1 等是 Monday.com 看板中列的唯一标识符。您需要在您的 Monday.com 看板设置中找到这些 ID。通常，可以通过点击列标题 -> 设置 -> 更改列类型 -> 更多设置来找到。
数据类型映射： 不同类型的 Monday.com 列需要不同的 JSON 格式来设置其值。例如，状态列需要 label 字段，日期列需要 date 字段，邮箱列需要 email 和 text 字段，而普通文本列可以直接传入字符串。

4. 发送 API 请求与处理响应

在构建好 GraphQL 突变和变量后，我们需要将其作为 POST 请求发送到 Monday.com API 端点。本教程采用 file_get_contents 结合 stream_context_create 的方式来发送 HTTP 请求。

    // 构造请求数据
    $requestPayload = json_encode([
        'query'     => $query,
        'variables' => $vars
    ]);

    // 使用 stream_context_create 发送 POST 请求
    $data = @file_get_contents($apiUrl, false, stream_context_create([
        'http' => [
            'method'  => 'POST',
            'header'  => $headers, // 使用 config.php 中定义的请求头
            'content' => $requestPayload,
        ]
    ]));

    // 解析 API 响应
    $responseContent = json_decode($data, true);

    // 输出响应内容，用于调试或进一步处理
    echo json_encode($responseContent);
}
?>

登录后复制

5. 完整代码示例

以下是整合了 config.php 和主处理逻辑的完整代码示例。

config.php

<?php
// config.php

// 您的 Monday.com API 密钥
$token = '[YOUR API KEY]'; 

// Monday.com API 端点 URL
$apiUrl = 'https://api.monday.com/v2';

// 请求头，包含内容类型和授权令牌
$headers = ['Content-Type: application/json', 'Authorization: ' . $token];

// 定义您要操作的看板及其对应的 ID
// 替换为您的实际看板名称和 ID
$boards = array(
  "boardName1" => 1918282734, // 示例看板ID
  "boardName2" => 1987654321,
  "boardName3" => 4567123890,
  "testBoard"  => 6376637288  // 用于测试的看板ID
);
?>

登录后复制

主处理脚本 (例如 create_lead.php)

<?php
// 包含配置文件
include('config.php');

if ($_SERVER["REQUEST_METHOD"] == "POST") {
    // 从表单中获取输入值
    // 请确保您的 HTML 表单字段名称与此处的 $_POST 键匹配
    $companyName    = $_POST['companyName'] ?? '';
    $firstName      = $_POST['firstName'] ?? '';
    $lastName       = $_POST['lastName'] ?? '';
    $contactEmail   = $_POST['contactEmail'] ?? '';
    $contactPhone   = $_POST['contactPhone'] ?? '';
    $projectState   = $_POST['projectState'] ?? '';
    $contactWebSite = $_POST['contactWebSite'] ?? ''; // 尽管示例代码未完全使用，但保留
    $projectMessage = $_POST['projectMessage'] ?? '';

    // 从配置中获取目标看板ID
    // 确保 'testBoard' 对应 config.php 中定义的实际看板ID
    $boardId = $boards['testBoard']; 

    // 获取当前日期，用于日期列
    $todaysDate = date("Y-m-d");

    // GraphQL 突变字符串
    $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([
            'status'        => [
                'label' => 'New Lead'
             ], 
            'date4'         => [
                'date' => $todaysDate
            ],
            'text__1'       => $firstName,
            'text5__1'      => $lastName,
            'email__1'      => [
                'email' => $contactEmail,
                'text'  => $contactEmail
            ],
            'phone__1'      => [
                'phone'            => $contactPhone,
                'countryShortName' => 'US' // 示例，根据需要修改
            ],
            'text7__1'      => $projectState,
            'long_text4__1' => $projectMessage
            // 如果需要添加链接列，格式类似：
            // 'link_column_id' => [
            //     'url'  => $contactWebSite,
            //     'text' => $contactWebSite
            // ]
        ])
    ];

    // 构造请求数据
    $requestPayload = json_encode([
        'query'     => $query,
        'variables' => $vars
    ]);

    // 使用 stream_context_create 发送 POST 请求
    // @ 符号用于抑制 file_get_contents 可能产生的警告
    $data = @file_get_contents($apiUrl, false, stream_context_create([
        'http' => [
            'method'  => 'POST',
            'header'  => $headers,
            'content' => $requestPayload,
        ]
    ]));

    // 解析 API 响应
    $responseContent = json_decode($data, true);

    // 输出响应内容，用于调试或进一步处理
    // 实际应用中，您可能需要检查响应是否成功并返回适当的信息给用户
    echo json_encode($responseContent);
} else {
    // 如果不是 POST 请求，可以返回错误信息或显示表单
    echo json_encode(['error' => 'Invalid request method. Please submit a POST request.']);
}
?>

登录后复制

6. 注意事项与最佳实践

列 ID 匹配： 确保代码中的列 ID（如 status, date4, text__1 等）与您的 Monday.com 看板中的实际列 ID 完全匹配。不匹配会导致数据无法正确写入。
数据类型： Monday.com 对不同类型的列有严格的数据格式要求。务必根据列类型（如状态、日期、邮箱、电话、链接、文本等）正确构建 column_values 中的 JSON 结构。例如，链接列需要 url 和 text 字段，而电话列需要 phone 和 countryShortName。
错误处理： 在实际应用中，您应该添加更健壮的错误处理机制。检查 file_get_contents 的返回值，以及 Monday.com API 响应中的 errors 字段，以便及时发现并解决问题。
file_get_contents 与 cURL： 虽然本教程使用了 file_get_contents 结合 stream_context_create 来发送 HTTP 请求，但 PHP 的 cURL 扩展是更强大、更灵活的 HTTP 客户端库，尤其适用于复杂的请求、超时控制、证书验证等场景。对于生产环境，通常推荐使用 cURL。如果您希望使用 cURL，需要进行相应的代码调整。
安全性： 除了 API 密钥的保护，还要注意对所有用户输入进行验证和清理，以防止 SQL 注入、XSS 攻击等常见的 Web 安全漏洞。
异步处理： 对于大量数据或性能敏感的场景，考虑将 API 请求放入队列进行异步处理，以避免阻塞用户界面。

总结

通过本教程，您应该已经掌握了如何使用 PHP 连接 Monday.com API，并自动化创建销售线索或交易条目的基本方法。这包括了 API 认证、GraphQL 突变的构建、数据映射以及请求的发送和响应处理。通过定制 config.php 文件和调整 column_values 的映射，您可以轻松地将此解决方案应用于不同的 Monday.com 看板和业务场景，从而有效提升工作效率和数据管理能力。

以上就是通过 PHP 连接 Monday.com API：自动化创建销售线索与交易的详细内容，更多请关注php中文网其它相关文章！