交易 (房源資料) 訊息

總覽

ARI 交易 (資源資料) 訊息會定義各資源的房型和套裝行程 (或費率方案) 資訊。每個房型資料都包含專屬 ID (RoomID)、本地化名稱、說明，以及房型照片的網址。每個套裝組合資料都包含專屬 ID (PackageID)、本地化名稱、說明、入住人數和加值服務。

您可以使用交易訊息執行下列操作：

• 為一或多個屬性定義資料。
• 為每個房源定義房型和套裝行程資訊。
• 控管產品項目。

此外，您也可以設定動作來執行下列操作：

• 為房源新增房型和套裝行程。

  重點： 每個資源最多可有 3,000 個房型。每個資源最多只能有 3,000 個套件。你可以使用 <Transaction> 訊息移除房型或套裝行程。

• 從房源移除房型和套裝行程。

• 在套裝組合或房源中新增會員點數，也就是獎勵方案。

如需交易訊息範例，請參閱「交易 (房源資料) 範例」。

必要和選用元素

XML 參考資料提供必要和選用元素的說明。如要瞭解屬性和子元素的詳細資料，請參閱「交易 (房地產資料) 元素和屬性」。

語法和結構定義

建立交易訊息時，請參考交易 (房源資料) 語法範例，確保格式正確。

你可以使用 xmllint 等第三方 XML 工具，先透過已發布的架構驗證動態饋給，再提交給 Google。如要瞭解交易訊息架構，請參閱飯店廣告架構。

指南規範

請遵守下列交易訊息指南：

行動：

delta：用於新增或更新新的房型和套裝行程 (費率方案)。

overlay：用來為房源的所有房型和套裝行程，替換成新的組合。必須包含你仍想銷售的所有房型和費率方案資訊。

支援的語言：

為「名稱」、「說明」和「說明文字」欄位指定一到兩種語言 (英文，以及視需要為房源指定的當地語言)。如有需要，可以新增兩種以上的語言。

房型和套裝行程：

更新房型或套裝組合時，必須傳送該房型或套裝組合的所有相關資訊。舉例來說，新增相片時，必須一併加入名稱和說明。

<AllowablePackageIDs> 和 <AllowableRoomIDs> 為選填欄位，如果未設定，系統會允許任何房型和費率方案組合。你仍須透過房型和房價方案 ID 傳送空房情形和房價。您可以使用這些元素控制產品，以及停用系統不再支援的組合。

每當房型或套裝行程有變更，或是需要新增房型或套裝行程的重要詳細資料時，請傳送交易訊息更新給 Google。

注意： 由於 Google 會儲存與「相符」資源連結的資源資料，因此必須先在系統中「比對」對應資源，Google 才能接受這項資料。在清單動態饋給中傳送所有房源，有助於避免日後發生錯誤或延遲。

會員點數：

如要在套裝組合中加入或排除會員方案，請與 Google 合作設定會員點數。系統會顯示與該套裝組合相關聯的點數。進一步瞭解會員點數。

使用 <MilesIncluded> 元素定義或更新會員方案活動。詳情請參閱「交易(房源資料)」。會員點數可與 <PackageData> 一併提供。

範例

本節提供 ARI 交易訊息的基本範例，其中使用必要和選用元素。如要新增或更新房型和套裝行程，請使用 delta 動作新增或更新房型和套裝行程，或使用 overlay 動作取代所有房型和套裝行程定義 (刪除舊項目)。

您必須為「名稱」、「說明」和「說明文字」欄位指定一到兩種語言 (英文，以及視需要為房源指定的當地語言)。然後加入房源資料資訊，包括相片連結。

請將 <PropertyID> 和 <RoomID> 替換為系統中使用的費率方案和房型 ID (分別)。與系統保持一致是確保 Google 正確顯示價格和資料的關鍵。

