アドレスを確認する

[アーティクル]
07/11/2024

適用対象: パートナーセンター | 21Vianet が運営するパートナーセンター | Microsoft Cloud for US Government のパートナーセンター

この記事では、アドレス検証 API を使用してアドレスを検証する方法について説明します。

アドレス検証 API は、顧客プロファイルの更新の事前検証にのみ使用する必要があります。 API 応答の状態に基づいて、呼び出し元は顧客に最適なアドレスを選択する必要があります。

前提条件

パートナーセンターの認証に関するページで説明している資格情報。このシナリオでは、スタンドアロンアプリとアプリ + ユーザーの両方の資格情報を使った認証がサポートされています。

C#

アドレスを検証するには、最初に新しい Address オブジェクトをインスタンス化し、検証するアドレスを設定します。次に、IAggregatePartner.Validations プロパティから Validations 操作へのインターフェイスを取得し、address オブジェクトを使用して 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
投稿	{baseURL}/v1/validations/address HTTP/1.1

要求ヘッダー

詳細については、「パートナーセンター REST ヘッダー」を参照してください。

要求本文

次の表は、要求本文の必須プロパティの説明です。

名前	Type	必須*	説明
addressline1	string	年	住所の 1 行目。
addressline2	string	N	住所の 2 行目。このプロパティは省略可能です。
city	string	年	市区町村。
state	string	年	状態。
postalcode	string	年	郵便番号。
country	string	年	2 文字の ISO alpha-2 国別コード。

※国や地域によって必要な物件が変わる場合があります。

応答の詳細

応答は、次のいずれかのステータスメッセージを返します。状態の応答が検証済みまたは VerifiedShippable でない場合は、入力した住所や提案された住所を確認します。顧客に最も適した住所を選択するのは呼び出し元の責任です。

状態	説明	返される住所候補の数	状態の応答に関する推奨事項
Verified shippable (検証済み出荷可能)	住所が確認され、出荷可能です。	単一	確認済みアドレスに進みます。
検証済み	住所が確認されました。	単一	確認済みアドレスに進みます。
Interaction required (対話式操作が必要)	推奨されるアドレスが大幅に変更され、ユーザーの確認が必要です。	単一	ユーザーが確認したアドレスに進みます。
Street partial (番地が不完全)	住所の番地が部分的であるため、さらに情報が必要です。	複数 (最大 3)	ユーザーが確認したアドレスに進みます。
Premises partial (建物が不完全)	指定された建物 (ビル番号、部屋番号、その他) が不完全であるため、さらに情報が必要です。	複数 (最大 3)	ユーザーが確認したアドレスに進みます。
複数	住所の複数のフィールドが不完全です (street partial と premises partial も含む可能性があります)。	複数 (最大 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'"
}

次の方法で共有