Überprüfen einer Adresse

Artikel
07/11/2024

Gilt für: Partner Center | Partner Center-Betrieb durch 21Vianet | Partner Center für Microsoft Cloud for US Government

In diesem Artikel wird erläutert, wie Sie eine Adresse mithilfe der Adressüberprüfungs-API überprüfen.

Die Adressüberprüfungs-API sollte nur für die Vorabvalidierung von Kundenprofilupdates verwendet werden. Basierend auf dem API-Antwortstatus sollte der Aufrufer die am besten geeignete Adresse für den Kunden auswählen.

Voraussetzungen

Anmeldeinformationen, wie unter Partner Center-Authentifizierung beschrieben. Dieses Szenario unterstützt die Authentifizierung mit eigenständigen App- und App+Benutzeranmeldeinformationen.

C#

Um eine Adresse zu überprüfen, instanziieren Sie zuerst ein neues Address-Objekt und füllen Sie sie mit der zu überprüfenden Adresse auf. Rufen Sie dann eine Schnittstelle zu Validations-Vorgängen aus der IAggregatePartner.Validations-Eigenschaft ab, und rufen Sie die IsAddressValid-Methode mit dem Adressobjekt auf.

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-Anforderung

Anforderungssyntax

Methode	Anforderungs-URI
POST	{baseURL}/v1/validations/address HTTP/1.1

Anforderungsheader

Weitere Informationen finden Sie unter Partner Center-REST-Header.

Anforderungstext

In dieser Tabelle werden die erforderlichen Eigenschaften im Anforderungstext beschrieben.

Name	type	Erforderlich*	Beschreibung
addressline1	Zeichenfolge	J	Die erste Zeile der Adresse.
addressline2	Zeichenfolge	N	Die zweite Zeile der Adresse. Diese Eigenschaft ist optional.
city	Zeichenfolge	J	Die Stadt.
state	Zeichenfolge	J	Das Land/die Region.
postalcode	Zeichenfolge	J	Die Postleitzahl.
country	Zeichenfolge	J	Der aus zwei Zeichen bestehende ISO alpha-2-Ländercode.

* Erforderliche Eigenschaften können sich je nach Land oder Region ändern.

Details der Antwort

Die Antwort gibt eine der folgenden Statusmeldungen zurück. Wenn die Statusantwort nicht überprüft oder verifiedShippable ist, überprüfen Sie Ihre eingegebene Adresse und/oder vorgeschlagene Adresse. Es liegt bei dem Anrufer, die am besten geeignete Adresse für den Kunden auszuwählen.

Status	Beschreibung	Anzahl der zurückgegebenen vorgeschlagenen Adressen	Empfehlung zur Statusantwort
Versandfähigkeit überprüft	Die Adresse ist überprüft und für den Versand geeignet.	Single	Fahren Sie mit der überprüften Adresse fort.
Überprüft	Die Adresse ist überprüft.	Single	Fahren Sie mit der überprüften Adresse fort.
Interaktion erforderlich	Die vorgeschlagene Adresse wird erheblich geändert und erfordert eine Benutzerbestätigung.	Single	Fahren Sie mit der bestätigten Adresse des Benutzers fort.
Straße unvollständig	Die angegebene Straße in der Adresse ist unvollständig und erfordert weitere Informationen.	Mehrere – maximal drei	Fahren Sie mit der bestätigten Adresse des Benutzers fort.
Räumlichkeiten unvollständig	Die angegebenen Räumlichkeiten (Gebäudenummer, Suitenummer und andere) sind unvollständig und erfordern weitere Informationen.	Mehrere – maximal drei	Fahren Sie mit der bestätigten Adresse des Benutzers fort.
Mehrere	Mehrere Felder in der Adresse sind unvollständig (möglicherweise einschließlich der Felder für Straße und Räumlichkeiten).	Mehrere – maximal drei	Fahren Sie mit der bestätigten Adresse des Benutzers fort.
Keine	Die Adresse ist falsch.	Keine	Fahren Sie mit der bestätigten Adresse des Benutzers fort.
Nicht überprüft	Die Adresse konnte nicht über den Überprüfungsprozess gesendet werden.	Keine	Fahren Sie mit der bestätigten Adresse des Benutzers fort.

Anforderungsbeispiel

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

REST-Antwort

Bei erfolgreicher Ausführung gibt die Methode ein AddressValidationResponse-Objekt im Antworttext mit einem HTTP 200-Statuscode zurück. Im Folgenden wird ein Beispiel aufgeführt.

Erfolgs- und Fehlercodes der Antwort

Jede Antwort enthält einen HTTP-Statuscode, der Erfolg oder Fehler und Debugginginformationen angibt. Verwenden Sie ein Netzwerkablaufverfolgungstool, um diesen Code, fehlertyp und andere Parameter zu lesen. Die vollständige Liste finden Sie unter Partner Center-REST-Fehlercodes.

Beispielantwort

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

Freigeben über