Google API v1 readMask 错误解决方法

随着 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 会返回一个典型的 Google\Service\Exception #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://developers.google.com/my-business/reference/businessinformation/rest/v1/locations

解决方案与示例代码

解决 readMask 错误的关键在于确保 readMask 中只包含 Location 资源中定义的有效属性。以下是修正后的 PHP 代码示例，展示了如何正确构造 readMask：

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 (Google\Service\Exception $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 错误。

重要注意事项

1. 查阅官方文档是关键： 始终以 Google API 的官方文档为准，特别是关于特定资源（如 Location）的字段定义。这是确保 readMask 参数正确性的最可靠方法。
2. 按需请求字段： 仅在 readMask 中指定您实际需要的字段。这不仅能减少API响应的大小，降低网络延迟，还能提高API调用的效率和性能。请求不必要的字段会浪费资源。
3. 错误处理： 在您的代码中实现健壮的错误处理机制。捕获 Google\Service\Exception 可以帮助您诊断和处理 API 返回的特定错误，例如 INVALID_ARGUMENT。
4. 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 集成，确保顺利获取所需的商家位置数据。