Convalidare un indirizzo

Articolo
07/11/2024

Si applica a: Centro per i partner | Centro per i partner gestito da 21Vianet | Centro per i partner per Microsoft Cloud per il governo degli Stati Uniti

Questo articolo illustra come convalidare un indirizzo usando l'API di convalida degli indirizzi.

L'API di convalida degli indirizzi deve essere usata solo per la prevalida degli aggiornamenti del profilo cliente. In base allo stato della risposta dell'API, il chiamante deve scegliere l'indirizzo più appropriato per il cliente.

Prerequisiti

Credenziali descritte in Autenticazione del Centro per i partner. Questo scenario supporta l'autenticazione con le credenziali app autonome e App+Utente.

C#

Per convalidare un indirizzo, creare prima di tutto un'istanza di un nuovo oggetto Address e popolarlo con l'indirizzo da convalidare. Recuperare quindi un'interfaccia per le operazioni Validations dalla proprietà IAggregatePartner.Validations e chiamare il metodo IsAddressValid con l'oggetto address.

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();
}

Richiesta REST

Sintassi della richiesta

metodo	URI della richiesta
POST	{baseURL}/v1/validations/address HTTP/1.1

Intestazioni delle richieste

Per altre informazioni, vedi Intestazioni REST del Centro per i partner.

Corpo della richiesta

Questa tabella descrive le proprietà necessarie nel corpo della richiesta.

Nome	Type	Obbligatorio*	Descrizione
addressline1	string	Y	Prima riga dell'indirizzo.
addressline2	string	N	Seconda riga dell'indirizzo. Questa proprietà è facoltativa.
city	string	Y	La città.
state	string	Y	Stato.
postalcode	string	Y	Il CAP.
country	string	Y	Codice paese ISO a due caratteri alfabetici.

* Le proprietà obbligatorie possono cambiare in base al paese o all'area geografica.

Dettagli risposta

La risposta restituisce uno dei messaggi di stato seguenti. Se la risposta di stato non è Verificata o VerifiedShippable, esaminare l'indirizzo immesso e/o l'indirizzo suggerito. Spetta al chiamante scegliere l'indirizzo più appropriato per il cliente.

Stato	Descrizione	Numero di indirizzi suggeriti restituiti	Raccomandazione sulla risposta allo stato
Spedizione verificata	L'indirizzo viene verificato e può essere spedito a.	Singola	Procedere con l'indirizzo verificato.
Verificato	L'indirizzo viene verificato.	Singola	Procedere con l'indirizzo verificato.
Interazione necessaria	L'indirizzo suggerito viene modificato in modo significativo e richiede la conferma dell'utente.	Singola	Procedere con l'indirizzo confermato dall'utente.
Parziale della strada	La strada specificata nell'indirizzo è parziale e necessita di maggiori informazioni.	Multiplo: massimo tre	Procedere con l'indirizzo confermato dall'utente.
Parziale locale	I locali specificati (numero di edificio, numero di suite e altri) sono parziali e necessitano di altre informazioni.	Multiplo: massimo tre	Procedere con l'indirizzo confermato dall'utente.
Multipla	Ci sono più campi parziali nell'indirizzo (potenzialmente anche parziale della strada e locale parziale).	Multiplo: massimo tre	Procedere con l'indirizzo confermato dall'utente.
None	L'indirizzo non è corretto.	None	Procedere con l'indirizzo confermato dall'utente.
Non convalidato	L'indirizzo non è stato in grado di essere inviato tramite il processo di convalida.	None	Procedere con l'indirizzo confermato dall'utente.

Esempio di richiesta

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

Risposta REST

Se ha esito positivo, il metodo restituisce un oggetto AddressValidationResponse nel corpo della risposta, con un codice di stato HTTP 200 . Esempio:

Codici di errore e di esito della risposta

Ogni risposta viene fornita con un codice di stato HTTP che indica l'esito positivo o negativo e le informazioni di debug. Usare uno strumento di traccia di rete per leggere questo codice, il tipo di errore e altri parametri. Per l'elenco completo, vedi Codici di errore REST del Centro per i partner.

Risposta di esempio

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

Condividi tramite