ヒント メッセージを作成する
ヒント要求を使用してプルにサインアップすると、Microsoft は、指定したエンドポイントに次のフォームを含むメッセージを送信し、最後のプル要求以降のスケジュールの変更を特定するように求めます。 オンボード時に要求の頻度を決定します。
<?xml version="1.0" encoding="UTF-8"?>
<HintRequest id="123-abc" timestamp="2017-10-21T08:45:09Z">
<LastFetchTime>2017-10-21T08:30:16Z</LastFetchTime>
</HintRequest>
LastFetchTime要素は、スケジュールの変更を識別した Microsoft に送信した最後に成功した応答の UTC 日時を識別します。 その時点以降に変更がない場合は、応答に空の本文が含まれている必要があります。 変更があった場合、本文には ヒント メッセージが含まれます。これは、変更された旅程を識別します。 次のいずれかの方法を使用して、旅程を特定できます。
正確な旅程
ヒント メッセージは、チェックの日付と滞在期間を使用して、個々の旅程を識別できます。 次の例は、1 つのホテルの 1 つの旅程を指定するヒント メッセージを示しています。
<Hint>
<Item>
<Property>789</Property>
<Stay>
<CheckInDate>2017-10-20</CheckInDate>
<LengthOfStay>2</LengthOfStay>
</Stay>
</Item>
</Hint>
各 <Item> は、個々の旅程を表します。 更新するスケジュールごとに <Item> オブジェクトを指定できます。また、各スケジュールで 1 つ以上のプロパティを指定することもできます。
Microsoft は、上記のヒントを受け取ると、次の クエリ メッセージを送信します。
<Query>
<Checkin>2017-10-20</Checkin>
<Nights>2</Nights>
<PropertyList>
<Property>789</Property>
</PropertyList>
</Query>
クエリ メッセージを取得すると、応答に次の<Result>を含む Price フィードが含まれている必要があります。
<Result>
<Property>789</Property>
<Checkin>2017-10-20</Checkin>
<Nights>2</Nights>
<!-- Pricing and other elements that changed -->
</Result>
上記のヒントで 2 つのプロパティが指定されている場合、Price フィードには 2 つの <Result> 要素 (プロパティごとに 1 つ) が含まれます。
チェックインの日付範囲
ヒント メッセージは、旅程の範囲を識別できます。 範囲を指定するには、FirstDate要素を開始チェック日付に設定し、LastDateを最後のチェック日付に設定します。 次の例は、日付範囲を使用して 1 つのプロパティに 6 つのチェック日付を指定するヒント メッセージを示しています。
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
<Item>
<Property>123</Property>
<FirstDate>2017-10-20</FirstDate>
<LastDate>2017-10-25</LastDate>
</Item>
</Hint>
各<Item>は、チェックの日付の 1 つの範囲を表します。 更新するスケジュールを識別するチェックの日付範囲ごとに <Item> オブジェクトを指定できます。また、それぞれが 1 つ以上のプロパティを指定できます。
Microsoft は、上記のヒントを受け取ると、次の クエリ メッセージを送信します。
<Query>
<FirstDate>2017-10-20</FirstDate>
<LastDate>2017-10-25</LastDate>
<Nights>3</Nights>
<PropertyList>
<Property>123</Property>
</PropertyList>
</Query>
クエリ メッセージを取得すると、応答には、次の <Result> オブジェクトを含む Price フィードが含まれている必要があります。
<Result>
<Property>789</Property>
<Checkin>2017-10-20</Checkin>
<Nights>1</Nights>
<!-- Pricing and other elements that changed -->
</Result>
<Result>
<Property>789</Property>
<Checkin>2017-10-20</Checkin>
<Nights>2</Nights>
<!-- Pricing and other elements that changed -->
</Result>
<Result>
<Property>789</Property>
<Checkin>2017-10-20</Checkin>
<Nights>3</Nights>
<!-- Pricing and other elements that changed -->
</Result>
. . .
<Result>
<Property>789</Property>
<Checkin>2017-10-25</Checkin>
<Nights>1</Nights>
<!-- Pricing and other elements that changed -->
</Result>
<Result>
<Property>789</Property>
<Checkin>2017-10-25</Checkin>
<Nights>2</Nights>
<!-- Pricing and other elements that changed -->
</Result>
<Result>
<Property>789</Property>
<Checkin>2017-10-25</Checkin>
<Nights>3</Nights>
<!-- Pricing and other elements that changed -->
</Result>
この例では、Price フィードに含める必要がある結果の最大数は 18 です (6 チェックの日付 * 3 泊)。 日付範囲の一部の旅程が変更されなかった場合、価格フィードに含まれる量が少なくなる場合があります。
拡張されたチェックの日付範囲
展開されたチェックの日付範囲のヒントは、日付範囲のチェックの日付範囲のヒントに似ていますが、日付範囲に旅程と交差するすべての旅程を含める必要があります。 そのため、Price フィードには、チェックアウト日が日付範囲内にある旅程が含まれている必要があります。
<StaysIncludingRange>は、拡張されたチェックの日付範囲のヒントとしてヒントを識別します。 範囲を指定するには、FirstDate要素を開始チェック日付に設定し、LastDateを最後のチェック日付に設定します。 次の例は、日付範囲を使用して 1 つのプロパティに 6 つのチェック日付を指定するヒント メッセージを示しています。
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
<Item>
<Property>123</Property>
<StaysIncludingRange>
<FirstDate>2017-10-20</FirstDate>
<LastDate>2017-10-25</LastDate>
</StaysIncludingRange>
</Item>
</Hint>
各 <Item> は、1 つの範囲の旅程を表します。 更新するスケジュールを識別するチェックの日付範囲ごとに <Item> オブジェクトを指定できます。また、それぞれが 1 つ以上のプロパティを指定できます。
Microsoft は、上記のヒントを受け取ると、次の クエリ メッセージを送信します。
QueryControl メッセージのMaxLengthOfStay設定によって、<AffectedNights> の値が決まります (この例では、3 に設定されていると想定しています)。
<Query>
<FirstDate>2017-10-20</FirstDate>
<LastDate>2017-10-25</LastDate>
<AffectedNights>3</AffectedNights>
<PropertyList>
<Property>123</Property>
</PropertyList>
</Query>
クエリ メッセージを取得すると、応答には、次の <Result> オブジェクトを含む Price フィードが含まれている必要があります。 最初のいくつかのオブジェクトのチェック日付は、ヒントのFirstDate日付より前に表示されます。 これは、チェックアウト日の旅程がヒントの日付範囲内にあるためです。
<Result>
<Property>789</Property>
<Checkin>2017-10-17</Checkin>
<Nights>3</Nights>
<!-- Pricing and other elements that changed -->
</Result>
<Result>
<Property>789</Property>
<Checkin>2017-10-18</Checkin>
<Nights>2</Nights>
<!-- Pricing and other elements that changed -->
</Result>
<Result>
<Property>789</Property>
<Checkin>2017-10-18</Checkin>
<Nights>3</Nights>
<!-- Pricing and other elements that changed -->
</Result>
<Result>
<Property>789</Property>
<Checkin>2017-10-19</Checkin>
<Nights>1</Nights>
<!-- Pricing and other elements that changed -->
</Result>
<Result>
<Property>789</Property>
<Checkin>2017-10-19</Checkin>
<Nights>2</Nights>
<!-- Pricing and other elements that changed -->
</Result>
<Result>
<Property>789</Property>
<Checkin>2017-10-19</Checkin>
<Nights>3</Nights>
<!-- Pricing and other elements that changed -->
</Result>
<Result>
<Property>789</Property>
<Checkin>2017-10-20</Checkin>
<Nights>1</Nights>
<!-- Pricing and other elements that changed -->
</Result>
. . .
<Result>
<Property>789</Property>
<Checkin>2017-10-25</Checkin>
<Nights>1</Nights>
<!-- Pricing and other elements that changed -->
</Result>
<Result>
<Property>789</Property>
<Checkin>2017-10-25</Checkin>
<Nights>2</Nights>
<!-- Pricing and other elements that changed -->
</Result>
<Result>
<Property>789</Property>
<Checkin>2017-10-25</Checkin>
<Nights>3</Nights>
<!-- Pricing and other elements that changed -->
</Result>
クエリのバッチ処理
更新する必要があるプロパティとスケジュールの数に応じて、Microsoft は 1 つの大きなクエリではなく、いくつかの小さなクエリを送信します。 たとえば、1,000 プロパティのスケジュールを更新する必要がある場合、Microsoft は、それぞれ 10 個のプロパティを含む 100 件のクエリ メッセージを送信する場合があります。