注意： Google 會使用「ID」做為房型和套裝行程 (費率方案) 的 ID； 而 OTA XML 則使用「code」。Google 不會產生 ID，因此您必須使用自己的 ID。如果是房源資料，房型和費率方案 ID 在每個房源中都不得重複。

準備好檔案後，請透過 POST 訊息將檔案傳送至下列端點：https://www.google.com/travel/hotels/uploads/property_data

如要進一步瞭解如何推送/POST 訊息，請參閱推送訊息。

以下範例說明如何使用 delta 動作設定 Transaction 訊息：

<?xml version="1.0" encoding="UTF-8"?>
<Transaction timestamp="202X-XX-XXT00:00:00-0X:00" id="12345678" partner="partner_key">
  <PropertyDataSet action="delta">
    <Property>PROPERTYID</Property>
      <RoomData>
        <RoomID>ROOMID</RoomID>
        <Name><Text text="ROOM NAME" language="en"/></Name>
        <Description>
          <Text text="ROOM DESCRIPTION TEXT" language="en"/>
        </Description>
        <Capacity>4</Capacity>
        <PhotoURL>
          <Caption><Text text="ROOM PHOTO CAPTION TEXT" language="en"/></Caption>
          <URL>https://LINK TO PHOTO</URL>
        </PhotoURL>
      </RoomData>
      <PackageData>
        <PackageID>BASE</PackageID>
        <Name><Text text="Internet Special" language="en"/></Name>
        <Description><Text text="Direct Booking through Hotel Website" language="en"/></Description>
        <Refundable available="true" refundable_until_days="2" refundable_until_time="12:00"/>
      </PackageData>
  </PropertyDataSet>
</Transaction>

如需更多範例，例如如何使用 overlay 動作、將房型和套裝行程新增至現有資源資料，以及移除現有房型和套裝行程，請參閱「交易 (資源資料) 範例」。

使用指南

本節提供解決方案，協助您處理傳送交易訊息時可能遇到的情況。

情境 1：如何移除房型資料

如何移除現有房型和/或套裝組合資料？

說明

您已為該房源傳送多種房型，包括特大床房和雙人床房。改建期間無法入住任何雙人床房型，目前僅提供特大雙人床房型。

解決方案

• 如果房型和套裝組合 ID 已移除或停用，就不需要更新每晚的空房情況、房價或房源。
• 如果房型或套裝方案已移除或停用，請傳送新的 action="overlay" 交易訊息，其中只包含仍有效的房型和套裝方案，並排除已移除的房型或套裝方案。

範例

這個 XML 片段顯示如何使用 overlay 動作移除房型。

注意： 雖然這個範例涵蓋房間類型，但您也可以使用相同的動作移除套件資料。

以下是原始的 delta 動作，包含 King 和 Queen 房型：

  <PropertyDataSet action="delta">
    <Property>Property_1</Property>
    <RoomData>
      <RoomID>King</RoomID>
      <Name>
        <Text text="King" language="en"/>
      </Name>
      <Capacity>2</Capacity>
    </RoomData>
    <PackageData>
      <PackageID>Standard</PackageID>
      <Name>
        <Text text="Standard" language="en"/>
      </Name>
      <Description>
        <Text text="Standard rate" language="en"/>
      </Description>
      <Refundable available="true" refundable_until_days="7" refundable_until_time="18:00:00"/>
      <BreakfastIncluded>0</BreakfastIncluded>
      </PackageData>
    <RoomData>
      <RoomID>Queen</RoomID>
      <Name>
        <Text text="Queen" language="en"/>
      </Name>
      <Capacity>2</Capacity>
      <!-- Additional RoomData child elements omitted. -->
    </RoomData>
  </PropertyDataSet>

