ヒント要求付きのプルにサインアップすると、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> を含む価格フィードが含まれている必要があります。
<Result>
<Property>789</Property>
<Checkin>2017-10-20</Checkin>
<Nights>2</Nights>
<!-- Pricing and other elements that changed -->
</Result>
上記のヒントで 2 つのプロパティを指定した場合、価格フィードには 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>
各 <項目> は、チェックの日付の 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> オブジェクトを含む価格フィードが含まれている必要があります。
<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>
この例では、価格フィードに含める結果の最大数は 18 (6 日間のチェック日 * 3 泊) です。 日付範囲の一部の旅程が変更されなかった場合、価格フィードに含まれる値が少なくなる可能性があります。
チェックの日範囲の拡大
拡張チェックイン日範囲のヒントは、チェックイン日範囲のヒントに似ていますが、日付範囲内の旅程と交差するすべての旅程を含めるように求められます。 したがって、価格フィードには、チェックアウト日が日付範囲内の旅程を含める必要があります。
<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>
各 <項目> は、旅程の 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> オブジェクトを含む価格フィードが含まれている必要があります。 最初のいくつかのオブジェクトのチェック日は、ヒントの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 件のクエリ メッセージを送信する場合があります。