交易 (資源資料) 訊息

總覽

ARI 交易 (資源資料) 訊息會定義每個房源的房型和套裝行程 (或費率方案) 相關資訊。每個房型資料都包含一個獨特 ID (RoomID)、本地化名稱、說明，以及房型相片的網址。每個套件資料都包含專屬 ID (PackageID)、本地化名稱、說明、可容納人數和附加價值。

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

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

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

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

  重點： 每個房源最多只能有 3000 個房型。套裝方案也有單獨的限制，每個資源最多只能有 3000 個。你可以使用 <Transaction> 訊息移除房型或套裝行程。

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

• 為套裝行程或房源新增會員點數，也就是獎勵計畫。

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

必要和選用元素

XML 參考資料會說明必要和選用元素。如要進一步瞭解屬性和子元素，請參閱「交易 (資源資料) 元素和屬性」。

語法和結構定義

建立交易訊息時，請參考「交易 (資源資料) 語法」範例，確保您遵循正確的格式。

您可以使用第三方 XML 工具 (例如 xmllint)，在提交至 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」。您必須使用自己的 ID，因為 Google 不會產生 ID。針對房源資料，房型和房價方案 ID 必須是每個房源的專屬 ID。

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

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

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

<?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 動作移除房型。

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

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

  <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：如何使用 AllowablePackageID 控制產品

當套裝方案依房型分組時，如何控制產品 (房型和套裝方案的組合)？

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

說明

你有某些套裝行程僅適用於特定房型。舉例來說，假設你的住宿設施有四種房型 (包括總統套房) 和六種不同的套裝行程，但只有少數套裝行程適用於總統套房，你可以指定資格。

解決方案

傳送更新的交易訊息，使用 <AllowablePackageIDs> 指定套件中包含哪些產品。

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

範例

這個 XML 程式碼片段顯示如何使用 <AllowablePackageIDs> 指定與特定房型搭配使用的套裝方案。在此，閣樓套房房型只允許閣樓套房全包套餐或免費早餐套餐，而 King 套房房型只允許 King 套房全包套餐或寵物友善套餐。

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