理解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 (Google\Service\Exception $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可能会更新，旧的字段可能被废弃，新的字段可能被添加。
- 错误处理：在实际应用中，务必实现健壮的错误处理机制，捕获Google\Service\Exception。通过检查错误码和错误详情，可以更精确地诊断和解决问题。
- 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获取所需的商家位置数据。
