GoogleAPIPHP客户端readMask使用详解

来到golang学习网的大家，相信都是编程学习爱好者，希望在这里学习文章相关编程知识。下面本篇文章就来带大家聊聊《Google API PHP客户端readMask使用教程》，介绍一下，希望对大家的知识积累有所帮助，助力实战开发！

Google My Business Business Information API 概述

Google My Business Business Information API 是 Google 提供的用于管理 Google 商家资料的最新接口。它允许开发者以编程方式访问和更新商家信息，包括地点详情、营业时间、照片、评论等。相较于旧版的 Google My Business API (v4)，新版 API 提供了更细粒度的控制和更清晰的资源结构。

在使用 PHP 客户端库与此 API 交互时，通常会涉及以下几个核心步骤：

1. 初始化 Google 客户端并进行认证。
2. 获取账户管理服务实例 (Google_Service_MyBusinessAccountManagement) 以列出和选择商家账户。
3. 获取商家信息服务实例 (Google_Service_MyBusinessBusinessInformation) 以操作地点（Location）资源。
4. 调用相应的方法，例如 accounts_locations->listAccountsLocations() 来获取账户下的地点列表。

readMask 参数解析与常见错误

在调用 API 获取资源列表或详情时，readMask 是一个非常重要的参数。它允许您指定 API 响应中应包含的资源字段，从而实现“部分响应”（Partial Response）。这是一种优化策略，可以显著减少传输的数据量，提高 API 调用的效率。

然而，readMask 的使用不当是导致 INVALID_ARGUMENT 错误的一个常见原因。当您尝试使用 Google_Service_MyBusinessBusinessInformation 服务的 accounts_locations->listAccountsLocations() 方法获取地点列表时，如果 readMask 参数中包含了不属于 Location 资源本身的字段，API 将返回 HTTP 400 Bad Request 错误，并附带 INVALID_ARGUMENT 状态码及 Invalid field mask provided 的详细信息。

错误示例分析： 例如，尝试使用 readMask 指定 user.display_name,photo：

{
  "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"
          }
        ]
      }
    ]
  }
}

这个错误发生的原因是 user.display_name 和 photo 并非 Location 资源直接拥有的属性。readMask 必须指向 Location 资源（或其嵌套子资源）中定义的有效字段。例如，地点名称 (name)、标题 (title)、网站 URI (websiteUri)、地址 (address)、经纬度 (latlng) 等才是 Location 资源的合法属性。

readMask 的正确用法

要正确使用 readMask，您必须查阅 Google My Business Business Information API 的官方文档，特别是关于 Location 资源的定义。该文档会列出所有可用的字段及其类型。

正确的 readMask 应包含以下类型的字段：

• 顶级字段： 如 name (地点资源名称), title (商家标题), websiteUri (网站URI), languageCode 等。
• 嵌套字段： 如果某个字段本身是一个对象，您可以指定其子字段，例如 address.regionCode, address.locality, latlng.latitude, latlng.longitude。

示例： 如果您想获取地点的名称、标题、网站 URI 和地址信息，您的 readMask 可以是： name,title,websiteUri,address.regionCode,address.locality,address.postalCode,address.addressLines

PHP 客户端示例：正确获取地点列表

以下是一个使用 PHP 客户端库正确获取 Google My Business 地点列表的示例代码，其中包含了 readMask 的正确用法和基本的错误处理：

setApplicationName('My Business API Locations Example');

    // 假设你使用服务账户认证
    // 请替换为你的服务账户凭据文件路径
    $client->setAuthConfig('path/to/your/service_account_credentials.json'); 

    // 或者使用 OAuth 2.0 认证流程
    // $client->setRedirectUri('YOUR_REDIRECT_URI');
    // $client->setAccessToken('YOUR_ACCESS_TOKEN'); // 或使用刷新令牌获取新令牌

    // 设置必要的 API 作用域
    $client->setScopes([
        'https://www.googleapis.com/auth/business.manage' // 管理商家资料的权限
    ]);

    return $client;
}

