주소 유효성 검사

아티클
03/07/2025

적용: 파트너 센터 | 21Vianet에서 운영하는 파트너 센터 | 미국 정부를 위한 Microsoft 클라우드 파트너 센터

이 문서에서는 주소 유효성 검사 API를 사용하여 주소의 유효성을 검사하는 방법을 설명합니다.

주소 유효성 검사 API는 고객 프로필 업데이트의 유효성 검사에만 사용해야 합니다. API 응답 상태에 따라 호출자는 고객에게 가장 적합한 주소를 선택해야 합니다.

필수 구성 요소

파트너 센터 인증에 설명된 대로 자격 증명. 이 시나리오는 독립 실행형 앱 및 App+사용자 자격 증명을 모두 사용하여 인증을 지원합니다.

C#

주소의 유효성을 검사하려면 먼저 새 Address 개체를 인스턴스화하고 유효성을 검사할 주소로 채웁니다. 그런 다음, IAggregatePartner.Validations 속성에서 유효성 검사 작업을 위한 인터페이스를 가져와, 주소 개체를 사용하여 IsAddressValid 메서드를 호출합니다.

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 요청

요청 구문

메서드	요청 URI
POST	{baseURL}/v1/validations/address HTTP/1.1

요청 헤더

자세한 내용은 파트너 센터 REST 헤더 참조하세요.

요청 본문

이 표에서는 요청 본문의 필수 속성에 대해 설명합니다.

이름	유형	필수*	묘사
주소 행 1	문자열	Y	주소의 첫 번째 줄입니다.
주소 줄 2	문자열	N	주소의 두 번째 줄입니다. 이 속성은 선택 사항입니다.
도시	문자열	Y	도시.
상태	문자열	Y	상태
우편 번호	문자열	Y	우편 번호입니다.
나라	문자열	Y	두 문자 ISO alpha-2 국가 코드입니다.

* 필수 속성은 국가 또는 지역에 따라 변경 될 수 있습니다.

응답 세부 정보

응답은 다음 상태 메시지 중 하나를 반환합니다. 상태 응답이 확인됨 또는 배송 가능으로 확인됨아닐 경우, 입력한 주소 및/또는 제안된 주소를 검토하십시오. 고객에게 가장 적합한 주소를 선택하는 것은 호출자에게 달려 있습니다.

상태	묘사	반환된 제안된 주소 수	상태 응답 권장 사항
배송 가능 여부 확인됨	주소가 확인되어 배송될 수 있습니다.	싱글	확인된 주소로 진행하십시오.
확인	주소가 확인되었습니다.	싱글	확인된 주소로 진행하십시오.
상호 작용 필요	제안된 주소가 크게 변경되었으며 사용자 확인이 필요합니다.	싱글	사용자가 확인한 주소로 진행합니다.
도로의 일부	주소에 제공된 거리는 부분적으로만 제공되어 추가 정보가 필요합니다.	여러 개 - 최대 3개	사용자의 확인된 주소로 진행합니다.
건물 부분	지정된 건물(건물 번호, 호실 번호 등)은 불완전하며 더 많은 정보가 필요합니다.	다중 - 최대 3개	확인된 주소로 진행하세요.
여러 가지	주소에 부분적인 여러 필드가 있습니다(잠재적으로 거리 부분 및 건물 부분 포함).	여러 개 - 최대 3개	사용자가 확인한 주소로 진행합니다.
없음	주소가 잘못되었습니다.	없음	확인된 사용자 주소로 진행합니다.
유효성이 검사되지 않음	유효성 검사 프로세스를 통해 주소를 보낼 수 없습니다.	없음	확인된 사용자 주소로 진행합니다.

요청 예제

# "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 응답

성공하면 메서드는 HTTP 200 상태 코드와 함께 응답 본문에 AddressValidationResponse 개체를 반환합니다. 예제는 다음과 같습니다.

응답 성공 및 오류 코드

각 응답에는 성공 또는 실패 및 디버깅 정보를 나타내는 HTTP 상태 코드가 함께 제공됩니다. 네트워크 추적 도구를 사용하여 이 코드, 오류 유형 및 기타 매개 변수를 읽습니다. 전체 목록은 파트너 센터 REST 오류 코드를 참조하세요.

응답 예제

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

다음을 통해 공유