本文旨在解決在使用php客戶端庫調(diào)用Google My Business Business Information API獲取商家位置列表時，因readMask參數(shù)配置不當(dāng)導(dǎo)致的400錯誤。核心問題在于readMask必須指定location資源中有效的字段，而非其他不相關(guān)的屬性。文章將提供正確的readMask用法示例，幫助開發(fā)者順利遷移至新版API并高效獲取所需商家數(shù)據(jù)。
理解Google My Business Business Information API (v1) 與 readMask
隨著google my business api從v4版本遷移至最新的business information api (v1)，開發(fā)者在獲取商家位置信息時可能會遇到新的挑戰(zhàn)。其中一個常見問題是關(guān)于readmask參數(shù)的正確使用。readmask是一個關(guān)鍵字段，它允許api調(diào)用者指定只返回資源中需要的部分字段，從而優(yōu)化數(shù)據(jù)傳輸效率和減少不必要的數(shù)據(jù)量。
INVALID_ARGUMENT 錯誤及其根源
在使用Google_Service_MyBusinessBusinessInformation服務(wù)獲取商家位置列表時，如果readMask參數(shù)被錯誤地設(shè)置為user.display_name或photo等不屬于Location資源本身的字段，API會返回http 400 Bad Request錯誤，并附帶INVALID_ARGUMENT和Invalid field mask provided的詳細(xì)信息。
{ "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ù)是針對API返回的Location資源對象的屬性進行過濾的。它不能用于請求與Location資源本身不直接關(guān)聯(lián)的其他實體（如用戶或圖片，除非圖片是Location資源的一個直接屬性，且通過特定字段名訪問）。例如，user.display_name可能是與某個用戶賬戶關(guān)聯(lián)的屬性，而photo可能指的是獨立的照片資源，它們都不是Location資源頂層直接可用的字段。
Location資源 readMask 的正確用法
要正確使用readMask，必須確保其中包含的字段名是Location資源中定義的有效屬性。這些屬性包括但不限于：
- name：資源的完整名稱（例如 accounts/ACCOUNT_ID/locations/LOCATION_ID）。
- title：商家名稱。
- storeCode：商家代碼。
- websiteUri：網(wǎng)站URL。
- address：商家地址信息。
- latlng：經(jīng)緯度坐標(biāo)。
- phoneNumbers：電話號碼信息。
- regularHours：常規(guī)營業(yè)時間。
- openInfo：營業(yè)狀態(tài)信息。
- categories：商家類別。
- serviceArea：服務(wù)區(qū)域。
開發(fā)者應(yīng)查閱Google My Business Business Information API的官方文檔中關(guān)于Location資源字段的詳細(xì)說明，以獲取完整的有效字段列表：https://www.php.cn/link/dc8ea2d055557e14585d74fc6c1033b2。
立即學(xué)習(xí)“PHP免費學(xué)習(xí)筆記（深入）”；
PHP 代碼示例：正確獲取商家位置列表
以下是一個修正后的PHP代碼示例，演示了如何正確配置readMask參數(shù)以獲取商家位置列表：
<?php require_once 'vendor/autoload.php'; // 確保你的composer autoload文件已加載 // 假設(shè) $client 已經(jīng)是一個經(jīng)過認(rèn)證的 Google_Client 實例 // 并且已經(jīng)設(shè)置了正確的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; } // 通常選擇第一個賬戶，或者根據(jù)業(yè)務(wù)邏輯選擇特定賬戶 $account = $list_accounts_response->getAccounts()[0]; echo "正在處理賬戶: " . $account->getName() . "n"; // 2. 初始化 MyBusinessBusinessInformation 服務(wù) $mybusinessService = new Google_Service_MyBusinessBusinessInformation($client); $locations_service = $mybusinessService->accounts_locations; // 3. 定義查詢參數(shù)，重點是正確的 readMask $queryParams = [ "pageSize" => 10, // 修正：readMask 必須指定 Location 資源本身的有效字段 // 這里請求了名稱、標(biāo)題、商家代碼、網(wǎng)站URI、地址和電話號碼 'readMask' => "name,title,storeCode,websiteUri,address,phoneNumbers" ]; // 4. 調(diào)用 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 " - 商家標(biāo)題 (Title): " . $location->getTitle() . "n"; if ($location->getStoreCode()) { echo " - 商家代碼 (Store Code): " . $location->getStoreCode() . "n"; } if ($location->getWebsiteUri()) { echo " - 網(wǎng)站 (Website): " . $location->getWebsiteUri() . "n"; } // 地址字段是一個復(fù)雜對象，需要進一步解析 if ($location->getAddress()) { $postalAddress = $location->getAddress()->getPostalAddress(); if ($postalAddress) { echo " - 地址 (Address): " . implode(", ", $postalAddress->getAddressLines()) . ", " . $postalAddress->getLocality() . "n"; } } // 電話號碼字段也是一個復(fù)雜對象 if ($location->getPhoneNumbers() && $location->getPhoneNumbers()->getPrimaryPhone()) { echo " - 主要電話 (Primary Phone): " . $location->getPhoneNumbers()->getPrimaryPhone() . "n"; } echo "---n"; } // 處理分頁，如果有更多結(jié)果 $nextPageToken = $locationsListResponse->getNextPageToken(); if ($nextPageToken) { echo "還有更多結(jié)果，可以通過 nextPageToken 繼續(xù)獲取。n"; // 示例：獲取下一頁 // $queryParams['pageToken'] = $nextPageToken; // $nextLocationsListResponse = $locations_service->listAccountsLocations($account->name, $queryParams); } } catch (GoogleServiceException $e) { echo "API 調(diào)用出錯: " . $e->getMessage() . "n"; echo "錯誤詳情: " . (isset($e->getErrors()[0]['message']) ? $e->getErrors()[0]['message'] : '未知錯誤') . "n"; // 更多錯誤處理，例如根據(jù)錯誤碼進行不同處理 } catch (Exception $e) { echo "發(fā)生未知錯誤: " . $e->getMessage() . "n"; } ?>
注意事項
- 字段準(zhǔn)確性：始終參考Google My Business Business Information API的官方Location資源文檔，以獲取最新和最準(zhǔn)確的有效readMask字段列表。API可能會更新，舊的字段可能被廢棄，新的字段可能被添加。
- 錯誤處理：在實際應(yīng)用中，務(wù)必實現(xiàn)健壯的錯誤處理機制，捕獲GoogleServiceException。通過檢查錯誤碼和錯誤詳情，可以更精確地診斷和解決問題。
- API權(quán)限與范圍：確保你的Google Cloud項目已啟用Google My Business Business Information API，并且OAuth 2.0客戶端憑據(jù)具有訪問所需資源的正確權(quán)限（Scope），例如https://www.googleapis.com/auth/mybusiness.businessinformation和https://www.googleapis.com/auth/mybusiness.accountmanagement。
- 分頁處理：listAccountsLocations方法支持分頁。當(dāng)結(jié)果數(shù)量超過pageSize時，API會返回nextPageToken。開發(fā)者需要循環(huán)調(diào)用API，并在后續(xù)請求中帶上pageToken參數(shù)以獲取所有數(shù)據(jù)。
- 性能優(yōu)化：readMask的目的是只請求你真正需要的數(shù)據(jù)。避免請求不必要的字段可以減少API響應(yīng)大小，從而提高應(yīng)用程序的性能和響應(yīng)速度。
總結(jié)
通過本文，我們詳細(xì)探討了Google My Business Business Information API中readMask參數(shù)的正確使用方法。核心要點是：readMask中的字段必須是目標(biāo)資源（本例中為Location）的有效屬性。遵循這一原則，并結(jié)合官方文檔進行字段驗證，將有效避免INVALID_ARGUMENT錯誤，確保開發(fā)者能夠順利、高效地從Google My Business獲取所需的商家位置數(shù)據(jù)。
