本文旨在解决在使用 Google My Business Business Information API 的 accounts.locations.list 方法时，因 readMask 参数不正确导致 INVALID_ARGUMENT 错误的常见问题。我们将深入分析错误原因，明确指出 readMask 必须指定 Location 资源本身的有效属性，而非其他关联实体字段。通过提供正确的参数使用方法和示例代码，帮助开发者顺利获取所需的商家位置信息，避免不必要的api调用失败。
随着 google my business api 旧版本的逐步弃用，开发者需要迁移到新的 api 服务，例如 google_service_mybusinessbusinessinformation 来管理商家位置信息。在进行位置列表查询时，readmask 参数是一个关键的字段，它允许开发者指定希望在响应中返回的特定字段，从而优化数据传输和处理效率。然而，不正确的 readmask 值常常导致 http 400 invalid_argument 错误。
诊断 readMask 错误：INVALID_ARGUMENT
当您尝试使用 Google_Service_MyBusinessBusinessInformation 服务的 accounts.locations.list 方法，并传入一个无效的 readMask 时，API 会返回一个典型的 GoogleServiceException #400 错误，其详细信息如下：
{ "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" } ] } ] } }
这个错误明确指出 read_mask 字段存在问题，即提供了“无效的字段掩码”。问题通常在于 readMask 中包含了不属于 Location 资源本身的属性，或者属性名称拼写错误。例如，尝试获取 user.display_name 这样的字段，它并非 Location 资源的标准属性。
核心问题：readMask 参数的正确使用
readMask 参数的作用是告诉 API 您需要响应中包含哪些特定的字段。对于 accounts.locations.list 方法，readMask 中的字段必须是 Location 资源（Google_Service_MyBusinessBusinessInformation_Location 对象）的有效属性。这意味着您不能随意指定任何与位置相关的字段，而必须参照 Google My Business Business Information API v1 文档中 Location 资源的定义。
常见的错误是将其他服务或关联实体（如用户账户）的字段混入 Location 的 readMask 中。例如，user.display_name 显然不属于 Location 资源，因此会导致 INVALID_ARGUMENT 错误。即使是 photo 这样的字段，虽然 Location 资源中包含照片信息，但其具体的引用方式也需符合API规范，通常是直接指定 photos 字段以获取照片列表或相关元数据。
有效的 Location 资源属性示例包括：
- name：位置的资源名称。
- title：商家名称。
- websiteUri：商家网站的URI。
- address：商家地址。
- latlng：经纬度。
- primaryCategory：主要业务类别。
- phoneNumbers：电话号码。
- openInfo：营业状态信息。
- photos：照片信息（如果需要获取照片详情，可能需要进一步的API调用或特定的字段组合）。
- metadata：元数据。
- storeCode：商家自定义的店铺代码。
请务必查阅官方文档： Google My Business Business Information API v1 Location 资源： https://www.php.cn/link/dc8ea2d055557e14585d74fc6c1033b2
解决方案与示例代码
解决 readMask 错误的关键在于确保 readMask 中只包含 Location 资源中定义的有效属性。以下是修正后的 php 代码示例，展示了如何正确构造 readMask：
<?php // 假设 $client 已经是一个经过认证的 Google_Client 实例 // 并且已经包含了 Google My Business API 相关的服务类 // 1. 初始化 My Business Account Management 服务以获取账户信息 $my_business_account = new Google_Service_MyBusinessAccountManagement($client); $list_accounts_response = $my_business_account->accounts->listAccounts(); // 确保至少有一个账户 if (empty($list_accounts_response)) { die("No Google My Business accounts found."); } // 获取第一个账户的名称，通常用于后续API调用 $account = $list_accounts_response[0]; $accountName = $account->name; // 例如：accounts/1234567890 // 2. 初始化 My Business Business Information 服务 $mybusinessService = new Google_Service_MyBusinessBusinessInformation($client); $locationsService = $mybusinessService->accounts_locations; // 3. 定义正确的 queryParams，特别是 readMask // readMask 必须包含 Location 资源中定义的有效字段 $queryParams = [ "pageSize" => 10, // 正确的 readMask 示例：只请求 Location 资源中的 'name', 'title' 和 'websiteUri' 字段 'readMask' => "name,title,websiteUri,address,primaryCategory,phoneNumbers" // 如果需要照片信息，通常直接指定 'photos' 字段，但获取详细照片URL可能需要额外的API调用或在photos字段中包含子字段 // 'readMask' => "name,title,photos" // 示例：请求名称、标题和照片信息 ]; try { // 4. 调用 listAccountsLocations 方法获取位置列表 $locationsList = $locationsService->listAccountsLocations($accountName, $queryParams); // 遍历并打印获取到的位置信息 if ($locationsList->getLocations()) { echo "Successfully retrieved locations:n"; foreach ($locationsList->getLocations() as $location) { echo " Location Name: " . $location->getName() . "n"; echo " Location Title: " . $location->getTitle() . "n"; echo " Website URI: " . $location->getWebsiteUri() . "n"; // 访问其他字段，例如地址 if ($location->getAddress()) { echo " Address: " . $location->getAddress()->getPostalAddress()->getLocality() . ", " . $location->getAddress()->getPostalAddress()->getRegionCode() . "n"; } echo "---n"; } } else { echo "No locations found for this account.n"; } } catch (GoogleServiceException $e) { // 捕获并处理 API 错误 echo "An error occurred: " . $e->getMessage() . "n"; echo "Error details: " . $e->getErrors()[0]['message'] . "n"; if (isset($e->getErrors()[0]['details'][0]['fieldViolations'])) { foreach ($e->getErrors()[0]['details'][0]['fieldViolations'] as $violation) { echo " Field Violation: " . $violation['field'] . " - " . $violation['description'] . "n"; } } } catch (Exception $e) { // 捕获其他通用错误 echo "An unexpected error occurred: " . $e->getMessage() . "n"; } ?>
在上述代码中，’readMask’ => “name,title,websiteUri,address,primaryCategory,phoneNumbers” 是一个有效的示例。它仅请求 Location 资源中明确定义的字段，从而避免了 INVALID_ARGUMENT 错误。
重要注意事项
- 查阅官方文档是关键： 始终以 Google API 的官方文档为准，特别是关于特定资源（如 Location）的字段定义。这是确保 readMask 参数正确性的最可靠方法。
- 按需请求字段： 仅在 readMask 中指定您实际需要的字段。这不仅能减少API响应的大小，降低网络延迟，还能提高API调用的效率和性能。请求不必要的字段会浪费资源。
- 错误处理： 在您的代码中实现健壮的错误处理机制。捕获 GoogleServiceException 可以帮助您诊断和处理 API 返回的特定错误，例如 INVALID_ARGUMENT。
- API 凭证和权限： 确保您的 Google Cloud 项目已启用 Google My Business API，并且您的服务账户或OAuth 2.0 凭证拥有足够的权限来访问 My Business 账户和位置信息。
总结
readMask 参数在 Google My Business Business Information API 中是一个强大的工具，用于精细控制 API 响应中返回的数据。解决 INVALID_ARGUMENT 错误的关键在于理解 readMask 必须引用目标资源（在本例中是 Location）的有效、直接的属性。通过仔细查阅 API 文档并遵循示例代码中的最佳实践，您可以有效地利用 readMask 来优化您的 API 集成，确保顺利获取所需的商家位置数据。
