建構驗證邏輯

本文件說明如何建構地址檢查系統，處理 Address Validation API 的各種回應。內容會說明如何建構邏輯以正確使用回應、調查 API 的其他信號，以及何時以及如何提示客戶瞭解詳情。

一般來說，API 回應會決定系統應以下列方式處理地址：

  • 修正：地址品質不佳。 系統應提示您提供更多資訊。
  • 確認：地址品質良好，但輸入地址有所變更。您可能會收到確認提示。
  • 接受：地址為高品質。您可以接受您提供的地址。

金鑰用途

這份文件可協助您修改系統，以妥善分析 API 回應，並判斷所提供的地址後續要採取的行動。下列虛擬程式碼說明可能的流程。

if (the API response indicates significant problems in the address)
    FIX - prompt the user to fix the address
else if (the API response indicates less significant problems in the address)
    CONFIRM - confirm with the user that the address is correct
else
    ACCEPT - continue with the address returned by the API.

確切的邏輯會因您的情況而異，詳情請參閱實作指南。您也可以使用這個邏輯的開放原始碼實作，其位於擴充元件程式庫中。

工作流程總覽

下表摘要列出系統可採取的兩項動作：

  1. 根據修正、確認及接受行為區分的工作流程。
  2. 要檢查回應中的第一個信號。此處描述的信號來自 verdict 屬性，且不是唯一要檢查的信號，而是提供地址品質的初始指標。每種行為類型都對應本文件中的一個章節，說明您可能還需要調查的進一步信號。
系統行為
修正地址

verdict 的回應表示應提供的重要資訊。Address Validation API 傳回的地址可能不符合交付品質。

工作流程

  1. 必要時調查地址元件。
  2. 提醒客戶解決問題。
  3. 要求驗證更新後的地址。
  4. (選用) 傳送要求至 API 的意見回饋端點。 請參閱「處理更新後的地址」。
  5. 繼續設定地址。

判定信號

符合下列任何條件：
確認地址

verdict 的回應表示有交貨地址，但已變更原始輸入內容：推斷資料拼寫或可確認的資料。

工作流程

  1. 需要修正：
    1. 必要時調查地址元件。
    2. 要求驗證更新後的地址。
    3. (選用) 傳送要求至 API 的意見回饋端點。 請參閱「處理更新後的地址」。
    4. 繼續設定地址。
  2. 不需要修正：
    1. (選用) 傳送要求至 API 的意見回饋端點。 請參閱「處理更新後的地址」。
    2. 繼續設定地址。

判定信號

符合下列所有條件：

  • validationGranularity 包含 ROUTE 或更佳。請參閱精細程度值。
  • addressComplete 為 true。
  • 「hasInferredComponents」欄位為「true」，或是「hasReplacedComponents」欄位為「true」。
接受地址

Address Validation API 回應表示地址品質良好。

工作流程

繼續處理退貨地址。

判定信號

符合下列所有條件：

  • validationGranularity 包含 PREMISE 或更佳。 請參閱精細程度值。
  • addressComplete 為 true。
  • 沒有推論或替換的元件。

實作指南

設計系統回應 Address Validation API 信號的方式時，您可以參考下列建議做法，建立更有效的回應模型。不過，這些只是建議，提醒您，您的導入作業應適合您的商業模式。

指引 詳細資料
風險等級

在提示要求修正和接受輸入的地址時，請考量您遇到的容忍度。

Address Validation API 會傳回各種信號，方便您整合至風險等級，以便最佳化驗證程序。

舉例來說，即使地址的門牌號碼尚未確認，您仍可接受該地址。另一方面，如果您的業務營運需要更準確的地址，您可能會提示使用者。如需可能屬於任一類別的範例，請參閱「接受地址 - 範例」中的「非美國未確認的門牌號碼」部分。
接受地址

如果客戶未回應提示，建議您允許系統接受原始項目。

在這些情況下，客戶可能輸入的地址不在系統內，例如新建築建造的地址。
提供意見

