工作階段符記

Place Autocomplete 使用工作階段符記,將使用者自動完成搜尋的查詢和選取階段歸入不同的工作階段,以用於計費。工作階段是從使用者輸入查詢時開始,到使用者選取地點並呼叫 Place Details 時結束。每個工作階段可以含有多項自動完成查詢,其後會選取一個地點。工作階段內每個要求的 API 金鑰必須屬於同一個 Google Cloud 控制台專案。工作階段結束後,符記就會失效;應用程式必須為每個工作階段產生新的符記。如果省略 sessiontoken 參數或重複使用工作階段符記,系統會視為未提供工作階段符記,並針對工作階段收費 (每個要求分別收費)。

我們建議遵循下列規範:

  • 所有自動完成工作階段都使用工作階段符記。
  • 為每個工作階段產生新權杖
  • 確認工作階段中所有 Place Autocomplete 和 Place Details 要求使用的 API 金鑰,皆屬於同一個 Google Cloud 控制台專案。
  • 請務必針對每個新的工作階段傳遞不重複的工作階段符記。如果多個工作階段使用同一個符記,則每個要求會分別計費。

您可以選擇在要求中省略自動完成工作階段符記。如果省略工作階段符記,每個要求都會分開計費,觸發 Autocomplete - Per Request SKU。假如您重複使用工作階段符記,系統會將工作階段視為無效,並依照未提供工作階段符記的情況收取相關要求費用。

範例

使用者輸入查詢時,系統會每隔幾個按鍵動作 (而非每個字元) 執行自動完成要求,並傳回可能的結果清單。當使用者從結果清單中做出選擇時,該選項會計為要求,在搜尋期間發出的所有要求都會經過組合並計為單一要求。如果使用者選取地點,則搜尋查詢為免付費,且只收取地點資料要求的費用。如果使用者未在工作階段開始後的幾分鐘內選取,系統只會對搜尋查詢收費。

讓我們從應用程式的角度來檢視這個事件流程。

  1. 使用者開始輸入查詢,搜尋「法國巴黎」。
  2. 偵測到使用者輸入內容時,應用程式會建立新的工作階段符記「符記 A」。
  3. 在使用者輸入內容時,API 每隔幾個字元就會發出自動完成要求,針對下列各個字元顯示新的可能結果清單:
    「P」
    「Par」
    「Paris」、「
    "Paris, Fr」
  4. 當使用者做出選擇時:
    • 從查詢產生的所有要求都會分組並加到由「憑證 A」代表的工作階段,當做單一要求。
    • 系統會將使用者的選擇計為地點詳細資料要求,並加進以「權杖 A」代表的工作階段。
  5. 工作階段結束,應用程式捨棄「Token A」。

如要進一步瞭解 Autocomplete 要求的計費方式,請參閱「用量與計費」一文。

建立工作階段符記

您可以使用偏好的任何程式輔助機制建立工作階段符記。我們建議使用第 4 版 UUID 做為工作階段符記。