Bagikan melalui


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