驗證位址

發行項
04/11/2024

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

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

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

必要條件

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

C#

若要驗證位址，請先具現化新的 Address 對象，然後填入要驗證的位址。然後，從 IAggregatePartner.Validations 屬性擷取 Validations 作業的介面，並使用 address 物件呼叫 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	字串	Y	地址的第一行。
addressline2	字串	否	地址的第二行。這個屬性為選擇性。
市/鎮	字串	Y	市/鎮。
state	字串	Y	州。
postalcode	字串	Y	郵遞區號。
國家/地區	字串	Y	雙字元 ISO alpha-2 國家/地區代碼。

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

回覆詳細資料

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

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

要求範例

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

共用方式為