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

Статья
07/11/2024

Область применения: Центр партнеров | Центр партнеров, управляемый 21Vianet | Центр партнеров для Microsoft Cloud for US Government

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

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

Необходимые компоненты

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

C#

Чтобы проверить адрес, сначала создайте экземпляр нового объекта Address и заполните его адресом для проверки. Затем получите интерфейс для операций Validations из свойства 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 Центра партнеров.

Текст запроса

В этой таблице описываются необходимые свойства в тексте запроса.

Имя.	Тип	Обязательно*	Description
addressline1	строка	Y	Первая строка адреса.
addressline2	строка	N	Вторая строка адреса. Это необязательное свойство.
city	string	Y	Город.
state	string	Y	Состояние.
postalcode	строка	Y	Почтовый индекс.
country	string	Y	Двухсимвольный код страны ISO alpha-2.

* Обязательные свойства могут изменяться в зависимости от страны или региона.

Сведения об ответе

Ответ возвращает одно из следующих сообщений о состоянии. Если ответ состояния не проверен или проверен, просмотрите введенный адрес и (или) предлагаемый адрес. Это до вызывающего абонента, чтобы выбрать наиболее подходящий адрес для клиента.

Состояние	Description	Число возвращаемых предложенных адресов	Рекомендация по ответу на состояние
Адрес доставки проверен	Адрес проверен и готов к отправке.	Одна	Продолжайте с проверенным адресом.
Проверено	Адрес проверен.	Одна	Продолжайте с проверенным адресом.
Требуется взаимодействие	Рекомендуемый адрес значительно изменился и требует подтверждения пользователя.	Одна	Продолжайте использовать подтвержденный адрес пользователя.
Неполное название улицы	В адресе указано неполное название улицы. Требуются дополнительные сведения.	Несколько (не более трех)	Продолжайте использовать подтвержденный адрес пользователя.
Неполные сведения о здании	Указаны неполные сведения о здании (номер дома, номер квартиры и т. д.). Требуется дополнительная информация.	Несколько (не более трех)	Продолжайте использовать подтвержденный адрес пользователя.
Несколько	В нескольких полях адреса указаны неполные сведения (возможно, в том числе название улицы и сведения о здании).	Несколько (не более трех)	Продолжайте использовать подтвержденный адрес пользователя.
нет	Неверный адрес.	нет	Продолжайте использовать подтвержденный адрес пользователя.
Не проверяется	Адрес не удалось отправить через процесс проверки.	нет	Продолжайте использовать подтвержденный адрес пользователя.

Пример запроса

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

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