然後設定 overlay，移除 Queen 房型並保留 King 房型：

  <PropertyDataSet action="overlay">
    <Property>Property_1</Property>
    <RoomData>
      <RoomID>King</RoomID>
      <Name>
        <Text text="King" language="en"/>
      </Name>
      <Capacity>2</Capacity>
    </RoomData>
    <PackageData>
      <PackageID>Standard</PackageID>
      <Name>
        <Text text="Standard" language="en"/>
      </Name>
      <Description>
        <Text text="Standard rate" language="en"/>
      </Description>
      <Refundable available="true" refundable_until_days="7" refundable_until_time="18:00:00"/>
      <BreakfastIncluded>0</BreakfastIncluded>
    </PackageData>
  </PropertyDataSet>

情境 2：如何使用 AllowablePackageIDs 控制產品

如果套裝方案是依房型分組，如何控管產品 (房型和套裝方案的組合)？

注意： 如果房型是依套裝方案分組，請參閱情境 3。

說明

你提供特定套裝行程，但僅適用於特定房型。舉例來說，假設您的房源有四種房型 (包括總統套房) 和六種不同的套裝行程，但只有少數套裝行程符合總統套房的資格，您就可以指定資格。

解決方案

使用 <AllowablePackageIDs> 傳送更新後的交易訊息，指明套裝組合內含哪些產品。

注意： 請使用 <AllowablePackageIDs> 或 <AllowableRoomIDs>，但不要同時使用這兩者。使用的元素取決於系統是否使用「room>package」或「package>room」階層。如果交易訊息中未定義這兩個元素，房型可與任何套裝組合。

範例

這個 XML 程式碼片段說明如何使用 <AllowablePackageIDs>，指定特定房型適用的套裝行程。例如，閣樓套房房型僅允許閣樓全包套裝行程或免費早餐套裝行程，而特大號床套房房型僅允許特大號床全包套裝行程或寵物友善套裝行程。

<RoomData>
  <RoomID>penthouse_suite</RoomID>
  <AllowablePackageIDs>
    <AllowablePackageID>penthouse_all_inclusive</AllowablePackageID>
    <AllowablePackageID>free_breakfast</AllowablePackageID>
  </AllowablePackageIDs>
  <!-- Additional child elements omitted. -->
</RoomData>
<RoomData>
  <RoomID>king_suite</RoomID>
  <AllowablePackageIDs>
    <AllowablePackageID>king_all_inclusive</AllowablePackageID>
    <AllowablePackageID>pet_friendly</AllowablePackageID>
  </AllowablePackageIDs>
  <!-- Additional child elements omitted. -->
</RoomData>
<PackageData>
  <PackageID>penthouse_all_inclusive</PackageID>
</PackageData>
<!-- Additional child elements omitted. -->
<PackageData>
  <PackageID>free_breakfast</PackageID>
</PackageData>
<!-- Additional child elements omitted. -->
<PackageData>
  <PackageID>king_all_inclusive</PackageID>
</PackageData>
<!-- Additional child elements omitted. -->
<PackageData>
  <PackageID>pet_friendly</PackageID>
</PackageData>

注意： 如果您使用 <AllowablePackageIDs> 或 <AllowableRoomIDs> 停用先前可能使用過，但系統現在不允許的組合，則不需要重新傳送所有日期的 ARI，只要移除先前的資料即可。

情境 3：如何使用 AllowableRoomIDs 控制產品

如果房型是依套裝行程分組，如何控管產品 (房型和套裝行程的組合)？

注意： 如果套裝組合是依房型分組，請參閱情境 2。

說明

房型和套裝行程組合不再以產品形式銷售，或您想控管新套裝行程的內容。舉例來說，您只想指定特定房型，例如附套裝行程的海景特大床和雙人床房。

解決方案

使用 <AllowableRoomIDs> 元素傳送更新後的交易訊息，指明套裝組合內含的確切產品。

範例

這個 XML 程式碼片段說明如何使用 <AllowableRoomID>，在套裝組合中指定海景大床和雙人床房型。

<PackageID>RO</PackageID>
<AllowableRoomIDs>
  <AllowableRoomID>king_oceanview</AllowableRoomID>
  <AllowableRoomID>queen_oceanview</AllowableRoomID>
</AllowableRoomIDs>