构建验证逻辑

本文档介绍了构建地址检查系统以处理来自 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 返回的地址可能不具有交付质量。 工作流程 如有必要，请检查地址组成部分。 提示客户解决地址问题。 请求验证更新后的地址。 （可选）向该 API 的反馈端点发送请求。 请参阅处理更新后的地址。 继续输入地址。 判定信号 满足以下任何要求： validationGranularity 设置为 OTHER。 请参阅粒度值。 addressComplete 为 false。
确认地址	来自 verdict 的响应表示一个可递送地址，但对原始输入进行了更改：推断拼写正确的数据或可以确认的数据。 工作流程 需要更正的问题： 如有必要，请检查地址组成部分。 请求验证更新后的地址。 （可选）向该 API 的反馈端点发送请求。 请参阅处理更新后的地址。 继续输入地址。 无需更正： （可选）向该 API 的反馈端点发送请求。 请参阅处理更新后的地址。 继续输入地址。 判定信号 以下所有选项均适用： 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 演示中输入这些示例的结果，以浏览这些示例。

修正地址

当结果明确表明某个地址无法送达时，修正某个地址。然后，您的系统可以提示用户提供必要的信息，之后您将重新发出工作流以获取可交付地址。

注意 ：当您针对同一地址重复向 Address Validation API 发出请求时，可以调用 provideValidationFeedback 来指示结果。请参阅处理美国地址。

修正信号

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 重新发出请求，则可以调用 provideValidationFeedback 来指示结果。请参阅处理更新后的地址。

确认信号

Address Validation API 会提供多种信号，让您知道是否应确认某个地址。

1. 验证粒度

validationGranularity 为 ROUTE 或更优值是可以接受的，但 PREMISE 或 SUBPREMISE 可提供更强的传递性信号。

2. 其他信号

在决定与客户确认地址输入时，判定结果还会提供以下信息，以确定要调查哪些部分：

推断的数据	如果 hasInferredComponents 字段为 true，则表示 API 填充了从其他地址组成部分收集的信息。
已替换的数据	当 hasReplacedComponents 字段为 true 时，API 会将输入的数据替换为它认为使地址有效的数据。

3. 美国地址信号

某些仅适用于美国地址的字段表示您的逻辑应向客户确认详细信息。以下两种情况之一：

dpvConfirmation	S 如需详细了解 dpvConfirmation，请参阅处理美国地址。
地址响应	包含值为 subpremise 的 missingComponentType 字段。 注意：如果该字段包含 subpremise 以外的类型，则相应操作将属于修正地址类别。如需查看完整的地址类型列表，请参阅地理编码文档。

确认地址示例

接受地址

如果认定结果高度可信，认为该地址可以送达，并且无需客户进一步互动，即可在下游流程中使用，此时您就可以接受该地址。

接受信号

Address Validation API 会提供多种信号，让您知道是否应确认某个地址。

1. 验证粒度

我们接受 validationGranularity 为 PREMISE 或更高的值，但在某些情况下，ROUTE 仍表示一个可递送地址。

2. 其他信号

优质地址的判定结果还应提供以下信息：

• 没有已替换的数据。在此示例中为 hasReplacedComponents: FALSE。
• 没有任何推断的组件。在此示例中为 hasInferredComponents: FALSE。

3. 美国地址信号

某些仅适用于美国地址的字段表示可以送货的高品质地址。如需查看可接受的美国地址，您应该会看到以下内容：

dpvConfirmation	Y 如需详细了解 dpvConfirmation，请参阅处理美国地址。

接受地址示例