验证地址
适用于:合作伙伴中心 | 由世纪互联运营的合作伙伴中心 | Microsoft Cloud for US Government 合作伙伴中心
本文介绍如何使用地址验证 API 验证地址。
地址验证 API 应仅用于预验证客户配置文件更新。 根据 API 响应状态,调用方应为客户选择最合适的地址。
先决条件
合作伙伴中心身份验证中所述的凭据。 此方案支持使用独立应用和 App+User 凭据进行身份验证。
C#
若要验证地址,请先实例化新的 Address 对象,并使用要验证的地址填充该地址。 然后,从 IAggregatePartner.Validations 属性检索验证操作的接口,并使用地址对象调用 IsAddressValid 方法。
IAggregatePartner partnerOperations;
// Create an address to validate.
Address address = new Address()
{
AddressLine1 = "One Microsoft Way",
City = "Redmond",
State = "WA",
PostalCode = "98052",
Country = "US"
};
// Validate the address.
AddressValidationResponse result = partnerOperations.Validations.IsAddressValid(address);
// If the request completes successfully, you can inspect the response object.
// See the status of the validation.
Console.WriteLine($"Status: {addressValidationResult.Status}");
// See the validation message returned.
Console.WriteLine($"Validation Message Returned: {addressValidationResult.ValidationMessage ?? "No message returned."}");
// See the original address submitted for validation.
Console.WriteLine($"Original Address:\n{this.DisplayAddress(addressValidationResult.OriginalAddress)}");
// See the suggested addresses returned by the API, if any exist.
Console.WriteLine($"Suggested Addresses Returned: {addressValidationResult.SuggestedAddresses?.Count ?? "None."}");
if (addressValidationResult.SuggestedAddresses != null && addressValidationResult.SuggestedAddresses.Any())
{
addressValidationResult.SuggestedAddresses.ForEach(a => Console.WriteLine(this.DisplayAddress(a)));
}
// Helper method to pretty-print an Address object.
private string DisplayAddress(Address address)
{
StringBuilder sb = new StringBuilder();
foreach (var property in address.GetType().GetProperties())
{
sb.AppendLine($"{property.Name}: {property.GetValue(address) ?? "None to Display."}");
}
return sb.ToString();
}
REST 请求
请求语法
方法 | 请求 URI |
---|---|
POST | {baseURL}/v1/validations/address HTTP/1.1 |
请求标头
有关详细信息,请参阅合作伙伴中心 REST 标头。
请求正文
下表描述了请求正文中的必需属性。
名称 | 类型 | 必填* | 说明 |
---|---|---|---|
addressline1 | string | Y | 地址的第一行。 |
addressline2 | string | N | 地址的第二行。 此属性是可选的。 |
city | string | Y | 城市。 |
state | string | Y | 状态。 |
postalcode | string | Y | 邮政编码。 |
country | string | Y | 两字符的 ISO alpha-2 国家/地区代码。 |
* 必需属性可能会根据国家或地区更改。
响应详细信息
响应返回以下状态消息之一。 如果未验证或 VerifiedShippable 状态响应,请查看输入的地址和/或建议的地址。 由呼叫方决定为客户选择最合适的地址。
状态 | 说明 | 返回的建议地址数 | 状态响应建议 |
---|---|---|---|
Verified shippable | 地址已经过验证且可送达。 | Single | 继续执行已验证的地址。 |
已验证 | 已验证地址。 | Single | 继续执行已验证的地址。 |
Interaction required | 建议的地址已显著更改,需要用户确认。 | Single | 继续处理用户确认的地址。 |
Street partial | 地址中给出的街道信息不完整,需要更多信息。 | 多个 - 最多 3 个 | 继续处理用户确认的地址。 |
Premises partial | 给出的场所信息(楼栋号、房号等)不完整,需要更多信息。 | 多个 - 最多 3 个 | 继续处理用户确认的地址。 |
多个 | 地址中有多个字段不完整(也可能包括 street partial 和 premises partial)。 | 多个 - 最多 3 个 | 继续处理用户确认的地址。 |
无 | 地址错误。 | 无 | 继续处理用户确认的地址。 |
未验证 | 地址无法通过验证过程发送。 | 无 | 继续处理用户确认的地址。 |
请求示例
# "VerifiedShippable" Request Example
POST https://api.partnercenter.microsoft.com/v1/validations/address HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <token>
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
MS-RequestId: eb55c2b8-6f4b-4b44-9557-f76df624b8c0
Host: api.partnercenter.microsoft.com
Content-Length: 137
X-Locale: en-US
{
"AddressLine1": "1 Microsoft Way",
"City": "Redmond",
"State": "WA",
"PostalCode": "98052",
"Country": "US"
}
# "StreetPartial" Request Example
POST https://api.partnercenter.microsoft.com/v1/validations/address HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <token>
MS-CorrelationId: bbbb1111-cc22-3333-44dd-555555eeeeee
MS-RequestId: ee6cf74c-3ab5-48d6-9269-4a4b75bd59dc
Host: api.partnercenter.microsoft.com
Content-Length: 135
X-Locale: en-US
{
"AddressLine1": "Microsoft Way",
"City": "Redmond",
"State": "WA",
"PostalCode": "98052",
"Country": "US"
}
REST 响应
如果成功,该方法在响应正文中返回 AddressValidationResponse 对象,其状态代码为 HTTP 200 。 示例如下。
响应的成功和错误代码
每个响应都附带一个 HTTP 状态代码,用于指示成功或失败和调试信息。 使用网络跟踪工具读取此代码、错误类型和其他参数。 如需完整列表,请参阅合作伙伴中心 REST 错误代码。
响应示例
# "VerifiedShippable" Response Example
HTTP/1.1 200 OK
Date: Mon, 17 May 2021 23:19:19 GMT
Content-Type: application/json; charset=utf-8
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
MS-RequestId: eb55c2b8-6f4b-4b44-9557-f76df624b8c0
X-Locale: en-US
{
"originalAddress": {
"country": "US",
"city": "Redmond",
"state": "WA",
"addressLine1": "1 Microsoft Way",
"postalCode": "98052"
},
"suggestedAddresses": [
{
"country": "US",
"city": "Redmond",
"state": "WA",
"addressLine1": "1 Microsoft Way",
"postalCode": "98052-8300"
}
],
"status": "VerifiedShippable"
}
# "StreetPartial" Response Example
HTTP/1.1 200 OK
Date: Mon, 17 May 2021 23:34:08 GMT
Content-Type: application/json; charset=utf-8
MS-CorrelationId: bbbb1111-cc22-3333-44dd-555555eeeeee
MS-RequestId: ee6cf74c-3ab5-48d6-9269-4a4b75bd59dc
X-Locale: en-US
{
"originalAddress": {
"country": "US",
"city": "Redmond",
"state": "WA",
"addressLine1": "Microsoft Way",
"postalCode": "98052"
},
"suggestedAddresses": [
{
"country": "US",
"city": "Redmond",
"state": "WA",
"addressLine1": "1 Microsoft Way",
"postalCode": "98052-6399"
}
],
"status": "StreetPartial",
"validationMessage": "Address field invalid for property: 'Region', 'PostalCode', 'City'"
}