共用方式為


驗證位址

適用於:合作夥伴中心 |由 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'"
}