幂等的 Quickbooks 在线集成 - RequestID 来救援！

欲了解更多信息，请访问 developer.intuit.com。

与 Quickbooks Online 集成提供了许多功能，并支持许多不同的应用程序架构。与 Quickbooks Online 集成的其中一个重要功能是使用 RequestID 参数。此参数唯一标识从您的应用程序发送到 Quickbooks 服务的 HTTP 请求。RequestID 值还使您的应用程序能够在您的应用程序需要重新发送操作到 Quickbooks Online 服务时，关联请求和响应。在本文中，我们将演示为什么 RequestID 参数很重要，以及如何在 您的应用程序 中实现它。

我们强烈建议所有开发人员在每次向 Quickbooks Online 发送 API 请求 时都传递一个唯一的 RequestID 值。通过执行此步骤，可以保证幂等性，因为 Quickbooks Online 可以识别该操作是否已先前收到。如果先前提交了 RequestID，则原始请求将返回到您的应用程序，而不会更改数据的状态。此外，在服务中断的情况下，可以在 Quickbooks 服务和您的应用程序中防止数据重复。

RequestID 演练示例

让我们逐步了解如何将 RequestID 添加到应用程序与 Quickbooks Online 的集成中，并回顾从将此参数添加到我们的服务调用中获得的优势。

在对 Quickbooks 服务的新请求中，我们的应用程序应传输一个新的、唯一的 RequestID，作为名为 `requestid` 的查询字符串参数。如果 Quickbooks 服务收到另一个具有相同 RequestID 的请求，则服务不会再次执行该操作或返回错误，而是发送与原始请求相同的响应。在进行服务调用时，对指定 RequestID 有一些要求

• 您的应用程序指定为查询字符串参数的 RequestID 对于给定公司的所有请求必须是唯一的。
• RequestID 的最大长度为 50 个字符，适用于所有操作，批量操作除外。
• 对于批量操作，RequestID 最多支持 36 个字符。对于每个批量操作 ID，当也指定了 RequestID 时，只允许 10 个字符。
• 为避免重复的 ID，应用程序负责为每个请求生成一个唯一的 ID。我们建议您的应用程序使用类似 java.util.UUID 或 .NET System.GUID 的库生成 requestid 值。
• 我们建议您将 RequestID 记录到持久数据存储中，例如关系数据库或日志文件。跟踪此值将使您能够在检测到操作错误时重新执行相同的请求。

以下场景展示了应用程序如何在创建操作中使用 RequestID

1. 应用程序发送一个创建发票的请求，指定 RequestID 4957：baseURL/company/1234/invoice?RequestID=4957
2. 服务处理创建发票的请求。
3. 发生错误，应用程序与其服务的连接中断，并且没有收到响应。
4. 应用程序再次发送创建发票的请求，指定与步骤 1 中相同的 content 和 requestid。
5. Quickbooks 服务确定 RequestID 之前已被发送过。Quickbooks 决定不再第二次处理该请求，并发送与步骤 2 相同的响应。如果应用程序未指定 RequestID，则服务将创建一个具有新实体 ID 的重复发票。
6. 应用程序接收响应并验证它是否包含错误。

使用 RequestID 的优势

以下两个序列图描述了使用 RequestID 的优势。

摘要

在大型系统集成中，系统之间的服务调用保持幂等性非常重要 – 也就是说，具有相同输入的相同操作会返回相同的输出。为了帮助确保这些操作在 Quickbooks 中不会执行多次，我们强烈建议您在将来与 Quickbooks Online 服务的所有交互中实现 RequestID 参数。