遷移作業總覽

歐洲經濟區 (EEA) 開發人員

本指南著重說明舊版地點服務與新版地點類別的主要差異。升級至 Place 類別可享有顯著優勢，包括提升效能和採用新的定價模式。如要充分運用 Places，並確保應用程式為最新版本，請詳閱本指南中列出的變更。

遷移作業的帳單最佳做法

如果您的 API 使用量夠高，可改用第二層級的價格，就適用這項指引。遷移至較新版本的 API 時，系統也會以不同的 SKU 計費。為避免在轉換當月費用增加，建議您盡可能在月初切換至正式環境中的新 API。這樣可確保您在遷移當月達到最具成本效益的月費方案。如要瞭解定價層級，請參閱定價頁面和定價常見問題。

啟用 Places API

「地點」類別依賴 Places API 服務。如要使用新版 Place 類別的功能，請務必先在 Google Cloud 專案中啟用 Places API (新版)。詳情請參閱入門指南。

一般變更

下表列出 PlacesService 和 Place 的主要差異：

PlacesService (舊版) Place (新)
方法需要使用回呼來處理結果物件和 google.maps.places.PlacesServiceStatus 回應。 使用 Promise，並以非同步方式運作。
方法需要進行 PlacesServiceStatus 檢查。 不需要檢查狀態，可使用標準錯誤處理程序。
地點資料欄位的格式為蛇形命名法。 地點資料欄位的格式為駝峰式大小寫。
僅限一組固定的地點類型和地點資料欄位。 提供更多定期更新的地點類型和地點資料欄位。

API 專屬變更

「地點」類別提供 API，方便您使用 Places Library，並支援 Promise 等新型使用模式。Place 類別會公開與舊版 Places Service 相同的地點資料欄位和地點類型，並包含許多地點資料欄位和地點類型的新值。

下表說明 Places Service 的功能如何對應至 Place 類別的功能：

地點介面集服務 (舊版) 地點類別 (新)
地點資料欄位 地點類別資料欄位
地點類型 地點類型
PlacesService.findPlaceFromQuery() Place.searchByText()
PlacesService.findPlaceFromPhoneNumber() Place.searchByText()
PlacesService.textSearch() Place.searchByText()
PlacesService.nearbySearch() Place.searchNearby()
PlacesService.getDetails() Place.fetchFields()
Places.AutocompletionRequest Places.AutocompleteRequest
Places.AutocompletePrediction Places.PlacePrediction
Autocomplete 類別 PlaceAutocompleteElement 類別
SearchBox 類別 ---

載入 Places 程式庫

應用程式載入 Places 程式庫的方式，取決於使用的啟動載入器。如果應用程式使用動態程式庫匯入，您可以使用 await 運算子呼叫 importLibrary()，在執行階段載入所需程式庫，如下所示：

const { Place } = await google.maps.importLibrary("places");

如果您的應用程式使用直接指令碼載入標記，請在載入器指令碼中要求 places 程式庫：

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=places&callback=initMap">
</script>

進一步瞭解如何載入 Maps JavaScript API。

本節包含下列指南，可協助您遷移應用程式，以使用最新版 Places API：