Memvalidasi alamat
Berlaku untuk: Pusat Mitra | Pusat Mitra yang dioperasikan oleh 21Vianet | Pusat Mitra untuk Microsoft Cloud untuk Pemerintah AS
Artikel ini menjelaskan cara memvalidasi alamat menggunakan API validasi alamat.
API validasi alamat hanya boleh digunakan untuk prevalidasi pembaruan profil pelanggan. Berdasarkan status respons API, pemanggil harus memilih alamat yang paling tepat untuk pelanggan.
Prasyarat
Kredensial seperti yang dijelaskan dalam autentikasi Pusat Mitra. Skenario ini mendukung autentikasi dengan kredensial Aplikasi mandiri dan Aplikasi+Pengguna.
C#
Untuk memvalidasi alamat, pertama-tama buat objek Alamat baru dan isi dengan alamat untuk divalidasi. Kemudian, dapatkan antarmuka untuk operasi Validasi dari properti IAggregatePartner.Validations, dan panggil metode IsAddressValid dengan menggunakan objek alamat.
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();
}
Permintaan REST
Sintaksis permintaan
Metode | Meminta URI |
---|---|
POST | {baseURL}/v1/validations/address HTTP/1.1 |
Header permintaan
Untuk informasi selengkapnya, lihat header REST Pusat Mitra di .
Isi permintaan
Tabel ini menjelaskan properti yang diperlukan dalam isi permintaan.
Nama | Jenis | Diperlukan* | Deskripsi |
---|---|---|---|
garis alamat1 | tali | Y | Baris pertama alamat. |
alamat baris 2 | string | N | Baris kedua alamat. Properti ini bersifat opsional. |
kota | string | Y | Kota ini. |
negara | tali | Y | Negara |
kode pos | tali | Y | Kode pos. |
negara | string | Y | Kode negara ISO alpha-2 dua karakter. |
* Properti yang diperlukan dapat berubah berdasarkan negara atau wilayah.
Detail-detail tanggapan
Respons mengembalikan salah satu pesan status berikut. Jika respons status tidak Terverifikasi atau VerifiedShippable, tinjau alamat yang Anda masukkan dan/atau alamat yang disarankan. Terserah pemanggil untuk memilih alamat yang paling tepat untuk pelanggan.
Keadaan | Deskripsi | Jumlah alamat yang disarankan yang dikembalikan | Rekomendasi respons status |
---|---|---|---|
Terverifikasi dapat dikirim | Alamat diverifikasi dan dapat dikirim. | Satu | Lanjutkan dengan alamat terverifikasi. |
Diverifikasi | Alamat diverifikasi. | Tunggal | Lanjutkan dengan alamat terverifikasi. |
Interaksi diperlukan | Alamat yang disarankan diubah secara signifikan dan memerlukan konfirmasi pengguna. | Tunggal | Lanjutkan dengan alamat yang dikonfirmasi pengguna. |
Jalan Parsial | Jalan yang diberikan di alamat bersifat parsial dan membutuhkan lebih banyak info. | Banyak—maksimal tiga | Lanjutkan dengan alamat yang dikonfirmasi pengguna. |
Lokasi parsial | Tempat yang diberikan (nomor bangunan, nomor rangkaian, dan lainnya) bersifat parsial dan memerlukan info lebih lanjut. | Beberapa—maksimum tiga | Lanjutkan dengan alamat yang dikonfirmasi pengguna. |
Beberapa | Ada beberapa elemen yang sebagian dalam alamat (berpotensi juga termasuk sebagian jalan dan sebagian gedung). | Beberapa—maksimum tiga | Lanjutkan dengan alamat yang dikonfirmasi pengguna. |
Tidak | Alamat salah. | Tidak | Lanjutkan dengan alamat yang dikonfirmasi pengguna. |
Tidak divalidasi | Alamat tidak dapat dikirim melalui proses validasi. | Tidak | Lanjutkan dengan alamat yang dikonfirmasi pengguna. |
Contoh permintaan
# "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"
}
Respons REST
Jika berhasil, metode mengembalikan objek AddressValidationResponse dalam isi respons, dengan kode status HTTP 200. Contoh berikut.
Kode kesalahan dan keberhasilan respons
Setiap respons dilengkapi dengan kode status HTTP yang menunjukkan informasi keberhasilan atau kegagalan dan penelusuran kesalahan. Gunakan alat pelacakan jaringan untuk membaca kode ini, jenis kesalahan, dan parameter lainnya. Untuk daftar lengkapnya, lihat kode kesalahan REST di Pusat Mitra .
Contoh respons
# "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'"
}