Проверка адреса
применимо к: Центр партнеров | Центр партнеров, управляемый 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'"
}