遷移作業總覽

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

本指南重點說明舊版 Places 服務與新版 Place 類別的主要差異。升級至 Place 類別可帶來多項重要優勢，包括提升效能和採用新的定價模式。為充分發揮 Places 的效益，並確保應用程式保持最新狀態，請詳閱本指南，瞭解各項異動。

遷移作業的帳單最佳做法

如果 API 用量達到第二級定價標準，請參考這項指引。遷移至新版 API 時，系統也會依據不同的 SKU 計費。為避免在轉換當月產生額外費用，建議您盡可能在月初將實際工作環境切換至新版 API。這樣一來，您在遷移月份就能享有最符合成本效益的每月定價級別。如要瞭解定價級別，請參閱定價頁面和定價常見問題。

啟用 Places API

Place 類別仰賴 Places API 服務。如要使用新版 Place 類別的功能，您必須先在 Google Cloud 專案中啟用 Places API (新版)。詳情請參閱「開始使用」。

一般變更

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

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

API 專屬異動

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

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

Places Service (舊版) Place 類別 (新版)
地點資料欄位 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：