本教程详细阐述了将python requests.post请求转换为php时常遇到的陷阱，特别是当POST请求体中包含json字符串作为表单字段值时。通过FedEx包裹追踪API的实际案例，我们演示了如何正确构造PHP请求，以避免“UNSUPPORTED.ACTION”错误，确保数据以application/x-www-form-urlencoded格式发送，同时嵌套的JSON数据能被正确处理。
跨语言api调用的挑战与Python requests机制解析
在现代软件开发中，不同语言之间进行API调用转换是常见的任务。Python的requests库因其简洁易用而广受欢迎，但在将其请求逻辑移植到PHP等其他语言时，尤其是在处理POST请求体格式方面，开发者常会遇到一些细微但关键的差异。
以FedEx包裹追踪API为例，原始python脚本使用requests.post方法，并通过data参数传递请求体。理解requests库中data和json参数的区别至关重要：
- requests.post(url, data=…)：当data参数是一个字典时，requests库会默认将其编码为application/x-www-form-urlencoded格式的表单数据发送。如果字典中的某个值本身是一个JSON字符串（例如通过json.dumps()生成），它将作为该表单字段的值被发送。
- requests.post(url, json=…)：当使用json参数时，requests库会将整个传入的对象序列化为JSON字符串，并设置Content-Type: application/json头，将其作为请求体发送。
在提供的Python脚本中，关键部分是：
data = requests.post('https://www.fedex.com/trackingCal/track', data={ 'data': json.dumps({ # 注意这里，'data'字段的值是一个JSON字符串 'TrackPackagesRequest': { # ... 追踪信息 ... } }), 'action': 'trackpackages', 'locale': 'en_US', 'format': 'json', 'version': 99 }).json()
这里，Python脚本实际上发送的是一个application/x-www-form-urlencoded格式的请求，其中包含多个字段，如action、locale、format、version，以及一个名为data的字段，其值是一个经过JSON编码的字符串。
立即学习“PHP免费学习笔记（深入）”；
PHP请求的常见误区与“UNSUPPORTED.ACTION”错误
在将上述Python逻辑转换为PHP时，一个常见的错误是误以为整个POST请求体都应该以JSON格式发送。开发者可能会尝试将包含所有参数的PHP数组整体进行json_encode，并设置Content-Type: application/json头。
以下是尝试转换时可能出现的错误PHP代码示例：
<?php // ... 引入autoload.php ... $tracking_number = '123456789'; $url = 'https://www.fedex.com/trackingCal/track'; $headers = ['Content-Type' => 'application/json']; // 错误的头部设置 $requestData = [ // 整个请求体被构建为一个PHP数组 'data' => [ // 这里的'data'字段值仍然是PHP数组 'TrackPackagesRequest' => [ 'appType' => 'wtrk', 'uniqueKey' => '', 'processingParameters' => [ 'anonymousTransaction' => true, 'clientId' => 'WTRK', 'returnDetailedErrors' => true, 'returnLocalizedDateTime' => false ], 'trackingInfoList' => [ [ 'trackNumberInfo' => [ 'trackingNumber' => $tracking_number, 'trackingQualifier' => '', 'trackingCarrier' => '' ] ] ] ] ], 'action' => 'trackpackages', 'locale' => 'en_US', 'format' => 'json', 'version' => 99 ]; // 整个requestData数组被json_encode，并作为请求体发送 $response = Requests::post($url, $headers, json_encode($requestData)); print_r($response);
当执行这段PHP代码时，FedEx API会返回以下错误：
{ "CALError": { "code":"UNSUPPORTED.ACTION", "message":" is not a supported action", "rootCause":null } }
这个错误表明API没有识别出所请求的“action”。根本原因在于，php脚本发送的请求体是application/json格式，而API期望的是application/x-www-form-urlencoded格式，并且其中一个表单字段（data）的值是JSON字符串。API无法正确解析整个JSON体来找到预期的表单字段。
正确的PHP请求构造方法
解决此问题的关键在于精确模拟Python脚本发送的请求格式。这意味着：
- 整个POST请求体应该以application/x-www-form-urlencoded格式发送。
- 其中一个名为data的表单字段，其值必须是一个JSON编码的字符串。
使用PHP Requests库（或直接使用cURL），当Requests::post方法的第三个参数是一个关联数组时，它会默认将其编码为application/x-www-form-urlencoded格式。因此，我们只需要对数组中data键的值进行json_encode。
以下是修正后的PHP代码示例：
<?php $dir = __DIR__; include $dir .'/vendor/autoload.php'; // 确保composer autoload已配置 $tracking_number = '123456789'; // 替换为实际的追踪号码 $url = 'https://www.fedex.com/trackingCal/track'; // 不需要设置Content-Type: application/json 头，因为我们发送的是form-urlencoded数据 $headers = []; $data = [ // 关键：只有'data'字段的值需要被json_encode "data" => json_encode([ "TrackPackagesRequest" => [ "appType" => "wtrk", "uniqueKey" => "", "processingParameters" => [ "anonymousTransaction" => true, "clientId" => "WTRK", "returnDetailedErrors" => true, "returnLocalizedDateTime" => false ], "trackingInfoList" => [[ "trackNumberInfo" => [ "trackingNumber" => $tracking_number, "trackingQualifier" => "", "trackingCarrier" => "" ] ]] ] ]), "action" => "trackpackages", "locale" => "en_US", "format" => "json", "version" => 99 ]; // Requests::post 方法会默认将$data数组编码为application/x-www-form-urlencoded $response = Requests::post($url, $headers, $data); // 检查响应状态码 if ($response->status_code === 200) { // 解析JSON响应 $responseData = json_decode($response->body, true); if (isset($responseData['TrackPackagesResponse']['packageList'][0])) { $packageInfo = $responseData['TrackPackagesResponse']['packageList'][0]; $fedex_status = $packageInfo['keyStatus']; $fedex_details = $packageInfo['statusWithDetails']; $delivery_date = $packageInfo['displayActDeliveryDt']; $delivery_time = $packageInfo['displayActDeliveryTm']; echo "FedEx 状态: " . $fedex_status . PHP_EOL; echo "详细信息: " . $fedex_details . PHP_EOL; echo "预计/实际投递日期: " . $delivery_date . PHP_EOL; echo "预计/实际投递时间: " . $delivery_time . PHP_EOL; } else { echo "未找到包裹信息或响应结构不符。" . PHP_EOL; } } else { echo "请求失败，HTTP状态码: " . $response->status_code . PHP_EOL; echo "响应体: " . $response->body . PHP_EOL; }
这段代码将$data数组直接传递给Requests::post方法。Requests库会识别这是一个关联数组，并自动将其编码为application/x-www-form-urlencoded格式，同时将data键对应的值（一个JSON字符串）作为表单字段值发送。这样就完美匹配了FedEx API的期望格式。
处理API响应
成功发送请求后，API会返回一个JSON格式的响应。在PHP中，可以使用json_decode()函数将其转换为PHP数组或对象进行处理：
$responseData = json_decode($response->body, true); // true表示返回关联数组 // 提取所需信息 $fedex_status = $responseData['TrackPackagesResponse']['packageList'][0]['keyStatus']; $fedex_details = $responseData['TrackPackagesResponse']['packageList'][0]['statusWithDetails']; $delivery_date = $responseData['TrackPackagesResponse']['packageList'][0]['displayActDeliveryDt']; $delivery_time = $responseData['TrackPackagesResponse']['packageList'][0]['displayActDeliveryTm'];
注意事项与最佳实践
在进行API集成时，除了正确构造请求外，还需要考虑以下几点：
- API稳定性： 外部API可能会更新或改变其请求/响应格式。定期测试您的集成代码是必要的。
- 错误处理： 始终检查HTTP响应状态码（例如200表示成功）和API返回的错误信息（如CALError）。这有助于诊断问题。
- 安全性： 如果API需要认证（尽管FedEx此公共接口不需要），请妥善管理API密钥，避免硬编码或将其暴露在公共仓库中。
- 依赖管理： 使用Composer管理PHP库（如requests），确保依赖项的正确安装和版本控制。
- 日志记录： 在生产环境中，记录API请求和响应的详细信息对于调试和监控至关重要。
- 性能优化： 对于高频调用，考虑缓存API响应或使用异步请求。
总结
将Python的requests库请求逻辑转换为PHP时，核心在于理解目标API期望的请求体格式。Python requests.post(url, data=…)默认发送application/x-www-form-urlencoded，即使data字典中的某个值是JSON字符串，它也会被作为普通表单字段值处理。在PHP中，通过对特定字段进行json_encode，并让HTTP客户端库（如Requests）自动处理表单编码，可以有效地模拟这种行为。避免将整个请求体不加区分地编码为JSON并设置错误的Content-Type头，是成功进行跨语言API集成的关键。
评论（已关闭）
评论已关闭