一位开发者的经验分享：如何用 Quire API 构建双向同步

最后更新：2026年7月20日

当数据同时存在于两个应用程序中时，每个操作都得做两遍，否则就会悄悄失去同步。双向同步通过让 Quire 与另一应用程序自动交换更新——依靠 webhooks——从根本上解决了这种重复录入的问题。Quire 的开放 API 正是为这种模式而设计的。

工具割裂的代价早已有据可查。根据麦肯锡关于社交经济的研究，知识型员工每周将近 20% 的时间都花在查找内部信息上，而不是真正做事。可靠的同步机制能自动消除这部分开销中的很大一块。

Google日历双向同步应用程序就是一个典型范例：Quire 的任务和 Google日历 的事件无需人工核对就能保持一致。这篇文章将带你了解如何针对任何其他应用程序的 API 构建同样的模式。

Google日历双向同步适用于 Premium 及以上的订阅等级。更多信息请参见我们的定价页面。

Quire 双向同步的组成部分

双向同步的工作流程是什么？

可以把双向同步想象成两个应用程序之间的对话。当你在 Quire 中更新一个任务时，它会把这个变更告诉另一应用程序；而当那个应用程序中有内容被更新时，它也会告诉 Quire。这样一来，你的信息无论在哪里都能保持一致。

实现步骤有哪些？

搭建你的 Quire 应用程序是第一步。你需要创建一个应用程序，以获取通过 API 访问你的 Quire 项目所需的凭据。

关于如何用 Quire API 创建自己的应用程序的详细步骤指南，请访问我们的这篇博客文章。

要实现双向同步，你需要开发一个中间层应用程序（你的应用程序），充当 Quire 与目标应用程序（例如 Google日历）之间的桥梁。可以把它想象成一名翻译：从一方获取信息，处理之后，再向另一方发出正确的指令。整体流程是这样的：Quire ↔ 你的应用程序 ↔ 其他应用程序。

如何一步步搭建？

1. 准备一个用于处理事件的应用程序

要启用双向同步，你首先需要搭建自己的服务器应用程序，作为中间层。这个应用程序负责接收来自 Quire 和另一应用程序的 webhook POST 请求。 你的服务器应该能够：

• 接受来自 Quire 和另一应用程序的传入 HTTP POST 请求（webhook 事件）。
• 解析事件负载，判断需要采取哪些操作。
• 使用各自的 API，按需更新 Quire 或另一应用程序中的数据。

你可以用任何你偏好的技术来搭建这个服务器应用程序，比如 Node.js、Python 或 Ruby。在接下来的区段中，我们将用 Node.js 演示一个简单的例子，说明如何接收和处理 webhook 事件。 请确保你的服务器可以从公网访问，这样 Quire 和另一应用程序才能把 webhook 事件发送给它。

下面是一个使用 Express 的简单 Node.js 示例：

const express = require('express');
const app = express();
app.use(express.json());

app.listen(3000, () => {
  console.log('Server is running on port 3000');
});

2. 在 Quire 中设置一个 webhook，把任务更新发送到你的应用程序

接下来，你需要在服务器中创建一个路由，用来接收来自 Quire 的 webhook 事件。

app.post('/webhook', (req, res) => {
  console.log('Received webhook event:', req.body);
  // TODO: Handle the event and update Quire or other app via API
  res.status(200).send('Event received');
});

在这个例子中，webhook 路由是 /webhook，所以完整的 URL 会是 ${your-host}/webhook。

复制这个 webhook URL，粘贴到 Quire 应用程序设置中，这样 Quire 就知道该把事件通知发送到你的应用程序的哪个地址。

此外，你还需要把你的 Quire 应用程序注册为想要同步的项目的关注者。这样才能确保你的应用程序收到相关更新的通知。

关于如何通过 Quire API 接收通知的详细步骤指南，请访问我们的这篇指南。

3. 在另一应用程序中设置一个 webhook，把它的更新发送到你的应用程序

要把另一应用程序的更新同步到 Quire，你还需要在服务器中创建一个路由，用来接收来自该应用程序的 webhook 事件。注册流程与上面 Quire 的示例类似。只需将另一应用程序配置为把事件通知发送到你的中间层应用程序的 webhook 端点，并确保你的服务器能够正确处理这些传入事件。

