本教程詳細(xì)探討了在使用Google My Business Business Information API的accounts.locations.list方法時(shí),因readMask參數(shù)格式不正確導(dǎo)致的INVALID_ARGUMENT錯(cuò)誤。文章將闡明readMask應(yīng)如何正確指定Location資源的有效字段,提供正確的php代碼示例,并指導(dǎo)開(kāi)發(fā)者如何根據(jù)官方文檔構(gòu)建有效的請(qǐng)求,確保成功獲取商家位置信息。
理解Google My Business Business Information API與readMask參數(shù)
google my business business information api (v1) 是google提供的一套用于管理商家在google上展示信息的接口,它取代了舊版的my business api (v4)。通過(guò)此api,開(kāi)發(fā)者可以程序化地獲取、更新和管理商家列表信息,例如商家名稱(chēng)、地址、電話、營(yíng)業(yè)時(shí)間等。
在調(diào)用API獲取資源列表時(shí),readMask參數(shù)是一個(gè)非常重要的機(jī)制。它的作用是允許開(kāi)發(fā)者明確指定需要從API響應(yīng)中返回哪些字段。這不僅可以減少網(wǎng)絡(luò)傳輸?shù)臄?shù)據(jù)量,提高性能,還能確保只獲取所需信息,避免不必要的數(shù)據(jù)處理。然而,如果readMask中指定的字段不正確,API將返回INVALID_ARGUMENT錯(cuò)誤。
INVALID_ARGUMENT錯(cuò)誤分析:readMask的常見(jiàn)誤區(qū)
在使用PHP客戶(hù)端庫(kù)調(diào)用Google_Service_MyBusinessBusinessInformation的accounts.locations.list方法時(shí),一個(gè)常見(jiàn)的錯(cuò)誤是提供了無(wú)效的readMask字段。例如,以下代碼片段展示了導(dǎo)致錯(cuò)誤的問(wèn)題:
<?php // ... 假設(shè) $client 已正確初始化并認(rèn)證 ... $my_business_account = new Google_Service_MyBusinessAccountManagement($client); $list_accounts_response = $my_business_account->accounts->listAccounts(); $account = $list_accounts_response[0]; // 獲取第一個(gè)賬戶(hù) $mybusinessService = new Google_Service_MyBusinessBusinessInformation($client); $locations = $mybusinessService->accounts_locations; $queryParams = [ "pageSize" => 10, // 錯(cuò)誤的 readMask 示例 'readMask' => "user.display_name,photo" ]; try { $locationsList = $locations->listAccountsLocations($account->name, $queryParams); // ... 處理響應(yīng) ... } catch (GoogleServiceException $e) { echo "Google Service Error: " . $e->getMessage() . PHP_EOL; // 捕獲到的錯(cuò)誤響應(yīng)示例: /* 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被設(shè)置為”user.display_name,photo”。API返回INVALID_ARGUMENT錯(cuò)誤,并明確指出”Invalid field mask provided”。其根本原因在于,readMask中指定的字段必須是所請(qǐng)求資源(在本例中是Location資源)的有效屬性。user.display_name和photo并非Location資源自身的直接屬性。雖然商家可能與用戶(hù)關(guān)聯(lián),并且有照片,但這些信息通常通過(guò)不同的API端點(diǎn)或Location資源內(nèi)部的特定嵌套字段來(lái)訪問(wèn),而不是作為頂層字段直接通過(guò)readMask獲取。
正確使用readMask:指定Location資源的有效字段
要正確使用readMask,開(kāi)發(fā)者必須查閱Google My Business Business Information API的官方文檔,特別是關(guān)于Location資源(https://www.php.cn/link/dc8ea2d055557e14585d74fc6c1033b2)的定義。該文檔詳細(xì)列出了Location對(duì)象的所有可用字段及其數(shù)據(jù)類(lèi)型。
例如,Location資源包含name(資源名稱(chēng))、title(商家名稱(chēng))、websiteUri(網(wǎng)站URI)、phoneNumbers(電話號(hào)碼)、address(地址)等字段。當(dāng)您需要獲取這些信息時(shí),應(yīng)將它們添加到readMask中。
以下是修正后的PHP代碼示例,展示了如何正確構(gòu)建readMask:
<?php require_once __DIR__ . '/vendor/autoload.php'; // 假設(shè) $client 已經(jīng)是一個(gè)經(jīng)過(guò)認(rèn)證的 Google_Client 實(shí)例。 // 確保 $client 已配置正確的認(rèn)證憑據(jù)和作用域,例如: // $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'); // 或其他認(rèn)證方式 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; } // 獲取第一個(gè)賬戶(hù)。在實(shí)際應(yīng)用中,您可能需要遍歷所有賬戶(hù)或選擇特定賬戶(hù)。 $account = $list_accounts_response->getAccounts()[0]; $mybusinessService = new Google_Service_MyBusinessBusinessInformation($client); $locations_service = $mybusinessService->accounts_locations; $queryParams = [ "pageSize" => 10, // 正確的 readMask 應(yīng)該包含 Location 資源的有效字段。 // 示例:獲取商家名稱(chēng)、網(wǎng)站URI和地址。 'readMask' => "name,title,websiteUri,address" // 您也可以根據(jù)需要添加其他字段,如 "phoneNumbers", "primaryCategory", "openInfo" 等。 // 對(duì)于嵌套字段,如需要特定地址組件,可能需要 "address.locality", "address.postalCode" 等, // 但通常指定父字段(如 "address")會(huì)返回整個(gè)地址對(duì)象。 ]; 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; // 訪問(wèn)地址信息 $address = $location->getAddress(); if ($address) { echo " Address: " . $address->getPostalAddress()->getFormattedAddress() . PHP_EOL; // 您可以進(jìn)一步訪問(wèn)地址的各個(gè)組成部分,如 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; }
注意事項(xiàng)與最佳實(shí)踐
- 始終查閱官方文檔: 這是避免readMask錯(cuò)誤最關(guān)鍵的步驟。每當(dāng)使用一個(gè)新的API或資源時(shí),務(wù)必仔細(xì)閱讀其文檔,了解支持的字段和數(shù)據(jù)結(jié)構(gòu)。
- 精確指定字段: readMask的目的是為了精確控制返回的數(shù)據(jù)。只請(qǐng)求您真正需要的字段,可以有效減少響應(yīng)大小和處理時(shí)間。
- 處理嵌套字段: 對(duì)于像address或phoneNumbers這樣的復(fù)雜對(duì)象,readMask通常可以直接指定父字段(例如address),這將返回整個(gè)嵌套對(duì)象。如果您只需要嵌套對(duì)象中的特定子字段(例如地址的城市address.locality),則可能需要指定完整的路徑。API文檔會(huì)明確說(shuō)明哪些嵌套字段可以直接在readMask中使用。
- 錯(cuò)誤處理: 實(shí)施健壯的錯(cuò)誤處理機(jī)制。捕獲GoogleServiceException并解析其getErrors()方法返回的詳細(xì)信息(特別是fieldViolations),這對(duì)于調(diào)試API請(qǐng)求中的參數(shù)問(wèn)題至關(guān)重要。
- 認(rèn)證與授權(quán): 確保您的Google API客戶(hù)端已使用正確的OAuth 2.0憑據(jù)和必要的作用域(例如https://www.googleapis.com/auth/business.manage)進(jìn)行認(rèn)證。沒(méi)有正確的權(quán)限,即使readMask正確也會(huì)導(dǎo)致認(rèn)證錯(cuò)誤。
總結(jié)
readMask是Google API中一個(gè)強(qiáng)大的特性,用于優(yōu)化數(shù)據(jù)傳輸和提高api調(diào)用的效率。在使用Google My Business Business Information API的accounts.locations.list等方法時(shí),遇到INVALID_ARGUMENT錯(cuò)誤并伴隨”Invalid field mask provided”的提示,幾乎總是意味著readMask中包含了不屬于目標(biāo)資源(如Location)的字段。通過(guò)仔細(xì)查閱官方API文檔,并根據(jù)Location資源的有效屬性來(lái)構(gòu)建readMask,開(kāi)發(fā)者可以避免此類(lèi)錯(cuò)誤,并成功獲取所需的商家位置信息。