验证地址

项目
04/11/2024

适用于：合作伙伴中心 | 由世纪互联运营的合作伙伴中心 | 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: 29624f3c-90cb-4d34-a7e9-bd2de6d35218
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: 2c95c9bc-fdfb-4c6a-84f4-57c9b0826b43
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: 29624f3c-90cb-4d34-a7e9-bd2de6d35218
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: 2c95c9bc-fdfb-4c6a-84f4-57c9b0826b43
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'"
}

通过