理解Google My Business Business Information API与readMask参数
google my business business information api (v1) 是google提供的一套用于管理商家在google上展示信息的接口，它取代了旧版的my business api (v4)。通过此api，开发者可以程序化地获取、更新和管理商家列表信息，例如商家名称、地址、电话、营业时间等。
在调用API获取资源列表时，readMask参数是一个非常重要的机制。它的作用是允许开发者明确指定需要从API响应中返回哪些字段。这不仅可以减少网络传输的数据量，提高性能，还能确保只获取所需信息，避免不必要的数据处理。然而，如果readMask中指定的字段不正确，API将返回INVALID_ARGUMENT错误。
INVALID_ARGUMENT错误分析：readMask的常见误区
在使用PHP客户端库调用Google_Service_MyBusinessBusinessInformation的accounts.locations.list方法时，一个常见的错误是提供了无效的readMask字段。例如，以下代码片段展示了导致错误的问题：
accounts->listAccounts();
$account = $list_accounts_response[0]; // 获取第一个账户
$mybusinessService = new Google_Service_MyBusinessBusinessInformation($client);
$locations = $mybusinessService->accounts_locations;
$queryParams = [
"pageSize" => 10,
// 错误的 readMask 示例
'readMask' => "user.display_name,photo"
];
try {
$locationsList = $locations->listAccountsLocations($account->name, $queryParams);
// ... 处理响应 ...
} catch (Google\Service\Exception $e) {
echo "Google Service Error: " . $e->getMessage() . PHP_EOL;
// 捕获到的错误响应示例：
/*
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"
}
]
}
]
}
}
*/
}上述代码中，readMask被设置为"user.display_name,photo"。API返回INVALID_ARGUMENT错误，并明确指出"Invalid field mask provided"。其根本原因在于，readMask中指定的字段必须是所请求资源（在本例中是Location资源）的有效属性。user.display_name和photo并非Location资源自身的直接属性。虽然商家可能与用户关联，并且有照片，但这些信息通常通过不同的API端点或Location资源内部的特定嵌套字段来访问，而不是作为顶层字段直接通过readMask获取。
正确使用readMask：指定Location资源的有效字段
要正确使用readMask，开发者必须查阅Google My Business Business Information API的官方文档，特别是关于Location资源（https://www.php.cn/link/dc8ea2d055557e14585d74fc6c1033b2）的定义。该文档详细列出了Location对象的所有可用字段及其数据类型。
例如，Location资源包含name（资源名称）、title（商家名称）、websiteUri（网站URI）、phoneNumbers（电话号码）、address（地址）等字段。当您需要获取这些信息时，应将它们添加到readMask中。
以下是修正后的PHP代码示例，展示了如何正确构建readMask：
setApplicationName("My Business API Client");
// $client->setScopes(['https://www.googleapis.com/auth/business.manage']);
// $client->setAuthConfig('path/to/your/credentials.json'); // 或其他认证方式
try {
$my_business_account = new Google_Service_MyBusinessAccountManagement($client);
$list_accounts_response = $my_business_account->accounts->listAccounts();
if (empty($list_accounts_response->getAccounts())) {
echo "No accounts found." . PHP_EOL;
exit;
}
// 获取第一个账户。在实际应用中，您可能需要遍历所有账户或选择特定账户。
$account = $list_accounts_response->getAccounts()[0];
$mybusinessService = new Google_Service_MyBusinessBusinessInformation($client);
$locations_service = $mybusinessService->accounts_locations;
$queryParams = [
"pageSize" => 10,
// 正确的 readMask 应该包含 Location 资源的有效字段。
// 示例：获取商家名称、网站URI和地址。
'readMask' => "name,title,websiteUri,address"
// 您也可以根据需要添加其他字段，如 "phoneNumbers", "primaryCategory", "openInfo" 等。
// 对于嵌套字段，如需要特定地址组件，可能需要 "address.locality", "address.postalCode" 等，
// 但通常指定父字段（如 "address"）会返回整个地址对象。
];
echo "Fetching locations for account: " . $account->name . PHP_EOL;
$locationsList = $locations_service->listAccountsLocations($account->name, $queryParams);
if ($locationsList->getLocations()) {
echo "Successfully retrieved locations:" . PHP_EOL;
foreach ($locationsList->getLocations() as $location) {
echo " Location Name (Resource): " . $location->getName() . PHP_EOL;
echo " Location Title (Business Name): " . $location->getTitle() . PHP_EOL;
echo " Website URI: " . $location->getWebsiteUri() . PHP_EOL;
// 访问地址信息
$address = $location->getAddress();
if ($address) {
echo " Address: " . $address->getPostalAddress()->getFormattedAddress() . PHP_EOL;
// 您可以进一步访问地址的各个组成部分，如 getLocality(), getPostalCode() 等
}
echo "--------------------" . PHP_EOL;
}
} else {
echo "No locations found for this account." . PHP_EOL;
}
} catch (Google\Service\Exception $e) {
echo "Google Service Error: " . $e->getMessage() . PHP_EOL;
echo "Details: " . json_encode($e->getErrors(), JSON_PRETTY_PRINT) . PHP_EOL;
} catch (Exception $e) {
echo "Error: " . $e->getMessage() . PHP_EOL;
}注意事项与最佳实践
- 始终查阅官方文档： 这是避免readMask错误最关键的步骤。每当使用一个新的API或资源时，务必仔细阅读其文档，了解支持的字段和数据结构。
- 精确指定字段： readMask的目的是为了精确控制返回的数据。只请求您真正需要的字段，可以有效减少响应大小和处理时间。
- 处理嵌套字段： 对于像address或phoneNumbers这样的复杂对象，readMask通常可以直接指定父字段（例如address），这将返回整个嵌套对象。如果您只需要嵌套对象中的特定子字段（例如地址的城市address.locality），则可能需要指定完整的路径。API文档会明确说明哪些嵌套字段可以直接在readMask中使用。
- 错误处理： 实施健壮的错误处理机制。捕获Google\Service\Exception并解析其getErrors()方法返回的详细信息（特别是fieldViolations），这对于调试API请求中的参数问题至关重要。
- 认证与授权： 确保您的Google API客户端已使用正确的OAuth 2.0凭据和必要的作用域（例如https://www.googleapis.com/auth/business.manage）进行认证。没有正确的权限，即使readMask正确也会导致认证错误。
总结
readMask是Google API中一个强大的特性，用于优化数据传输和提高API调用的效率。在使用Google My Business Business Information API的accounts.locations.list等方法时，遇到INVALID_ARGUMENT错误并伴随"Invalid field mask provided"的提示，几乎总是意味着readMask中包含了不属于目标资源（如Location）的字段。通过仔细查阅官方API文档，并根据Location资源的有效属性来构建readMask，开发者可以避免此类错误，并成功获取所需的商家位置信息。