try {
    $client = getGoogleClient();

    // 1. 获取账户管理服务实例
    $my_business_account = new Google_Service_MyBusinessAccountManagement($client);

    // 2. 列出账户
    $list_accounts_response = $my_business_account->accounts->listAccounts();

    // 检查是否有账户，并选择第一个账户进行操作
    $accounts = $list_accounts_response->getAccounts();
    if (empty($accounts)) {
        echo "未找到任何Google My Business账户。\n";
        exit;
    }
    $account = $accounts[0]; // 获取第一个账户

    echo "正在处理账户: " . $account->getName() . " (显示名称: " . $account->getDisplayName() . ")\n";

    // 3. 获取Business Information服务实例
    $mybusinessService = new Google_Service_MyBusinessBusinessInformation($client);

    // 4. 准备查询参数
    $queryParams = [
        "pageSize" => 10, // 每页获取10个地点
        // 关键点：readMask 必须指定 Location 资源的有效属性。
        // 这些属性可以在 Google My Business Business Information API 的 Location 资源文档中找到。
        // 错误示例：'user.display_name,photo'
        // 正确示例：
        'readMask' => "name,title,websiteUri,address,latlng,primaryCategory.displayName"
        // 更多可选字段：phoneNumbers, storefrontHours, regularHours, specialHours, serviceArea, labels, relations, moreHours, metadata, profile, serviceItems, attributes 等
    ];

    // 5. 列出账户下的地点
    // accounts_locations 是 Google_Service_MyBusinessBusinessInformation 服务下的 Locations 集合
    $locationsList = $mybusinessService->accounts_locations->listAccountsLocations($account->name, $queryParams);

    // 6. 处理返回的地点数据
    $locations = $locationsList->getLocations();
    if (!empty($locations)) {
        echo "成功获取地点列表：\n";
        foreach ($locations as $location) {
            echo "--------------------\n";
            echo "  地点名称: " . $location->getName() . "\n";
            echo "  地点标题: " . $location->getTitle() . "\n";
            if ($location->getWebsiteUri()) {
                echo "  网站URI: " . $location->getWebsiteUri() . "\n";
            }
            if ($location->getAddress()) {
                $address = $location->getAddress();
                echo "  地址: " . implode(", ", $address->getAddressLines()) . ", " 
                     . $address->getLocality() . ", " . $address->getRegionCode() . " " . $address->getPostalCode() . "\n";
            }
            if ($location->getLatlng()) {
                $latlng = $location->getLatlng();
                echo "  经纬度: " . $latlng->getLatitude() . ", " . $latlng->getLongitude() . "\n";
            }
            if ($location->getPrimaryCategory()) {
                echo "  主类别: " . $location->getPrimaryCategory()->getDisplayName() . "\n";
            }
            // 访问其他通过 readMask 请求的字段
        }
        echo "--------------------\n";

        // 如果有下一页，可以继续获取
        if ($locationsList->getNextPageToken()) {
            echo "存在更多地点，下一页令牌: " . $locationsList->getNextPageToken() . "\n";
            // 您可以在此处添加逻辑以获取下一页数据
        }

    } else {
        echo "该账户下未找到任何地点。\n";
    }

} catch (Google\Service\Exception $e) {
    // 捕获 Google API 服务的特定异常
    echo "API调用失败: " . $e->getMessage() . "\n";
    $errors = $e->getErrors();
    if (!empty($errors)) {
        foreach ($errors as $error) {
            echo "错误详情: " . ($error['message'] ?? 'N/A') . "\n";
            echo "错误状态: " . ($error['status'] ?? 'N/A') . "\n";
            if (isset($error['details'][0]['fieldViolations'])) {
                foreach ($error['details'][0]['fieldViolations'] as $violation) {
                    echo "字段违规: " . ($violation['field'] ?? 'N/A') . " - " . ($violation['description'] ?? 'N/A') . "\n";
                }
            }
        }
    }
} catch (Exception $e) {
    // 捕获其他通用异常
    echo "发生未知错误: " . $e->getMessage() . "\n";
}

?>

注意事项与最佳实践

1. 查阅官方文档： 始终以 Google My Business Business Information API 的官方文档作为 readMask 字段的最终参考。Location 资源的详细定义将明确指出所有可用的字段。
2. 精确指定字段： 只请求您实际需要的字段。这不仅可以避免 INVALID_ARGUMENT 错误，还能减少网络传输量和 API 响应处理时间，提高应用程序性能。
3. 错误处理： 实现健壮的错误处理机制。捕获 Google\Service\Exception 可以帮助您识别 API 返回的特定错误（如 400 Bad Request），并根据错误详情进行调试。
4. 认证与授权： 确保您的 Google 客户端已正确配置了认证凭据（如 OAuth 2.0 凭据或服务账户）和必要的 API 作用域（例如 https://www.googleapis.com/auth/business.manage）。权限不足也会导致 API 调用失败。
5. 分页处理： 当地点数量较多时，API 响应会进行分页。利用 pageSize 和 nextPageToken 参数来循环获取所有地点数据。

总结

正确理解和使用 readMask 参数是有效利用 Google My Business Business Information API 的关键。通过确保 readMask 中指定的字段与目标资源（如 Location）的实际属性相符，可以避免常见的 INVALID_ARGUMENT 错误，并实现高效、精准的数据获取。开发者在集成 API 时，务必仔细查阅官方文档，以确保参数的正确性。

本篇关于《GoogleAPIPHP客户端readMask使用详解》的介绍就到此结束啦，但是学无止境，想要了解学习更多关于文章的相关知识，请关注golang学习网公众号！