Поделиться через


Проверка адреса

применимо к: Центр партнеров | Центр партнеров, управляемый 21Vianet | Центр партнеров для Microsoft Cloud для государственных организаций США

В этой статье объясняется, как проверить адрес с помощью API проверки адресов.

API проверки адресов следует использовать только для предварительной оценки обновлений профиля клиента. В зависимости от состояния ответа API вызывающая сторона должна выбрать наиболее подходящий адрес для клиента.

Необходимые условия

Учетные данные, как описано в аутентификации Центра партнеров. Этот сценарий поддерживает аутентификацию с использованием как автономных учетных данных приложения, так и совместных учетных данных приложения и пользователя.

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 струна У Первая строка адреса.
адресная линия2 струна N Вторая строка адреса. Это свойство является необязательным.
город струна Y Город.
государство струна Y Государство.
почтовый индекс струна Y Почтовый индекс.
страна струна Y Код страны ISO-альфа-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'"
}