Memvalidasi alamat

Artikel
03/08/2025

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

Bagikan melalui