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