Weryfikowanie adresu

Artykuł
07/11/2024

Dotyczy: Centrum partnerskie | Centrum partnerskie obsługiwane przez firmę 21Vianet | Centrum partnerskie dla chmury firmy Microsoft dla instytucji rządowych USA

W tym artykule wyjaśniono, jak zweryfikować adres przy użyciu interfejsu API weryfikacji adresów.

Interfejs API sprawdzania poprawności adresów powinien być używany tylko do prewalidacji aktualizacji profilu klienta. Na podstawie stanu odpowiedzi interfejsu API obiekt wywołujący powinien wybrać najbardziej odpowiedni adres dla klienta.

Wymagania wstępne

Poświadczenia zgodnie z opisem w temacie Uwierzytelnianie w Centrum partnerskim. Ten scenariusz obsługuje uwierzytelnianie zarówno przy użyciu autonomicznych poświadczeń aplikacji, jak i aplikacji i użytkownika.

C#

Aby zweryfikować adres, najpierw utwórz wystąpienie nowego obiektu Address i wypełnij go adresem w celu zweryfikowania. Następnie pobierz interfejs do operacji Validations z właściwości IAggregatePartner.Validations i wywołaj metodę IsAddressValid z obiektem 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();
}

Żądanie REST

Składnia żądania

Method	Identyfikator URI żądania
POST	{baseURL}/v1/validations/address HTTP/1.1

Nagłówki żądań

Aby uzyskać więcej informacji, zobacz Nagłówki REST Centrum partnerskiego.

Treść żądania

W tej tabeli opisano wymagane właściwości w treści żądania.

Nazwisko	Typ	Wymagane*	opis
addressline1	string	Y	Pierwszy wiersz adresu.
Addressline2	string	N	Drugi wiersz adresu. Ta właściwość jest opcjonalna.
miejscowość	string	Y	Miejscowość.
stan	string	Y	Stan.
Postalcode	string	Y	Kod pocztowy.
kraj	string	Y	Dwuznaczny kod kraju ISO alfa-2.

* Wymagane właściwości mogą ulec zmianie w zależności od kraju lub regionu.

Szczegóły odpowiedzi

Odpowiedź zwraca jeden z następujących komunikatów o stanie. Jeśli odpowiedź o stanie nie jest zweryfikowana lub zweryfikowana, przejrzyj wprowadzony adres i/lub sugerowany adres. Do rozmówców należy wybrać najbardziej odpowiedni adres dla klienta.

Stan	opis	Liczba zwróconych sugerowanych adresów	Zalecenie dotyczące odpowiedzi na stan
Zweryfikowano wysyłkę	Adres jest weryfikowany i można go wysłać.	Pojedynczy	Przejdź do zweryfikowanego adresu.
Zweryfikowano	Adres jest weryfikowany.	Pojedynczy	Przejdź do zweryfikowanego adresu.
Wymagana interakcja	Sugerowany adres jest znacznie zmieniony i wymaga potwierdzenia użytkownika.	Pojedynczy	Przejdź do adresu potwierdzonego przez użytkownika.
Częściowa ulica	Dana ulica w adresie jest częściowa i potrzebuje więcej informacji.	Wielokrotność — maksymalnie trzy	Przejdź do adresu potwierdzonego przez użytkownika.
Częściowe lokalne	Podane lokale (numer budynku, numer apartamentu i inne) są częściowe i wymagają dodatkowych informacji.	Wielokrotność — maksymalnie trzy	Przejdź do adresu potwierdzonego przez użytkownika.
Wiele	Istnieje wiele pól, które są częściowe w adresie (potencjalnie dotyczy to również częściowych ulic i częściowych pomieszczeń).	Wielokrotność — maksymalnie trzy	Przejdź do adresu potwierdzonego przez użytkownika.
Brak	Adres jest niepoprawny.	Brak	Przejdź do adresu potwierdzonego przez użytkownika.
Nie zweryfikowano	Nie można wysłać adresu za pośrednictwem procesu weryfikacji.	Brak	Przejdź do adresu potwierdzonego przez użytkownika.

Przykład żądania

# "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: 29624f3c-90cb-4d34-a7e9-bd2de6d35218
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: 2c95c9bc-fdfb-4c6a-84f4-57c9b0826b43
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"
}

Odpowiedź REST

Jeśli metoda powiedzie się, metoda zwraca obiekt AddressValidationResponse w treści odpowiedzi z kodem stanu HTTP 200 . Poniżej przedstawiono przykład.

Kody powodzenia i błędów odpowiedzi

Każda odpowiedź zawiera kod stanu HTTP, który wskazuje powodzenie lub niepowodzenie i informacje o debugowaniu. Użyj narzędzia do śledzenia sieci, aby odczytać ten kod, typ błędu i inne parametry. Aby uzyskać pełną listę, zobacz Kody błędów REST Centrum partnerskiego.

Przykład odpowiedzi

# "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: 29624f3c-90cb-4d34-a7e9-bd2de6d35218
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: 2c95c9bc-fdfb-4c6a-84f4-57c9b0826b43
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'"
}

Udostępnij za pośrednictwem