管理旅館廣告活動

發行項
02/17/2024

注意事項

此 Beta 版的旅館價格廣告僅供選取參與者使用。如需參與 Beta 發行計劃的相關信息，請連絡您的帳戶管理員或在這裡註冊。

API 和檔可能會變更。

旅館 API 可讓您管理旅館廣告營銷活動和營銷活動。子帳戶提供您旅館價格廣告的最上層邏輯組織。您可以將它視為先前旅館活動) (的記錄活動。您最多可以有 75 個作用中的子帳戶。

子帳戶會指定營銷活動的每日預算、允許的報價上限，以及未指定報價或乘數之廣告的預設中標和報價乘數。

注意事項

這裡提到的旅館廣告活動與 Microsoft Advertising 中的行銷活動沒有任何關聯性。

如果您尚未這麼做，請熟悉下列主題：

如需旅館 API 端點，請參閱端點。

如需報告的相關信息，請參閱旅館價格廣告報告 API。

使用子帳戶

子帳戶是飯店價格廣告的最上層組織。當您註冊飯店價格廣告時，服務會為您建立預設的子帳戶。 API 可讓您新增子帳戶、列出子帳戶、取得特定的子帳戶，以及更新子帳戶。

以下是您用來管理子帳戶的 REST 範本。

/SubAccounts — 取得 | POST
/SubAccounts('{subAccountId}') — 取得 | 修補程式

如需取得和更新子帳戶的範例，請參閱程式代碼範例。 (使用右窗格中的 [語言] 選取器來查看不同語言的範例。)

列出子帳戶

若要取得子帳戶清單，請傳送下列要求。

GET https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Accept: application/json
Host: <host>

回應包含 CollectionResponse 物件。數位 value 包含 SubAccount 物件的清單。

HTTP/1.1 200 OK
x-ms-requestid: a21451ae-f86b-4a19-a00e-9265b59a99ec
x-ms-trackingid: 7cd2710c-821a-48e8-99af-efdc05aebe86

{
  "@odata.count":1,
  "value":[
    {
      "Id":"1902000002",
	  "Name":"DefaultSubAccount1",
	  "Status":"Active",
	  "Bid":{
        "@odata.type":"#Model.FixedBid",
		"Amount":2.75
      },
	  "BidMultipliers":[],
	  "DailyBudget":{
        "Amount":125.25
      },
	  "MaximumBid":{
        "Amount":10.0
      }
    }
  ]
}

更新子帳戶

子帳戶會指定用於未指定中標或乘數之旅館群組和旅館的預設中標和報價乘數。子帳戶也會指定全天散佈的預算，以及您希望所有報價都不要超過的最大報價。

如需有關您市場有效報價範圍和預算的詳細資訊，請參閱貨幣主題中的貨幣值數據表。

若要暫停子帳戶中的所有旅館，請將 subaccount 的 Bid 屬性設定為 PercentageBid 物件，並將百分比的約定金額設定為零 (0.0) 。

如果子帳戶指定了標定乘數，而您想要移除它們，請將設定 BidMultipliers 為空陣列 (例如 “BidMultipliers”：[]) 。

若要更新子帳戶，請傳送 PATCH 要求。要求的主體是 SubAccount 物件。只包含您想要更新的屬性。此範例會顯示更新乘數。

PATCH https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>') HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Content-Type: application/json
Host: <host>
Content-Length: 682

{
  "Id":"1902000002",
  "BidMultipliers":[
    { 
	  "Countries":["US"],
	  "Factor":1.1,
	  "@odata.type":"#Model.UserCountryMultiplier"
	},
	{
	  "Sites":["LocalUniversal","MapResults"],
	  "Factor":0.85,
	  "@odata.type":"#Model.SiteMultiplier"
	},
	{
	  "DeviceTypes":["Desktop"],
	  "Factor":0.65,
	  "@odata.type":"#Model.DeviceMultiplier"
	},
	{
	  "MinimumNumberOfNights":5,
	  "Factor":1.3,
	  "@odata.type":"#Model.LengthOfStayMultiplier"
	},
	{
	  "DaysOfWeek":["Thursday","Friday","Saturday"],
	  "Factor":1.2,
	  "@odata.type":"#Model.CheckinDayOfWeekMultiplier"
	},
	{
	  "DaysOfWeek":["Sunday","Monday"],
	  "Factor":0.9,
	  "@odata.type":"#Model.CheckinDayOfWeekMultiplier"
	},
	{
	  "MinimumNumberOfDays":3,
	  "Factor":1.3,
	  "@odata.type":"#Model.AdvanceBookingWindowMultiplier"
	} 
  ]
}

取得子帳戶

若要取得特定的子帳戶，請傳送下列要求。子帳戶標識碼必須以單引號包裝，如下所示。

GET https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>') HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Accept: application/json
Host: <host>

回應包含 SubAccount 物件。

HTTP/1.1 200 OK
x-ms-requestid: 58d37dd1-78ae-4ced-91e4-7f57e647ddee
x-ms-trackingid: 5345bf4f-e64a-47a6-8d1e-43cc0231dc1b

{
  "Id":"1902000002",
  "Name":"DefaultSubAccount1",
  "Status":"Active",
  "Bid":{
    "@odata.type":"#Model.FixedBid",
	"Amount":2.75
  },
  "BidMultipliers":[
    {
      "@odata.type":"#Model.DeviceMultiplier",
	  "Factor":0.65,
	  "DeviceTypes":["Desktop"]
    },
	{
      "@odata.type":"#Model.LengthOfStayMultiplier",
	  "Factor":1.3,
	  "MinimumNumberOfNights":5
    },
	{
      "@odata.type":"#Model.UserCountryMultiplier",
	  "Factor":1.1,
	  "Countries":["US"]
    },
	{
      "@odata.type":"#Model.AdvanceBookingWindowMultiplier",
	  "Factor":1.3,
	  "MinimumNumberOfDays":3
    },
	{
      "@odata.type":"#Model.CheckinDayOfWeekMultiplier",
	  "Factor":0.9,
	  "DaysOfWeek":["Monday","Sunday"]
    },
	{
      "@odata.type":"#Model.CheckinDayOfWeekMultiplier",
	  "Factor":1.2,
	  "DaysOfWeek":["Thursday","Friday","Saturday"]
    },
	{
      "@odata.type":"#Model.SiteMultiplier",
	  "Factor":0.85,
	  "Sites":["MapResults","LocalUniversal"]
    }
  ],
  "DailyBudget":{
    "Amount":125.25
  },
  "MaximumBid":{
    "Amount":10.0
  },
  "HotelAssociationCount":39540
}

使用旅館群組

旅館群組是您用來將旅館分組的第二層組織。當您建立子帳戶時，服務會在名為 Ungrouped 的子帳戶下建立預設旅館群組。 API 可讓您列出、取得、更新和新增旅館群組。

以下是您用來管理旅館群組的 REST 範本。

/SubAccounts('{subAccountId}')/HotelGroups — 取得 | POST
/SubAccounts('{subAccountId}')/HotelGroups('{hotelGroupId}') — 取得 | 修補程序 | 刪除

如需取得、新增及更新旅館群組的範例，請參閱程式代碼範例。 (使用右窗格中的 [語言] 選取器來查看不同語言的範例。)

列出旅館群組

根據預設，當您要求子帳戶下的旅館群組清單時，API 最多會傳回 1,000 個群組。若要判斷子帳戶中的群組總數，請使用 $count 查詢參數。若要指定要傳回的群組數目，請使用 $top 查詢參數。您可以在單一呼叫中要求的群組數目上限為5,000個。如果子帳戶包含超過 5,000 個群組，請使用$top和 $skip 查詢參數來逐頁查看所有群組。

若要取得子帳戶下前 1,000 個旅館群組的清單，請傳送下列要求。

GET https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>')/HotelGroups HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Accept: application/json
Host: <host>

回應包含 CollectionResponse 物件。數位 value 包含 HotelGroup 物件的清單。此範例顯示預設的 [未群組] 群組。

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
x-ms-requestid: f526c0e6-f7d8-48c7-9270-8fb0a0465153
x-ms-trackingid: 21fafae0-4053-46e0-8271-87bc5fce6312

{
  "@odata.count":6,
  "value":[
    {
      "Id":"55113020342274",
      "Name":"UnGrouped",
      "Status":"Active",
      "Bid":{
        "@odata.type":"#Model.FixedBid",
        "Amount":3.0
      },
      "BidSource":"SubAccount",
      "BidMultiplierSource":null,
      "BidMultipliers":[]
    },
	
	. . .
	
    {
      "Id":"55113020351605",
      "Name":"test-2",
      "Status":"Active",
      "Bid":{
        "@odata.type":"#Model.FixedBid",
        "Amount":1.5
      },
      "BidSource":"HotelGroup",
      "BidMultiplierSource":null,
      "BidMultipliers":[]
    }
  ]
}

新增旅館群組

如果您想要建立旅館的新邏輯群組，您可以建立新的旅館群組。若要指定旅館群組，請使用 HotelGroup 物件。唯一需要的欄位是 Name。使用表示群組的描述性名稱。和 BidMultipliers 欄Bid位是選擇性的。如果您未指定它們，群組會使用子帳戶中的中標和中標乘數。如果您想要覆寫子帳戶值，請指定它們。您可以指定中標、乘數或兩者。

如需您市場有效報價範圍的詳細資訊，請參閱貨幣主題中的貨幣值數據表。

下列範例會建立旅館群組，該群組會繼承子帳戶中的中標和報價乘數。

POST https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>')/HotelGroups HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Accept: application/json
Host: <host>
Content-Length: 26

{"Name":"test-3"}

回應是 AddResponse 物件，其中包含新增旅館群組的標識碼。

HTTP/1.1 200 OK
Content-Length: 140
Content-Type: application/json; odata.metadata=minimal
x-ms-requestid: 8a2e2026-e170-4607-b4fe-06954a67b80a
x-ms-trackingid: e86fcdbd-613e-44a9-b5fc-528cfa87297a

{
  "value":"55113020351606"
}

新增旅館群組之後，請使用關聯範本將旅館新增至群組。如需詳細資訊，請參閱建立旅館與旅館群組的關聯。

更新旅館群組

旅館群組會指定要用於群組中旅館的預設中標和報價乘數。群組會明確指定它們，或從其所屬的子帳戶繼承它們。您可以使用 API 來更新未指定中標或乘數的飯店所要使用的中標乘數和中標乘數。

如需有關您市場有效報價範圍和預算的詳細資訊，請參閱貨幣主題中的貨幣值數據表。

如果子帳戶指定最高報價，則旅館群組的報價必須小於子帳戶的最大報價。

若要暫停旅館群組中的所有旅館，請將群組的 Bid 屬性設定為 PercentageBid 物件，並將百分比的約定金額設定為零 (0.0) 。

如果群組指定的報價大於零，但群組的旅館未提供服務，可能是因為子帳戶的報價為零。

若要移除旅館群組的申請，請將設 Bid 為 null (例如“Bid”：null) 。

如果旅館群組指定了中標乘數，而您想要移除它們，請將設定 BidMultipliers 為空陣列 (例如 “BidMultipliers”：[]) 。

若要更新旅館群組，請傳送 PATCH 要求。要求的本文是 HotelGroup 物件。只包含您想要更新的屬性。此範例顯示更新中標的和乘數。

PATCH https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>')/HotelGroups('<hotelgroupid>') HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Content-Type: application/json
Content-Length: 474
Host: <host>

{
  "Id":"55113020351606",
  "Bid":{
    "Amount":4.75,
    "@odata.type":"#Model.FixedBid"
  },
  "BidMultipliers":[
    {
      "DeviceTypes":["Desktop"],
      "Factor":0.65,
      "@odata.type":"#Model.DeviceMultiplier"
    },
    {
      "MinimumNumberOfNights":7,
      "Factor":1.3,
      "@odata.type":"#Model.LengthOfStayMultiplier"
    },
    {
      "DaysOfWeek":["Thursday","Friday","Saturday"],
      "Factor":1.5,
      "@odata.type":"#Model.CheckinDayOfWeekMultiplier"
    },
    {
      "DaysOfWeek":["Sunday","Monday"],
      "Factor":2.5,
      "@odata.type":"#Model.CheckinDayOfWeekMultiplier"
    }
  ]
}

取得旅館群組

若要取得特定旅館群組，請傳送下列要求。旅館群組標識碼必須以單引號包裝，如下所示。

GET https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>')/HotelGroups('<hotelgroupid>') HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Accept: application/json
Host: <host>

回應包含 HotelGroup 物件。

HTTP/1.1 200 OK
Content-Length: 813
Content-Type: application/json; odata.metadata=minimal
x-ms-requestid: 3be2a39c-723c-41bd-9e74-0a9e44c4fa3c
x-ms-trackingid: e5eba818-2ef7-4fe6-9225-9e2325414e3b

{
  "Id":"55113020351606",
  "Name":"test-2",
  "Status":"Active",
  "Bid":{
    "@odata.type":"#Model.FixedBid",
    "Amount":4.75
  },
  "BidSource":"HotelGroup",
  "BidMultiplierSource":"HotelGroup",
  "BidMultipliers":[
    {
      "@odata.type":"#Model.DeviceMultiplier",
      "Factor":0.65,
      "DeviceTypes":["Desktop"]
    },
    {
      "@odata.type":"#Model.LengthOfStayMultiplier",
      "Factor":1.3,
      "MinimumNumberOfNights":7
    },
    {
      "@odata.type":"#Model.CheckinDayOfWeekMultiplier",
      "Factor":2.5,
      "DaysOfWeek":["Monday","Sunday"]
    },
    {
      "@odata.type":"#Model.CheckinDayOfWeekMultiplier",
      "Factor":1.5,
      "DaysOfWeek":["Thursday","Friday","Saturday"]
    }
  ],
  "HotelAssociationCount":0
}

使用旅館

旅館代表您旅館摘要中的旅館。 API 可讓您列出、取得和更新旅館。您無法使用 API 來新增旅館;若要新增旅館，請使用旅館摘要。每個子帳戶的旅館都是唯一的，一個以上的子帳戶可能不包含相同的旅館。

以下是您用來管理旅館的 REST 範本。

/SubAccounts('{subAccountId}')/Hotels — GET
/SubAccounts('{subAccountId}')/HotelGroups('{hotelGroupId}')/Hotels — GET
/SubAccounts('{subAccountId}')/HotelGroups('{hotelGroupId}')/Hotels('{hotelId}') — 取得 | 修補程式

如需取得和更新旅館的範例，請參閱旅館範例。 (使用右窗格中的 [語言] 選取器來查看不同語言的範例。)

列出旅館

根據預設，當您要求旅館群組中的旅館清單時，API 會傳回最多 1,000 家旅館。若要判斷旅館群組中的旅館總數，請使用 $count 查詢參數。若要指定要傳回的旅館數目，請使用 $top 查詢參數。您可以在單一通話中要求的旅館數目上限為 5,000。如果您的旅館群組包含超過 5,000 家旅館，請使用$top和 $skip 查詢參數來逐頁查看旅館。

注意事項

您應該使用$top和$skip查詢參數，只在UI體驗中逐頁瀏覽旅館。若要取得所有旅館，請使用報告功能來下載旅館。

/SubAccounts ('{subAccountId}') /Hotels
/SubAccounts ('{subaccountid}') /HotelGroups ('{hotelgroupid}') /Hotels
/SubAccounts ('{subAccountId}') /Ungrouped

若要取得旅館群組中的前 1,000 家旅館，請傳送下列要求。

GET https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>')/HotelGroups('<hotelgroupid>')/Hotels HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Accept: application/json
Host: <host>

回應包含 CollectionResponse 物件。數位 value 包含 Hotel 物件的清單。

HTTP/1.1 200 OK
Content-Length: 1611
Content-Type: application/json; odata.metadata=minimal
x-ms-requestid: d836f741-8083-4d54-b49e-e1f14287b944
x-ms-trackingid: 3787a393-eca3-4ad0-be3d-dd4c7ae08906

{
  "@odata.count":2,
  "value":[
    {
      "Id":"55113020344013",
      "Name":"Contoso Inn Singer",
      "PartnerHotelId":"942909",
      "Status":"Active",
      "CountryCode":"US",
      "Bid":{
        "@odata.type":"#Model.FixedBid",
        "Amount":2.75
      },
      "BidSource":"HotelGroup",
      "BidMultiplierSource":"HotelGroup",
      "BidMultipliers":[
        {
          "@odata.type":"#Model.DeviceMultiplier",
          "Factor":2.65,
          "DeviceTypes":["Desktop"]
        },
        {
          "@odata.type":"#Model.LengthOfStayMultiplier",
          "Factor":1.3,
          "MinimumNumberOfNights":8
        },
        {
          "@odata.type":"#Model.UserCountryMultiplier",
          "Factor":1.1,
          "Countries":["US"]
        },
        {
          "@odata.type":"#Model.AdvanceBookingWindowMultiplier",
          "Factor":1.3,
          "MinimumNumberOfDays":3
        },
        {
          "@odata.type":"#Model.CheckinDayOfWeekMultiplier",
          "Factor":0.9,
          "DaysOfWeek":["Monday","Sunday"]
        },
        {
          "@odata.type":"#Model.CheckinDayOfWeekMultiplier",
          "Factor":1.2,
          "DaysOfWeek":["Thursday","Friday","Saturday"]
        },
        {
          "@odata.type":"#Model.SiteMultiplier",
          "Factor":0.85,"Sites":["MapResults","LocalUniversal"]
        }
      ]
    },
    {
      "Id":"55113020351595",
      "Name":"Contoso Inn Casino Center",
      "PartnerHotelId":"60278",
      "Status":"Active",
      "CountryCode":"US",
      "Bid":{
        "@odata.type":"#Model.FixedBid",
        "Amount":2.75
      },
      "BidSource":"HotelGroup",
      "BidMultiplierSource":null,
      "BidMultipliers":[]
    }
  ]
}

更新旅館

旅館會指定要用於旅館價格廣告的報價和報價乘數。旅館會明確指定它們，或是依該順序從旅館群組或子帳戶繼承它們。您可以使用 API 來更新要用於旅館廣告的中標和報價乘數。

如需您市場有效報價範圍的詳細資訊，請參閱貨幣主題中的貨幣值數據表。

如果子帳戶指定最高報價，則旅館的報價必須小於子帳戶的最大報價。

若要暫停旅館，請將其 Bid 屬性設定為 PercentageBid 物件，並將百分比的約定金額設定為零 (0.0) 。

如果旅館指定的報價大於零但未提供服務，可能是因為它所屬的旅館群組或子帳戶的報價為零。

若要移除旅館的報價，請將其 Bid 設定為 null (例如“Bid”：null) 。

如果旅館指定了中標乘數，而您想要移除它們，請將設定 BidMultipliers 為空陣列 (例如 “BidMultipliers”：[]) 。

若要更新旅館，請傳送 PATCH 要求。要求可以指定 Microsoft 指派給旅館的標識碼或廣告商指派給旅館的標識碼。如果您指定廣告商指派的標識碼，要求必須將 PartnerHotelId 查詢參數設定為 true。

要求的本文是 Hotel 物件。只包含您想要更新的屬性。此範例顯示更新乘數。

{
  "BidMultipliers":[
    {
      "Countries":["US"],
      "Factor":1.1,
      "@odata.type":"#Model.UserCountryMultiplier"
    },
    {
      "DeviceTypes":["Desktop"],
      "Factor":2.65,
      "@odata.type":"#Model.DeviceMultiplier"
    }
  ]
}

取得旅館

若要取得特定旅館，請傳送下列要求。旅館標識碼必須以單引號包裝，如下所示。

GET https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>')/HotelGroups('<hotelgroupid>')/Hotels('<hotelid>') HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Accept: application/json
Host: <host>

回應包含 Hotel 物件。

HTTP/1.1 200 OK
Content-Length: 1122
Content-Type: application/json; odata.metadata=minimal
x-ms-requestid: a9a591c2-01c1-4e1c-8a6a-5cdece574460
x-ms-trackingid: ceb70eb3-36ca-4b99-a5f7-b1a04de1e4ae

{
  "Id":"55113020344013",
  "Name":"Contoso Inn Singer",
  "PartnerHotelId":"942909",
  "Status":"Active",
  "CountryCode":"US",
  "Bid":{
    "@odata.type":"#Model.FixedBid",
    "Amount":3.0
  },
  "BidSource":"SubAccount",
  "BidSource":"Hotel",
  "BidMultipliers":[
    {
      "@odata.type":"#Model.DeviceMultiplier",
      "Factor":2.65,
      "DeviceTypes":["Desktop"]
    },
    {
      "@odata.type":"#Model.UserCountryMultiplier",
      "Factor":1.1,
      "Countries":["US"]
    }
  ]
}

停留時間長度和進階預約時間乘數

LengthOfStayMultiplier 的描述指出，如果使用者維持指定的夜間數目或更長，Bing 會套用乘數。此外， AdvanceBookingWindowMultiplier 的描述也會指出，如果預約是以指定的天數 或更長的時間事先進行，Bing 就會套用乘數。描述的關鍵部分是片語 ，或是較長的片語。

如果您指定其中一個以上的乘數，則因素和天數/月數的組合必須是唯一的;否則，呼叫會失敗，並出現 DuplicateValues 錯誤。在下列 LengthOfStayMultiplier 範例中，每個專案的因數為 1。因為6個夜間的專案適用於6個夜間或更久的停留時間，所以8個夜間的第二個專案是重複的專案。若要修正此錯誤，只要移除8個夜間的專案，或提供不同的因素值即可。

  {
      "MinimumNumberOfNights": 8,
      "Factor": "1",
      "@odata.type": "#Model.LengthOfStayMultiplier"
    },
    {
      "MinimumNumberOfNights": 6,
      "Factor": "1",
      "@odata.type": "#Model.LengthOfStayMultiplier"
  }

建立旅館與旅館群組的關聯

當您匯入旅館摘要檔案時，旅館會放在 未分組 的旅館群組中，這是預設的旅館群組。旅館只能與一個旅館群組相關聯。如果您建立新的旅館群組以邏輯方式組織旅館，您會想要將旅館從 未分組 的旅館群組移至您建立的新群組。若要將旅館與新的旅館群組建立關聯，請使用關聯範本。當您將旅館與新的旅館群組建立關聯時，服務會移除先前的關聯。

下列 POST 範例示範如何指定關聯。要求的本文是 AssociationCollection 物件。集合最多可包含 500 個 HotelAssociation 物件。

POST https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>')/Associate HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Content-Type: application/json
Host: <host>
Content-Length: 169

{
  "HotelAssociations":[
    {
      "HotelGroupId":"55113020351226",
      "HotelId":"55113020351595"
    },
    {
      "HotelGroupId":"55113020351226",
      "HotelId":"55113020344013"
    }
  ]
}

Associate 方法應該一律傳回成功。如果一或多個關聯失敗，回應會包含失敗關聯的輸入關聯，以及失敗的原因。

回應包含 CollectionResponse 物件。如果所有關聯都成功，則陣 value 列是空的。否則， value 會針對每個失敗的關聯包含 HotelAssociation 物件。關聯的 Errors 欄位包含失敗的原因。

HTTP/1.1 200 OK
Content-Length: 770
Content-Type: application/json; odata.metadata=minimal
x-ms-requestid: 574fe6c6-503d-427d-8921-a259f76de0ed
x-ms-trackingid: a5f2510e-709a-4370-876e-bfb05ef2b8df

{
  "value":[
    {
      "HotelId":"55113020351595",
      "HotelName":null,
      "PartnerHotelId":null,
      "HotelGroupId":"55113020351226",
      "HotelGroupName":null,
      "Errors@odata.type":"#Collection(Model.AdsApiError)",
      "Errors":[
        {
          "Code":"<code>","Property":"<propertyname>","Message":"<messagestring>"
        }
      ]
    }
  ]
}

取得旅館關聯

根據預設，當您要求子帳戶中的關聯清單時，API 會傳回最多 1,000 個關聯。若要判斷關聯的總數，請使用 $count 查詢參數。若要指定要傳回的關聯數目，請使用 $top 查詢參數。您可以在單一呼叫中要求的關聯數目上限為 5,000。如果您的子帳戶包含超過 5,000 個關聯，請使用$top和 $skip 查詢參數來逐頁查看所有關聯。

若要取得子帳戶的前 1,000 家旅館和旅館群組關聯，請傳送下列要求：

GET https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>')/Associations HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Accept: application/json
Host: <host>

回應包含 CollectionResponse 物件。陣 value 列包含 HotelAsssociation 物件的清單。

HTTP/1.1 200 OK
Content-Length: 6880
Content-Type: application/json; odata.metadata=minimal
x-ms-requestid: 50bb9a63-f324-4c28-84f9-733b24ab3d0f
x-ms-trackingid: 4fa56e03-7e86-4f44-b671-8e00a67c2eed

{
  "@odata.count":39540,
  "value":[
    {
      "HotelId":"55113020342273",
      "HotelName":"Contoso Inn Downtown DC/Convention Center",
      "PartnerHotelId":"99995",
      "HotelGroupId":"55113020342274",
      "HotelGroupName":"UnGrouped"
    },
    {
      "HotelId":"55113020342274",
      "HotelName":"The Contoso Hotel",
      "PartnerHotelId":"999896",
      "HotelGroupId":"55113020342274",
      "HotelGroupName":"UnGrouped"
    },
    
    . . .
    
  ]
}

篩選旅館關聯

若要傳回關聯子集，請使用 OData $filter查詢參數。您可以依或PartnerHotelId只篩選關聯HotelId。 URL 長度上限 (2,048) 決定您可以指定的標識碼數目。如果 URL 超過 2,048 個字元，則要求會傳回 404。

下列範例會傳回指定的旅館關聯。

GET https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>')/Associations?$filter=HotelId+eq+'55113020342282'+or+HotelId+eq+'55113020344943' HTTP/1.1
Authorization: Bearer <accesstokengoeshere>
Accept: application/json
Host: <host>

批處理

若要在單一 HTTP 要求中傳送多個要求，請使用 /$batch 範本。您在單一批次要求中最多可以傳送 500 個要求。

注意事項

批處理僅支援旅館更新，例如報價變更。

要求

以下顯示範例要求。

POST https://<host>/Travel/V1/$batch HTTP/1.1
Authorization: Bearer <accesstokengoeshere>
Content-Type: multipart/mixed; boundary=batch_086fe0de-9b26-4d4a-a206-6df2013a2816
Host: <host>
Content-Length: 1371

Content-Type 標頭必須設定為 multipart/mixed，並包含界限標識符。界限標識元不透明，並分隔批次要求中的每個子要求。標識元可以是任何唯一的字串。此範例會使用唯一字串batch_<唯一字串><>為 GUID。

批次要求的主體包含以界限標識符分隔的多個個別要求。以下顯示批次要求本文的範例。請務必使用CRLF (歸位字元和換行字元) ，終止批次要求本文中的每一行。

--batch_086fe0de-9b26-4d4a-a206-6df2013a2816
Content-Type: application/http
Content-Transfer-Encoding: binary

PATCH Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>')/HotelGroups('<groupid>')/Hotels('<hotelid>') HTTP/1.1
Content-Type: application/json; odata.metadata=minimal
Host: partner.api.sandbox.bingads.microsoft.com

{"Id":"<hotelid>","Bid":{"Amount":1.75,"@odata.type":"#Model.FixedBid"}}

--batch_086fe0de-9b26-4d4a-a206-6df2013a2816
Content-Type: application/http
Content-Transfer-Encoding: binary

PATCH Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>')/HotelGroups('groupid>')/Hotels('<hotelid>') HTTP/1.1
Content-Type: application/json; odata.metadata=minimal
Host: partner.api.sandbox.bingads.microsoft.com

{"Id":"<hotelid>","Bid":{"Amount":1.75,"@odata.type":"#Model.FixedBid"}}

--batch_086fe0de-9b26-4d4a-a206-6df2013a2816
Content-Type: application/http
Content-Transfer-Encoding: binary

PATCH Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>')/HotelGroups('groupid>')/Hotels('<hotelid>') HTTP/1.1
Content-Type: application/json; odata.metadata=minimal
Host: partner.api.sandbox.bingads.microsoft.com

{"Id":"<hotelid>","Bid":{"Amount":1.75,"@odata.type":"#Model.FixedBid"}}

--batch_086fe0de-9b26-4d4a-a206-6df2013a2816--

請注意，每個界限標識符前面都會加上雙虛線 (例如， --batch_086fe0de-9b26-4d4a-a206-6df2013a2816) 。批次中最後一個要求之後的終止界限標識符會以雙虛線括住 (例如， --batch_086fe0de-9b26-4d4a-a206-6df2013a2816--) 。

界限標識符分隔符後面必須接著 Content-Type 和 Content-Transfer-Encoding 標頭，如下所示。因為您只能更新旅館，所以要求必須使用 HTTP PATCH 動詞，並使用旅館範本來識別要更新的旅館。要求必須包含 Content-Type 標頭，而且必須設定為 application/json;odata.metadata=minimal。要求的本文是 Hotel 物件。對象必須包含旅館的標識碼，而且應該只包含您要更新的欄位。

回應

回應的分隔方式類似，而且回應中的每個專案會直接對應至要求中的每個專案。回應的 Content-Type 標頭包含界限標識碼。取得標識碼，並使用它來剖析每個響應專案。

下列顯示上述要求的回應。

HTTP/1.1 200 OK
Content-Type: multipart/mixed; boundary=batchresponse_d33d1715-3dd3-45aa-80a9-854493c8764e
x-ms-requestid: c0fb9b49-2af0-4b41-bf57-0e4a0f8b55b9
x-ms-trackingid: 8b652a73-1bef-488d-b7d5-f371a31867a4
Date: Tue, 27 Mar 2018 20:30:19 GMT
Content-Length: 512

--batchresponse_d33d1715-3dd3-45aa-80a9-854493c8764e
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 204 No Content


--batchresponse_d33d1715-3dd3-45aa-80a9-854493c8764e
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 204 No Content


--batchresponse_d33d1715-3dd3-45aa-80a9-854493c8764e
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 204 No Content


--batchresponse_d33d1715-3dd3-45aa-80a9-854493c8764e--

每個回應專案都包含 HTTP 狀態。針對更新，如果更新成功，狀態為 204。例如，如果更新失敗 (找不到旅館、值無效，或旅館物件格式不正確) ，則狀態為 400 且本文包含錯誤清單。 (要求可能會因為其他狀態代碼而失敗。)

下列顯示包含錯誤的回應專案。如果發生錯誤，本文會包含 CollectionResponse 物件，而陣列中的 value 每個專案都是 AdsApiError 物件。

--batchresponse_d0048f4c-8a3f-40aa-9392-718943ecc5f3
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 400 Bad Request
x-ms-requestid: 00b551c2-b552-4cca-9e1b-04e0e5ffb4b7
x-ms-trackingid: ad383e45-4174-43d7-95bc-cca2ac6176e8
Content-Type: application/json; odata.metadata=minimal; odata.streaming=true
OData-Version: 4.0

{
  "@odata.count":1,
  "value":[
    {
      "Code":"EntityDoesNotExist","Property":null,"Message":null
    }
  ]
}
--batchresponse_d0048f4c-8a3f-40aa-9392-718943ecc5f3--

處理批次要求的範例程序代碼

如需在批次要求中更新旅館價格的範例程序代碼，請參閱 Batch 處理範例。

共用方式為

管理旅館廣告活動

使用子帳戶

列出子帳戶

更新子帳戶

取得子帳戶

使用旅館群組

列出旅館群組

新增旅館群組

更新旅館群組

取得旅館群組

使用旅館

列出旅館

更新旅館

取得旅館

停留時間長度和進階預約時間乘數

建立旅館與旅館群組的關聯

取得旅館關聯

篩選旅館關聯

批處理

要求

回應

處理批次要求的範例程序代碼

其他資源