管理酒店广告市场活动
使用酒店 API 可以管理酒店广告市场活动和出价。 子帐户提供酒店价格广告的顶级逻辑组织。 你可以把它想象成一个住宿运动 (以前酒店运动) 。 最多可以有 75 个活动子帐户。
子帐户指定市场活动的每日预算、允许的最高出价以及未指定出价或乘数的广告的默认出价和出价乘数。
注意
此处提到的酒店广告活动与 Microsoft Advertising 中的市场活动没有任何关系。
如果尚未这样做，请熟悉以下主题：
有关酒店 API 终结点，请参阅 终结点。
有关报告的信息，请参阅 酒店价格广告报告 API。
使用子帐户
子帐户是酒店价格广告的顶级组织。 当你注册酒店价格广告时，该服务会为你创建默认的子帐户。 通过 API，可以添加子帐户、列出子帐户、获取特定子帐户以及更新子帐户。
下面是用于管理子帐户的 REST 模板。
有关获取和更新子帐户的示例，请参阅 代码示例。 (使用右窗格中的语言选择器查看不同语言的示例。)
列出子帐户
若要获取子帐户列表，请发送以下请求。
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
}
}
]
}
更新子帐户
子帐户指定用于酒店组和酒店的默认出价和出价乘数，这些乘数未指定出价或乘数。 子帐户还指定了一天中的预算，以及你希望所有出价不超过的最大出价。
有关市场的有效出价范围和预算的详细信息，请参阅货币主题中的 货币 价值表。
若要暂停子帐户中的所有酒店，请将子帐户的属性 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"
}
]
}
获取子帐户
若要获取特定的子帐户，请发送以下请求。 子帐户 ID 必须用单引号包装，如下所示。
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— GET | POST/SubAccounts('{subAccountId}')/HotelGroups('{hotelGroupId}')— GET | PATCH | DELETE
有关获取、添加和更新酒店组的示例，请参阅 代码示例。 (使用右窗格中的语言选择器查看不同语言的示例。)
列出酒店组
默认情况下，当你请求子帐户下的酒店组列表时，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。 使用指示分组的描述性名称。 Bid 和 BidMultipliers 是可选字段。 如果未指定它们，组将使用子帐户中的出价和出价乘数。 如果要替代子帐户值，请指定它们。 可以指定出价和/或乘数。
有关市场有效出价范围的详细信息，请参阅货币主题中的 货币 价值表。
以下示例创建一个酒店组，该组从子帐户继承出价和出价乘数。
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 对象，其中包含添加的酒店组的 ID。
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"
}
]
}
获取酒店组
若要获取特定的酒店组，请发送以下请求。 酒店组 ID 必须包装在单引号中，如下所示。
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
}
使用酒店
Hotels 表示酒店源中的酒店。 通过 API，可以列出、获取和更新酒店。 不能使用 API 添加酒店;若要添加酒店，请使用 Hotel 源。 酒店在每个子帐户中是唯一的 - 多个子帐户可能不包含同一家酒店。
下面是用于管理酒店的 REST 模板。
/SubAccounts('{subAccountId}')/Hotels— GET/SubAccounts('{subAccountId}')/HotelGroups('{hotelGroupId}')/Hotels— GET/SubAccounts('{subAccountId}')/HotelGroups('{hotelGroupId}')/Hotels('{hotelId}')— GET | PATCH
有关获取和更新酒店的示例，请参阅 酒店示例。 (使用右窗格中的语言选择器查看不同语言的示例。)
列出酒店
默认情况下，当你请求酒店组中的酒店列表时，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 分配给酒店的 ID 或广告客户分配给酒店的 ID。 如果指定广告商分配的 ID，则请求必须将 PartnerHotelId 查询参数设置为 true。
请求的正文是 一个 Hotel 对象。 仅包括要更新的属性。 此示例演示如何更新乘数。
{
"BidMultipliers":[
{
"Countries":["US"],
"Factor":1.1,
"@odata.type":"#Model.UserCountryMultiplier"
},
{
"DeviceTypes":["Desktop"],
"Factor":2.65,
"@odata.type":"#Model.DeviceMultiplier"
}
]
}
获取酒店
若要获取特定酒店，请发送以下请求。 酒店 ID 必须用单引号包装，如下所示。
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 的说明显示，如果用户停留指定的天数或更长时间，必应将应用乘数。 而 AdvanceBookingWindowMultiplier 的说明还显示，如果提前在指定的天数或更长时间内进行预订，必应会应用乘数。 说明的关键部分是短语 或较长时间。
如果指定了多个乘数，则因子和日/夜的组合必须是唯一的;否则，调用失败并出现 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 查询参数。 可以按 HotelId 或 PartnerHotelId 仅筛选关联。 最大 URL 长度 (2,048) 确定可以指定的 ID 数。 如果 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 标头必须设置为多部分/混合，并包含边界 ID。 边界 ID 不透明，并分隔批处理请求中的每个子请求。 ID 可以是任何唯一字符串。 此示例使用 batch_<unique 字符串>，其中 <唯一字符串> 是 GUID。
批处理请求的正文包含由边界 ID 分隔的多个单独请求。 下面显示了批处理请求的正文示例。 请务必使用 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--
请注意，每个边界 ID 前面都附加了一个双短划线 (例如 --，batch_086fe0de-9b26-4d4a-a206-6df2013a2816) 。 批处理中最后一个请求之后的终止边界 ID 用双短划线 (括起来， --例如，batch_086fe0de-9b26-4d4a-a206-6df2013a2816--) 。
边界 ID 分隔符后面必须跟 Content-Type 和 Content-Transfer-Encoding 标头，如下所示。 由于只能更新酒店，因此请求必须使用 HTTP PATCH 谓词并使用 酒店 模板来标识要更新的酒店。 请求必须包含 Content-Type 标头，并且必须设置为 application/json;odata.metadata=minimal。 请求的正文是 一个 Hotel 对象。 对象必须包含酒店的 ID，并且应仅包含要更新的字段。
响应
响应以类似的方式分隔，响应中的每个项直接对应于请求中的每个项。 响应的 Content-Type 标头包含边界 ID。 获取 ID 并使用它来分析每个响应项。
下面显示了对上述请求的响应。
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。 例如，如果更新失败 (找不到 hotel、值无效或 hotel 对象) 格式不正确，则状态为 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--
处理批处理请求的示例代码
有关在批处理请求中更新酒店定价的示例代码，请参阅 批处理示例。