4. 处理传入事件，并通过各自的 API 更新 Quire 和另一应用程序中的数据

一旦你的应用程序开始接收来自 Quire 和另一应用程序的 webhook 事件，你就需要实现相应逻辑来处理这些事件，并在两个平台之间同步数据。这通常包括：

• 解析事件负载，识别发生了什么变化（例如任务被创建、更新或删除）。关于事件结构的更多细节，可以参阅 Quire API 文档 - 通知事件。
• 判断需要调用哪些 API，才能在另一应用程序中反映这些变化。
• 向 Quire 或另一应用程序发送相应的 API 请求，以保持数据同步。
• 维护 Quire 任务 ID 与你的应用程序条目 ID 之间的映射，确保更新被正确关联。

通过谨慎处理传入事件并借助 API 更新数据，你的应用程序能确保变更在双方都被准确反映，从而维持可靠的双向同步。

下面是一个使用 Node.js 和 axios 的示例：

const axios = require('axios');

app.post('/webhook', (req, res) => {
  const { type } = req.body.data;
  // Reference of activity types: 
  // https://github.com/quire-api/quire-api/blob/master/docs/activity_types.md
  switch (type) {
    case 0: //Quire task created
      onQuireTaskCreate();
      break; 
    case 1: //Quire task deleted
      onQuireTaskDelete();
      break;
  }
  res.status(200).send('Event received');
});

// Route for handling events from another app to Quire
app.post('/anotherwebhook', async (req, res) => {
  const { isCreate, id, name, projectId } = req.body;
  if (isCreate) {
    // Create a task in the Quire project
    await axios.post(`https://quire.io/api/task/${projectId}`, { name });
    // Optionally, store the mapping between your app's id and Quire's task id
  } else {
    // Retrieve the corresponding Quire task id using your mapping logic
    const taskOid = getTaskIdByAppEventId(id, projectId);
    // Delete the task from the Quire project
    await axios.delete(`https://quire.io/api/task/${taskOid}`);
  }
  res.status(200).send('Event processed successfully');
});

这个例子演示了如何处理来自另一应用程序的创建和删除事件，并将其与 Quire 同步。请务必实现完善的错误处理，并维护好 ID 映射，以确保同步可靠。

有哪些关键注意事项？

两条安全规则涵盖了几乎每个初次实现都会踩到的坑：

• 追踪每次变更的来源。为你的同步流程触发的更新打上标签，当它们以 webhook 形式回弹时予以忽略。如果不这样做，Quire 推送到另一应用程序，另一应用程序又触发一个 webhook 回传，你的服务器再次推送，循环就会永远持续下去。
• 保持数据格式一致。在 Quire 中含义明确的字段（例如 Markdown 格式的描述），在变成日历事件描述、纯文本工单备注或其他目标格式之前，可能需要显式转换。

下一步该做什么？

开放 API 加上 webhooks，能把 Quire 和你的其他工具变成一个统一的真实数据源，而不是两个互相打架的数据源。先从最小可行的同步做起（一种事件类型、一个方向），验证整个流程能端到端正常运行之后，再逐步扩展。

相关文章：通过 Quire API 集成外部工具——以 n8n 为例——如果你更想从无代码自动化工具入手，而不是自建服务器，这是一个可参考的实例。

常见问题

Quire 与其他应用程序之间的双向同步是什么？

一种双向连接，更新可以双向流动：Quire 中的变更推送到另一应用程序，那里的变更也会推送回 Quire。Google日历双向同步应用程序就是一个实际运行的例子。

要用 Quire API 构建双向同步，我需要准备什么？

一个带有 API 凭据的 Quire 应用程序、一台可从公网访问、能接收 webhooks 的中间层服务器，以及一套能在两个 API 之间转换事件的逻辑。任何后端语言都可以胜任。

中间层应用程序扮演什么角色？

它充当 Quire 与另一项服务之间的翻译官，接收 webhook 事件，决定要调用哪些 API，并维护 Quire 任务 ID 与另一应用程序条目 ID 之间的映射关系。

如何防止无限同步循环？

追踪每次变更的来源，忽略由你自己的同步流程触发的更新。如果没有这道保险，每次更新都会在两个应用程序之间来回反弹，永无止境。

Google日历 双向同步需要哪个 Quire 订阅方案？

Premium 及以上等级。可以在定价页面查看当前的等级限制。