此页面由 Cloud Translation API 翻译。

构建验证逻辑

本文档介绍了构建地址检查系统以处理 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.

具体逻辑取决于您的具体情况 - 如需了解详情，请参阅实现指南。您还可以使用我们对此逻辑的开源实现，该实现位于扩展组件库中。

工作流程概览

下表总结了系统的两项操作：

要使用的工作流，基于修复、确认、接受行为。
要从响应中检查的第一个信号。此处所述的信号来自 verdict 属性，并非唯一需要检查的信号，但却提供了地址质量的初始指示。每种行为类型都对应于本文档中的某个部分，其中介绍了您可能还需要调查的其他信号。

您的系统行为

修正地址

verdict 的响应会指明缺少的重要信息，您应提供这些信息。Address Validation API 返回的地址可能不符合提交要求。

工作流程

必要时调查地址组成部分。
提示客户修正地址问题。
请求验证更新后的地址。
（可选）向该 API 的反馈端点发送请求。请参阅处理更新后的地址。
继续填写地址。

判定信号

符合以下任一条件：

将 validationGranularity 设置成了 OTHER。请参阅粒度值。
addressComplete 为 false。

确认地址

verdict 的响应指明了可投放的地址，但对原始输入进行了更改：推断出拼写已更正的数据或可确认的数据。

工作流程

需要更正：
1. 如有必要，调查地址组成部分。
2. 请求验证更新后的地址。
3. （可选）向 API 的反馈端点发送请求。请参阅处理更新后的地址。
4. 继续填写地址。
无需更正：

（可选）向 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 会返回各种信号，您可以将这些信号与风险级别结合使用，以优化验证流程。

例如，如果地址包含未经确认的门牌号，您仍然可以接受它。另一方面，如果您的业务运营需要更精确的地址信息，您可以提示用户。如需查看可能属于这两类中的任一类别的示例，请参阅接受地址 - 示例中的非美国未经确认的街道号。

接受地址

最好让系统在客户不响应提示时接受原始条目。

在这些情况下，客户可能输入了系统中不存在的地址，例如新建建筑物的地址。

提供反馈

重新发出地址验证请求时，您还可以向 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` 字段。注意：如果该字段包含 `subpremise` 以外的类型，相应操作将属于“更正地址”类别。请参阅地理编码文档中的地址类型完整列表。

确认地址示例

接受地址

如果判定结果高度可信地表明地址可送达且可以在下游流程中使用，无需进一步与客户互动，您就可以接受该地址。

接受信号

Address Validation API 提供了一些信号，可让您了解是否应确认地址。

1. 验证粒度

validationGranularity 为 PREMISE 或更高值是可接受的，但在某些情况下，ROUTE 仍表示可投放的地址。

2. 其他信号

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

无替换数据。在此示例中为 hasReplacedComponents: FALSE。
没有推断出的组件。在此示例中为 hasInferredComponents: FALSE。

3. 美国地址信号

仅适用于美国地址的某些字段可指明可配送的优质地址。如果您提供的美国地址符合要求，您应该会看到以下内容：

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

接受的地址示例

了解基本回复