Validera en adress

Artikel
07/11/2024

Gäller för: Partnercenter | Partnercenter som drivs av 21Vianet | Partnercenter för Microsoft Cloud for US Government

Den här artikeln beskriver hur du verifierar en adress med hjälp av API:et för adressverifiering.

API:et för adressverifiering bör endast användas för förhandsvalidering av kundprofiluppdateringar. Baserat på API-svarsstatusen bör anroparen välja den lämpligaste adressen för kunden.

Förutsättningar

Autentiseringsuppgifter enligt beskrivningen i Partnercenter-autentisering. Det här scenariot stöder autentisering med både fristående app- och App+User-autentiseringsuppgifter.

C#

Verifiera en adress genom att först instansiera ett nytt adressobjekt och fylla i det med den adress som ska verifieras. Hämta sedan ett gränssnitt till valideringsåtgärder från egenskapen IAggregatePartner.Validations och anropa metoden IsAddressValid med adressobjektet.

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

REST-begäran

Syntax för begäran

Metod	URI för förfrågan
POST	{baseURL}/v1/validations/address HTTP/1.1

Begärandehuvuden

Mer information finns i REST-huvuden för Partnercenter.

Begärandetext

I den här tabellen beskrivs de nödvändiga egenskaperna i begärandetexten.

Namn	Type	Krävs*	beskrivning
addressline1	sträng	Y	Den första raden i adressen.
addressline2	sträng	N	Den andra raden i adressen. Den här egenskapen är valfri.
ort	string	Y	Staden.
tillstånd	string	Y	Tillståndet.
Postnummer	sträng	Y	Postnummer.
land	string	Y	Landskoden iso alpha-2 med två tecken.

* Obligatoriska egenskaper kan ändras baserat på land eller region.

Svarsinformation

Svaret returnerar något av följande statusmeddelanden. Om statussvaret inte är Verifierat eller VerifiedShippable granskar du din angivna adress och/eller föreslagna adress. Det är upp till uppringaren att välja den lämpligaste adressen för kunden.

Status	beskrivning	Antal föreslagna adresser som returneras	Rekommendation för statussvar
Verifierad leveransbar	Adressen verifieras och kan skickas till.	Enstaka	Fortsätt med verifierad adress.
Bekräftat	Adressen har verifierats.	Enstaka	Fortsätt med verifierad adress.
Interaktion krävs	Den föreslagna adressen ändras avsevärt och behöver användarbekräftelse.	Enstaka	Fortsätt med användarens bekräftade adress.
Del av gata	Den angivna gatan i adressen är delvis och behöver mer information.	Flera – högst tre	Fortsätt med användarens bekräftade adress.
Delvis lokal	De angivna lokalerna (byggnadsnummer, svitnummer och andra) är partiella och behöver mer information.	Flera – högst tre	Fortsätt med användarens bekräftade adress.
Flera	Det finns flera fält som är partiella i adressen (potentiellt även delvis gata och delvis lokal).	Flera – högst tre	Fortsätt med användarens bekräftade adress.
Ingen	Adressen är felaktig.	Ingen	Fortsätt med användarens bekräftade adress.
Inte verifierad	Det gick inte att skicka adressen via valideringsprocessen.	Ingen	Fortsätt med användarens bekräftade adress.

Exempel på begäran

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

REST-svar

Om det lyckas returnerar metoden ett AddressValidationResponse-objekt i svarstexten med en HTTP 200-statuskod . Ett exempel följer.

Svarsframgång och felkoder

Varje svar levereras med en HTTP-statuskod som anger lyckad eller misslyckad och felsökningsinformation. Använd ett verktyg för nätverksspårning för att läsa den här koden, feltypen och andra parametrar. Den fullständiga listan finns i Rest-felkoder för Partnercenter.

Svarsexempel

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

Dela via