當您重新發出地址驗證要求時，您也可以向 provideValidationFeedback 端點傳送要求。

讓 Google 瞭解最終如何處理最終回覆。 請參閱「處理更新後的地址」。

修正地址

在結果明確指出無法配送的地址時修正地址。接著，您的系統可以提示客戶提供必要資訊，接著您會重新發出工作流程，以取得可交付的地址。

修正信號

Address Validation API 提供多項信號，協助您瞭解是否應修正地址。

1. 驗證精細程度和缺少的元件

下列兩種信號最能判斷有問題的地址：

  • 只要 validationGranularity 欄位為 OTHER，系統都應該調查地址元件信號，進一步瞭解發生錯誤的位置和修正方式。
  • 每次處理後處理的 address 物件傳回 missingComponentTypes 欄位時，系統應檢查該元件。如果缺少元件，則會導致地址不完整，無法送達。

2. 其他指標

Address Validation API 也提供其他信號，可協助診斷特定問題：

可疑元件 如果元件的確認等級列舉為 UNCOMFIRMED_AND_SUSPICIOUS，表示元件可能有誤。
未解析的元件 unresolvedToken 是輸入的一部分，無法識別是位址的有效部分。

3. 美國地址信號

某些僅適用於美國地址的欄位可做為有用的信號，指出地址無法配送，且應修正。如果是需要修正的位址，您應該會看到以下內容：

dpvConfirmation N、D 或空白。

如要進一步瞭解 dpvConfirmation，請參閱「處理美國地址」。

修正地址示例

確認地址

當判定結果指出 Address Validation API 是推論或變更地址元件，以便產生已驗證的地址時，您會確認地址。在這些情況下，您有一個可交付的地址，但最好確認所找到的地址是客戶預期的地址。

為了讓客戶取得正確的提示，您的邏輯會辨識服務加上標記的元件，判斷要套用至元件的動作或標記 API，例如 inferred、replaced 或 spellCorrected。請參閱參考資料中的 AddressComponent。

確認信號

Address Validation API 提供多種信號，有助您瞭解是否應確認地址。

1. 驗證精細程度

可以將 validationGranularity 設為 ROUTE 以上，但 PREMISE 或 SUBPREMISE 可以更準確地顯示交付項目。

2. 其他指標

決定向客戶確認地址項目時，判定結果還提供下列資訊，協助您決定要調查的元件：

推測資料 如果 hasInferredComponents 欄位為 true，就表示 API 已填入從其他地址元件收集的資訊。
替換的資料 當 hasReplacedComponents 欄位為 true 時，API 會將輸入的資料替換為使地址有效的資料。

3. 美國地址信號

某些僅適用於美國地址的欄位指出，您的邏輯應向客戶確認詳細資料。符合下列其中一項條件：

dpvConfirmation S

如要進一步瞭解 dpvConfirmation，請參閱「處理美國地址」一文。
地址回應 包含值為 subpremise 的 missingComponentType 欄位。

確認地址範例

接受地址

當判定結果非常有信心，表示位址可以遞送，而且在下游程序中不需要客戶進一步互動就能使用，您接受地址。

接受信號

Address Validation API 提供多種信號，有助您瞭解是否應確認地址。

1. 驗證精細程度

可以將 validationGranularity 設為 PREMISE 以上，但在某些情況下，ROUTE 仍表示可交付的位址。

2. 其他指標

高品質地址的判定結果也應提供以下資訊：

  • 沒有替換的資料。在本例中：hasReplacedComponents: FALSE。
  • 沒有推論元件。在本例中：hasInferredComponents: FALSE。

3. 美國地址信號

某些僅適用於美國地址的欄位表示可送達的高品質地址。如果是可接受的美國地址，您應該會看到：

dpvConfirmation Y

如要進一步瞭解 dpvConfirmation，請參閱「處理美國地址」一文。

接受地址範例

上一頁
瞭解基本回應