驗證位址

發行項
03/07/2025

適用於：合作夥伴中心 |由 21Vianet 營運的合作夥伴中心 |美國政府Microsoft雲端合作夥伴中心

本文說明如何使用地址驗證 API 來驗證位址。

地址驗證 API 只能用於客戶配置檔更新的預先驗證。根據 API 回應狀態，呼叫端應選擇最適合客戶的位址。

先決條件

合作夥伴中心驗證中描述的憑證。此案例支援使用獨立應用程式和 App+使用者認證進行驗證。

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 標頭。

請求正文

下表描述請求主體中的必要屬性。

名字	類型	必填*	描述
地址行一	字串	Y	位址的第一行。
地址行2	字串	N	位址的第二行。這個屬性是選擇性的。
城市	字串	Y	城市。
州	字串	Y	國家。
郵遞區號	字串	Y	郵遞區號。
國家	字串	Y	雙字元 ISO alpha-2 國家/地區代碼。

* 必要的屬性可能會根據國家或地區變更。

回應詳細數據

回應會傳回下列其中一個狀態消息。如果狀態回應不是已驗證或已驗證可出貨，請檢閱您輸入的位址和/或建議的位址。由來電者決定為客戶選擇最適當的位址。

地位	描述	傳回的建議位址數目	狀態回應建議
已驗證可出貨	位址已驗證且可寄送至。	單	使用已驗證的地址繼續進行。
驗證	地址已驗證。	單	請繼續使用已驗證的地址。
必須進行互動	建議的位址會大幅變更，而且需要用戶確認。	單身	繼續進行使用者確認的位址。
街道部分	位址中的指定街道是部分的，需要更多資訊。	多重 -- 最多三個	繼續進行使用者確認的位址。
場地部分	指定的地址（建築編號、套件號碼和其他）資料不完整，需要更多資訊。	多個—最多三個	請繼續使用者已確認的地址進行操作。
倍數	位址中有多個不完整的欄位（可能還包括街道不完整部分和單位不完整部分）。	多重——最多三個	繼續使用已確認的用戶地址。
沒有	位址不正確。	沒有	使用者確認後的地址繼續進行。
未驗證	位址無法透過驗證程式傳送。	沒有	請繼續使用經使用者確認的地址。

要求範例

# "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'"
}

共用方式為