QuickBooks Online API 查询中正确使用日期变量的完整指南-php教程-PHP中文网

QuickBooks Online API 查询中正确使用日期变量的完整指南

在 QuickBooks Online (QBO) API 查询中，若需动态传入 MetaData.LastUpdatedTime 的日期条件，必须将 PHP 变量用单引号包裹并拼接到双引号 SQL 字符串中（如 ' . $qboLastUpdate . '），否则 QBO 服务端无法识别该值为合法 ISO 8601 时间字面量，导致查询返回空结果。

在 quickbooks online (qbo) api 查询中，若需动态传入 `metadata.lastupdatedtime` 的日期条件，必须将 php 变量用单引号包裹并拼接到双引号 sql 字符串中（如 `' . $qbolastupdate . '`），否则 qbo 服务端无法识别该值为合法 iso 8601 时间字面量，导致查询返回空结果。

QuickBooks Online 的 REST API 对时间条件（如 MetaData.LastUpdatedTime > '2022-01-01'）有严格格式要求：右侧必须是带单引号的 ISO 8601 日期/时间字符串（例如 '2022-01-01' 或更精确的 '2022-01-01T00:00:00-08:00'）。当使用 PHP SDK 的 $dataService->Query() 方法时，整个查询语句是一个纯字符串，QBO 不解析 PHP 变量——它只接收最终拼接完成的、语法合规的 Query String。

常见错误写法（❌ 导致无结果）：

// 错误：变量未加单引号 → 生成 "WHERE MetaData.LastUpdatedTime > 2022-01-01"（非法）
$qboTableExtract = $dataService->Query("SELECT * FROM $qboTable WHERE MetaData.LastUpdatedTime > $qboLastUpdate STARTPOSITION $i MAXRESULTS $end");

// 错误：双引号内嵌双引号未转义 → 语法错误或截断
$qboTableExtract = $dataService->Query("SELECT * FROM $qboTable WHERE MetaData.LastUpdatedTime > \"$qboLastUpdate\" ...");

✅ 正确写法（关键：显式拼接单引号）：

// 推荐：清晰、安全、符合 QBO 要求
$escapedDate = "'" . $qboLastUpdate . "'";
$qboTableExtract = $dataService->Query(
    "SELECT * FROM $qboTable " .
    "WHERE MetaData.LastUpdatedTime > $escapedDate " .
    "STARTPOSITION $i MAXRESULTS $end"
);

⚠️ 重要注意事项：

日期格式必须为 YYYY-MM-DD 或 YYYY-MM-DDTHH:MM:SS±HH:MM：从 MySQL 读取的 DATE 类型字段（如 '2022-01-01'）可直接使用；若字段为 DATETIME 或 TIMESTAMP，建议统一格式化为 ISO 8601：
```
$qboLastUpdate = date('Y-m-d\TH:i:sP', strtotime($dbRow['last_update'])); // 输出如 '2022-01-01T00:00:00-08:00'
```
避免 SQL 注入风险：虽然 QBO 查询不支持参数化（无预处理语句），但务必确保 $qboLastUpdate 来源可信。建议从数据库读取后做白名单校验：
```
if (!preg_match('/^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}:\d{2}(?:[+-]\d{2}:\d{2}|Z)?)?$/', $qboLastUpdate)) {
    throw new InvalidArgumentException('Invalid QBO date format');
}
```
时区敏感性：MetaData.LastUpdatedTime 始终以 UTC 返回。若你的 $qboLastUpdate 是本地时区时间，请先转换为 UTC 再拼接，否则可能漏数据。

总结：QBO API 的查询字符串是“所见即所得”的文本协议，PHP 变量不会被自动加引号。唯一可靠方式是手动拼接单引号——这是与传统 SQL 预处理的本质区别。掌握此模式，即可稳定实现增量同步、分页拉取等生产级集成场景。