通过

验证地址

适用于：合作伙伴中心 |由世纪互联运营的合作伙伴中心 |美国政府Microsoft云合作伙伴中心

本文介绍如何使用地址验证 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 标头。

请求主体

下表说明了请求正文中的必需属性。

名称 类型 必填* 说明
地址行1 字符串 Y 地址的第一行。
地址栏2 字符串 N 地址的第二行。 此属性是可选的。
city 字符串 Y 城市。
状态 字符串 Y 省/市/自治区。
邮政编码 字符串 Y 邮政编码。
国家 字符串 Y 双字符 ISO alpha-2 国家/地区代码。

* 必需属性可能会根据国家或地区更改。

响应详细信息

响应返回以下状态消息之一。 如果状态响应不是验证或可验证装运，请查看您的输入地址和/或建议地址。 由呼叫方决定为客户选择最合适的地址。

地位 说明 返回的建议地址数 状态响应建议
已验证可交付 地址已验证并可以寄送到。 Single 继续处理已验证的地址。
Verified 地址已验证。 Single 继续处理已验证的地址。
需要交互 建议的地址已显著更改，需要用户确认。 Single 继续处理用户确认的地址。
街道部分 地址中的给定街道是部分的，需要更多信息。 多个，最多 3 个 继续处理用户确认的地址。
现场部分 所提供的场地信息（建筑物编号、套件号等信息）是不完整的，需要更多信息。 多个，最多 3 个 继续处理用户确认的地址。
Multiple 地址中存在多个不完整字段（可能还包括街道部分和建筑物部分）。 多个，最多 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'"
}
  • Last updated on