本教程详细探讨了在使用Google My Business Business Information API的accounts.locations.list方法时，因readMask参数格式不正确导致的INVALID_ARGUMENT错误。文章将阐明readMask应如何正确指定Location资源的有效字段，提供正确的php代码示例，并指导开发者如何根据官方文档构建有效的请求，确保成功获取商家位置信息。
理解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字段。例如，以下代码片段展示了导致错误的问题：
<?php // ... 假设 $client 已正确初始化并认证 ... $my_business_account = new Google_Service_MyBusinessAccountManagement($client); $list_accounts_response = $my_business_account->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 (GoogleServiceException $e) { echo "Google Service Error: " . $e->getMessage() . PHP_EOL; // 捕获到的错误响应示例： /* GoogleServiceException #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：
<?php require_once __DIR__ . '/vendor/autoload.php'; // 假设 $client 已经是一个经过认证的 Google_Client 实例。 // 确保 $client 已配置正确的认证凭据和作用域，例如： // $client = new Google_Client(); // $client->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 (GoogleServiceException $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中使用。
- 错误处理： 实施健壮的错误处理机制。捕获GoogleServiceException并解析其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，开发者可以避免此类错误，并成功获取所需的商家位置信息。
