PHP集成GoogleAPI：readMask参数使用解析

在使用PHP集成Google My Business API时，开发者常因`readMask`参数配置不当导致400错误。本文聚焦于解决这一问题，详细解析`readMask`参数在Business Information API (v1)中的正确用法。新版API要求`readMask`必须指定Location资源中有效的字段，而非用户或图片等不相关的属性。通过本文，你将理解如何避免`INVALID_ARGUMENT`错误，并学会如何利用`readMask`高效获取商家位置列表，包括商家名称、网站URL、地址和电话号码等关键信息。文章提供清晰的PHP代码示例，助你顺利迁移至新版API，提升数据获取效率，优化应用性能。

理解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://developers.google.com/my-business/reference/businessinformation/rest/v1/locations。

PHP 代码示例：正确获取商家位置列表

以下是一个修正后的PHP代码示例，演示了如何正确配置readMask参数以获取商家位置列表：

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获取所需的商家位置数据。

好了，本文到此结束，带大家了解了《PHP集成GoogleAPI：readMask参数使用解析》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多文章知识！