Memvalidasi alamat

Artikel
07/11/2024

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, ambil antarmuka ke operasi Validasi dari properti IAggregatePartner.Validations , dan panggil metode IsAddressValid dengan 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

Minta sintaks

Metode	URI Permintaan
POST	{baseURL}/v1/validations/address HTTP/1.1

Header permintaan

Untuk informasi selengkapnya, lihat Header REST Pusat Mitra.

Isi permintaan

Tabel ini menjelaskan properti yang diperlukan dalam isi permintaan.

Nama	Tipe	Diperlukan*	Deskripsi
garis alamat1	string	Y	Baris pertama alamat.
addressline2	string	N	Baris kedua alamat. Properti ini bersifat opsional.
kota	string	Y	Kota.
state	string	Y	Negara bagian.
kodepos	string	Y	Kode pos.
negara	string	Y	Kode negara ISO alpha-2 dua karakter.

* Properti yang diperlukan dapat berubah berdasarkan negara atau wilayah.

Detail respons

Respons mengembalikan salah satu pesan status berikut. Jika respons status tidak Diverifikasi atau Dapat Diverifikasi, 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
Dapat dikirim terverifikasi	Alamat diverifikasi dan dapat dikirim.	Tunggal	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.
Parsial jalan	Jalan yang diberikan di alamat bersifat parsial dan membutuhkan lebih banyak info.	Beberapa—maksimum tiga	Lanjutkan dengan alamat yang dikonfirmasi pengguna.
Parsial lokal	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 bidang yang parsial dalam alamat (berpotensi juga termasuk parsial jalan dan parsial lokal).	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 . Contohnya adalah sebagai 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 Pusat Mitra.

Contoh tanggapan

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