本文旨在解决在使用php客户端库调用Google My Business Business Information API获取商家位置列表时，因readMask参数配置不当导致的400错误。核心问题在于readMask必须指定location资源中有效的字段，而非其他不相关的属性。文章将提供正确的readMask用法示例，帮助开发者顺利迁移至新版API并高效获取所需商家数据。
理解Google My Business Business Information API (v1) 与 readMask
随着google my business api从v4版本迁移至最新的business information api (v1)，开发者在获取商家位置信息时可能会遇到新的挑战。其中一个常见问题是关于readmask参数的正确使用。readmask是一个关键字段，它允许api调用者指定只返回资源中需要的部分字段，从而优化数据传输效率和减少不必要的数据量。
INVALID_ARGUMENT 错误及其根源
在使用Google_Service_MyBusinessBusinessInformation服务获取商家位置列表时，如果readMask参数被错误地设置为user.display_name或photo等不属于Location资源本身的字段，API会返回http 400 Bad Request错误，并附带INVALID_ARGUMENT和Invalid field mask provided的详细信息。
{ "error": { "code": 400, "message": "Request contains an invalid argument.", "status": "INVALID_ARGUMENT", "details": [ { "@type": "type.googleapis.com/google.rpc.BadRequest", "fieldViolations": [ { "field": "read_mask", "description": "Invalid field mask provided" } ] } ] } }
核心原因在于，readMask参数是针对API返回的Location资源对象的属性进行过滤的。它不能用于请求与Location资源本身不直接关联的其他实体（如用户或图片，除非图片是Location资源的一个直接属性，且通过特定字段名访问）。例如，user.display_name可能是与某个用户账户关联的属性，而photo可能指的是独立的照片资源，它们都不是Location资源顶层直接可用的字段。
Location资源 readMask 的正确用法
要正确使用readMask，必须确保其中包含的字段名是Location资源中定义的有效属性。这些属性包括但不限于：
- name：资源的完整名称（例如 accounts/ACCOUNT_ID/locations/LOCATION_ID）。
- title：商家名称。
- storeCode：商家代码。
- websiteUri：网站URL。
- address：商家地址信息。
- latlng：经纬度坐标。
- phoneNumbers：电话号码信息。
- regularHours：常规营业时间。
- openInfo：营业状态信息。
- categories：商家类别。
- serviceArea：服务区域。
开发者应查阅Google My Business Business Information API的官方文档中关于Location资源字段的详细说明，以获取完整的有效字段列表：https://www.php.cn/link/dc8ea2d055557e14585d74fc6c1033b2。
立即学习“PHP免费学习笔记（深入）”；
PHP 代码示例：正确获取商家位置列表
以下是一个修正后的PHP代码示例，演示了如何正确配置readMask参数以获取商家位置列表：
<?php require_once 'vendor/autoload.php'; // 确保你的composer autoload文件已加载 // 假设 $client 已经是一个经过认证的 Google_Client 实例 // 并且已经设置了正确的Scopes，例如 Google_Service_MyBusinessBusinessInformation::MYBUSINESS_BUSINESSINFORMATION // 示例： // $client = new Google_Client(); // $client->setAuthConfig('path/to/your/credentials.json'); // $client->setScopes([Google_Service_MyBusinessBusinessInformation::MYBUSINESS_BUSINESSINFORMATION, Google_Service_MyBusinessAccountManagement::MYBUSINESS_ACCOUNTMANAGEMENT]); // $client->setAccessType('offline'); // 如果需要刷新令牌 try { // 1. 获取账户信息 $my_business_account = new Google_Service_MyBusinessAccountManagement($client); $list_accounts_response = $my_business_account->accounts->listAccounts(); if (empty($list_accounts_response->getAccounts())) { echo "未找到任何Google My Business账户。n"; exit; } // 通常选择第一个账户，或者根据业务逻辑选择特定账户 $account = $list_accounts_response->getAccounts()[0]; echo "正在处理账户: " . $account->getName() . "n"; // 2. 初始化 MyBusinessBusinessInformation 服务 $mybusinessService = new Google_Service_MyBusinessBusinessInformation($client); $locations_service = $mybusinessService->accounts_locations; // 3. 定义查询参数，重点是正确的 readMask $queryParams = [ "pageSize" => 10, // 修正：readMask 必须指定 Location 资源本身的有效字段 // 这里请求了名称、标题、商家代码、网站URI、地址和电话号码 'readMask' => "name,title,storeCode,websiteUri,address,phoneNumbers" ]; // 4. 调用 API 获取位置列表 $locationsListResponse = $locations_service->listAccountsLocations($account->name, $queryParams); if (empty($locationsListResponse->getLocations())) { echo "该账户下未找到任何商家位置。n"; exit; } echo "成功获取商家位置列表：n"; foreach ($locationsListResponse->getLocations() as $location) { echo " - 位置名称 (Resource Name): " . $location->getName() . "n"; echo " - 商家标题 (Title): " . $location->getTitle() . "n"; if ($location->getStoreCode()) { echo " - 商家代码 (Store Code): " . $location->getStoreCode() . "n"; } if ($location->getWebsiteUri()) { echo " - 网站 (Website): " . $location->getWebsiteUri() . "n"; } // 地址字段是一个复杂对象，需要进一步解析 if ($location->getAddress()) { $postalAddress = $location->getAddress()->getPostalAddress(); if ($postalAddress) { echo " - 地址 (Address): " . implode(", ", $postalAddress->getAddressLines()) . ", " . $postalAddress->getLocality() . "n"; } } // 电话号码字段也是一个复杂对象 if ($location->getPhoneNumbers() && $location->getPhoneNumbers()->getPrimaryPhone()) { echo " - 主要电话 (Primary Phone): " . $location->getPhoneNumbers()->getPrimaryPhone() . "n"; } echo "---n"; } // 处理分页，如果有更多结果 $nextPageToken = $locationsListResponse->getNextPageToken(); if ($nextPageToken) { echo "还有更多结果，可以通过 nextPageToken 继续获取。n"; // 示例：获取下一页 // $queryParams['pageToken'] = $nextPageToken; // $nextLocationsListResponse = $locations_service->listAccountsLocations($account->name, $queryParams); } } catch (GoogleServiceException $e) { echo "API 调用出错: " . $e->getMessage() . "n"; echo "错误详情: " . (isset($e->getErrors()[0]['message']) ? $e->getErrors()[0]['message'] : '未知错误') . "n"; // 更多错误处理，例如根据错误码进行不同处理 } catch (Exception $e) { echo "发生未知错误: " . $e->getMessage() . "n"; } ?>
注意事项
- 字段准确性：始终参考Google My Business Business Information API的官方Location资源文档，以获取最新和最准确的有效readMask字段列表。API可能会更新，旧的字段可能被废弃，新的字段可能被添加。
- 错误处理：在实际应用中，务必实现健壮的错误处理机制，捕获GoogleServiceException。通过检查错误码和错误详情，可以更精确地诊断和解决问题。
- API权限与范围：确保你的Google Cloud项目已启用Google My Business Business Information API，并且OAuth 2.0客户端凭据具有访问所需资源的正确权限（Scope），例如https://www.googleapis.com/auth/mybusiness.businessinformation和https://www.googleapis.com/auth/mybusiness.accountmanagement。
- 分页处理：listAccountsLocations方法支持分页。当结果数量超过pageSize时，API会返回nextPageToken。开发者需要循环调用API，并在后续请求中带上pageToken参数以获取所有数据。
- 性能优化：readMask的目的是只请求你真正需要的数据。避免请求不必要的字段可以减少API响应大小，从而提高应用程序的性能和响应速度。
总结
通过本文，我们详细探讨了Google My Business Business Information API中readMask参数的正确使用方法。核心要点是：readMask中的字段必须是目标资源（本例中为Location）的有效属性。遵循这一原则，并结合官方文档进行字段验证，将有效避免INVALID_ARGUMENT错误，确保开发者能够顺利、高效地从Google My Business获取所需的商家位置数据。
