遷移作業總覽

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

本指南著重說明舊版 Places 服務與新版 Place 類別的主要差異。升級至 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 類別的功能：

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 Library

應用程式載入 Places Library 的方式，取決於使用的 bootstrap 載入器。如果應用程式使用動態程式庫匯入，您可以在執行階段使用 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：