Administración de campañas de Hotel Ad
Nota:
Esta versión beta de Hotel Price Ads solo está disponible para seleccionar participantes. Para obtener información sobre cómo participar en el programa de versión beta, póngase en contacto con el administrador de cuentas o inscríbase aquí.
La API y la documentación están sujetas a cambios.
La API de hotel te permite administrar tus campañas de anuncios de hotel y pujas. Una subcuenta proporciona la organización lógica de nivel superior de los anuncios de precios de hoteles. Se puede considerar como una campaña de hospedaje (anteriormente campañas de hoteles). Puede tener un máximo de 75 subcuentas activas.
Una subcuenta especifica el presupuesto diario de la campaña, la puja máxima permitida y los multiplicadores predeterminados de pujas y pujas para los anuncios que no especifican pujas ni multiplicadores.
Nota:
Las campañas publicitarias de hotel a las que se hace referencia aquí no tienen ninguna relación con las campañas de Microsoft Advertising.
Si aún no lo ha hecho, familiarícese con los temas siguientes:
Para los puntos de conexión de La API de hotel, consulte Puntos de conexión.
Para obtener información sobre los informes, consulte La API de informes de anuncios de precios de hotel.
Trabajar con subcuentas
Las subcuentas son la organización de primer nivel de Los anuncios de precios de hotel. El servicio crea la subcuenta predeterminada cuando se registra en Anuncios de precios de hotel. La API le permite agregar subcuentas, enumerar subcuentas, obtener una subcuenta específica y actualizar una subcuenta.
A continuación se muestran las plantillas rest que se usan para administrar subcuentas.
Para obtener un ejemplo que obtiene y actualiza las subcuentas, consulte ejemplos de código. (Use el selector de idioma en el panel derecho para ver el ejemplo en diferentes idiomas).
Enumeración de subcuentas
Para obtener la lista de subcuentas, envíe la siguiente solicitud.
GET https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Accept: application/json
Host: <host>
La respuesta contiene un objeto CollectionResponse . La value matriz contiene una lista de objetos 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
}
}
]
}
Actualización de una subcuenta
La subcuenta especifica los multiplicadores predeterminados de puja y puja que se usarán para los grupos de hoteles y hoteles que no especifican una puja o multiplicadores. La subcuenta también especifica el presupuesto que se distribuye a lo largo del día y la puja máxima que quiere que no superen todas las pujas.
Para obtener más información sobre el intervalo de pujas y el presupuesto válidos para su mercado, consulte la tabla Valor de moneda en el tema Monedas .
Para pausar todos los hoteles de la subcuenta, establezca la propiedad de Bid la subcuenta en un objeto PercentageBid y el porcentaje de puja en cero (0,0).
Si la subcuenta especifica multiplicadores de puja y desea quitarlos, establezca en BidMultipliers una matriz vacía (por ejemplo, "BidMultipliers":[]).
Para actualizar una subcuenta, envíe una solicitud PATCH. El cuerpo de la solicitud es un objeto SubAccount . Incluya solo las propiedades que desea actualizar. En este ejemplo se muestran los multiplicadores de actualización.
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"
}
]
}
Obtención de una subcuenta
Para obtener una subcuenta específica, envíe la siguiente solicitud. El identificador de subcuenta debe ajustarse entre comillas simples, como se muestra.
GET https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>') HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Accept: application/json
Host: <host>
La respuesta contiene un objeto 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
}
Trabajar con grupos de hoteles
Los grupos de hoteles son el segundo nivel de organización que se usa para agrupar hoteles. Al crear una subcuenta, el servicio crea un grupo de hoteles predeterminado en la subcuenta denominada Ungrouped. La API le permite enumerar, obtener, actualizar y agregar grupos de hoteles.
A continuación se muestran las plantillas REST que se usan para administrar grupos de hoteles.
/SubAccounts('{subAccountId}')/HotelGroups— GET | POST/SubAccounts('{subAccountId}')/HotelGroups('{hotelGroupId}')— GET | PATCH | DELETE
Para obtener un ejemplo que obtiene, agrega y actualiza grupos de hoteles, consulte ejemplos de código. (Use el selector de idioma en el panel derecho para ver el ejemplo en diferentes idiomas).
Enumeración de grupos de hoteles
De forma predeterminada, cuando se solicita una lista de grupos de hoteles en una subcuenta, la API devuelve un máximo de 1000 grupos. Para determinar el número total de grupos de la subcuenta, use el parámetro de consulta $count . Para especificar el número de grupos que se van a devolver, use el parámetro de consulta $top . El número máximo de grupos que puede solicitar en una sola llamada es de 5000. Si la subcuenta contiene más de 5 000 grupos, use los parámetros de consulta $top y $skip para paginar todos los grupos.
Para obtener una lista de los primeros 1000 grupos de hoteles en una subcuenta, envíe la siguiente solicitud.
GET https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>')/HotelGroups HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Accept: application/json
Host: <host>
La respuesta contiene un objeto CollectionResponse . La value matriz contiene una lista de objetos HotelGroup . En este ejemplo se muestra el grupo sin agrupar predeterminado.
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":[]
}
]
}
Adición de un grupo de hoteles
Crearía un nuevo grupo de hoteles si desea crear una nueva agrupación lógica de hoteles. Para especificar el grupo de hoteles, use el objeto HotelGroup . El único campo necesario es Name. Use un nombre descriptivo que indique la agrupación. Los campos Bid y BidMultipliers son opcionales. Si no los especifica, el grupo usa los multiplicadores de puja y puja de la subcuenta. Especifíquelos si desea invalidar los valores de la subcuenta. Puede especificar la puja, los multiplicadores o ambos.
Para obtener más información sobre el intervalo de pujas válido para el mercado, consulte la tabla Valor de moneda del tema Monedas .
En el ejemplo siguiente se crea un grupo de hoteles que hereda los multiplicadores de puja y puja de la subcuenta.
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"}
La respuesta es un objeto AddResponse que contiene el identificador del grupo de hoteles agregado.
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"
}
Después de agregar un grupo de hoteles, use la plantilla de asociación para agregar hoteles al grupo. Para obtener información, consulte Asociación de un hotel con un grupo de hoteles.
Actualización de un grupo de hoteles
El grupo hotelero especifica los multiplicadores de puja y puja predeterminados que se usarán para los hoteles del grupo. El grupo los especifica explícitamente o los hereda de la subcuenta a la que pertenece. Puede usar la API para actualizar los multiplicadores de pujas y pujas para usarlos en hoteles que no especifiquen una puja o multiplicadores.
Para obtener más información sobre el intervalo de pujas y el presupuesto válidos para su mercado, consulte la tabla Valor de moneda en el tema Monedas .
Si la subcuenta especifica una oferta máxima, la oferta del grupo hotelero debe ser menor que la puja máxima de la subcuenta.
Para pausar todos los hoteles del grupo de hoteles, establezca la propiedad del Bid grupo en un objeto PercentageBid y el porcentaje de puja en cero (0,0).
Si el grupo especifica una puja mayor que cero pero los hoteles del grupo no sirven, puede deberse a que la oferta de la subcuenta es cero.
Para quitar la puja del grupo de hoteles, establezca en Bid null (por ejemplo, "Bid":null).
Si el grupo de hoteles especifica multiplicadores de puja y desea quitarlos, establezca en BidMultipliers una matriz vacía (por ejemplo, "BidMultipliers":[]).
Para actualizar un grupo de hoteles, envíe una solicitud PATCH. El cuerpo de la solicitud es un objeto HotelGroup . Incluya solo las propiedades que desea actualizar. En este ejemplo se muestra cómo actualizar la puja y los multiplicadores.
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"
}
]
}
Obtención de un grupo de hoteles
Para obtener un grupo de hoteles específico, envíe la siguiente solicitud. El id. de grupo de hotel debe ajustarse entre comillas simples, como se muestra.
GET https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>')/HotelGroups('<hotelgroupid>') HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Accept: application/json
Host: <host>
La respuesta contiene un objeto 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
}
Trabajar con hoteles
Los hoteles representan los hoteles en tu fuente de hoteles. La API le permite enumerar, obtener y actualizar hoteles. No puede usar la API para agregar hoteles; para agregar hoteles, use la fuente hotelera. Los hoteles son únicos por subcuenta: es posible que más de una subcuenta no contenga el mismo hotel.
A continuación se muestran las plantillas REST que se usan para administrar hoteles.
/SubAccounts('{subAccountId}')/Hotels— GET/SubAccounts('{subAccountId}')/HotelGroups('{hotelGroupId}')/Hotels— GET/SubAccounts('{subAccountId}')/HotelGroups('{hotelGroupId}')/Hotels('{hotelId}')— GET | PATCH
Para obtener un ejemplo que obtiene y actualiza los hoteles, consulte ejemplos de hoteles. (Use el selector de idioma en el panel derecho para ver el ejemplo en diferentes idiomas).
Listado de hoteles
De forma predeterminada, cuando se solicita una lista de hoteles en un grupo de hoteles, la API devuelve un máximo de 1000 hoteles. Para determinar el número total de hoteles del grupo de hoteles, use el parámetro de consulta $count . Para especificar el número de hoteles que se van a devolver, use el parámetro de consulta $top . El número máximo de hoteles que puede solicitar en una sola llamada es de 5000. Si el grupo de hoteles contiene más de 5.000 hoteles, use los parámetros de consulta $top y $skip para paginar los hoteles.
Nota:
Debe usar los parámetros de consulta $top y $skip para paginar solo los hoteles en una experiencia de interfaz de usuario. Para obtener todos los hoteles, use la característica Informes para descargar los hoteles.
- /SubAccounts('{subAccountId}')/Hotels
- /SubAccounts('{subaccountid}')/HotelGroups('{hotelgroupid}')/Hotels
- /SubAccounts('{subAccountId}')/Ungrouped
Para obtener los primeros 1000 hoteles de un grupo hotelero, envíe la siguiente solicitud.
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>
La respuesta contiene un objeto CollectionResponse . La value matriz contiene una lista de objetos 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":[]
}
]
}
Actualizar un hotel
El hotel especifica los multiplicadores de pujas y pujas que se usarán para los anuncios de precios del hotel. El hotel los especifica explícitamente o los hereda del grupo de hoteles o subcuenta, en ese orden. Puedes usar la API para actualizar los multiplicadores de pujas y pujas que se usarán para el anuncio del hotel.
Para obtener más información sobre el intervalo de pujas válido para el mercado, consulte la tabla Valor de moneda del tema Monedas .
Si la subcuenta especifica una oferta máxima, la oferta del hotel debe ser menor que la puja máxima de la subcuenta.
Para pausar un hotel, establezca su Bid propiedad en un objeto PercentageBid y el importe de la puja porcentual en cero (0,0).
Si el hotel especifica una oferta mayor que cero pero no sirve, puede deberse a que la oferta del grupo hotelero o subcuenta a la que pertenece es cero.
Para quitar la oferta de un hotel, establezca en Bid null (por ejemplo, "Bid":null).
Si el hotel especifica multiplicadores de puja y desea quitarlos, establezca en BidMultipliers una matriz vacía (por ejemplo, "BidMultipliers":[]).
Para actualizar un hotel, envíe una solicitud PATCH . La solicitud puede especificar el id. que Microsoft asignó al hotel o al identificador que el anunciante asignó al hotel. Si especifica el identificador asignado por el anunciante, la solicitud debe establecer el parámetro de consulta PartnerHotelId en true.
El cuerpo de la solicitud es un objeto Hotel . Incluya solo las propiedades que desea actualizar. En este ejemplo se muestra cómo actualizar los multiplicadores.
{
"BidMultipliers":[
{
"Countries":["US"],
"Factor":1.1,
"@odata.type":"#Model.UserCountryMultiplier"
},
{
"DeviceTypes":["Desktop"],
"Factor":2.65,
"@odata.type":"#Model.DeviceMultiplier"
}
]
}
Obtención de un hotel
Para obtener un hotel específico, envíe la siguiente solicitud. El id. del hotel debe ajustarse entre comillas simples, como se muestra.
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>
La respuesta contiene un objeto 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"]
}
]
}
Duración de la estancia y multiplicadores de ventana de reserva avanzada
La descripción de LengthOfStayMultiplier indica que Bing aplica el multiplicador si el usuario permanece el número especificado de noches o más. Y la descripción de AdvanceBookingWindowMultiplier también indica que Bing aplica el multiplicador si la reserva se produce de antemano el número especificado de días o más. La parte clave de la descripción es la frase o más larga.
Si especifica más de uno de estos multiplicadores, la combinación de factor y días/noches debe ser única; De lo contrario, la llamada produce un error DuplicateValues. En el siguiente ejemplo LengthOfStayMultiplier, el factor para cada entrada es 1. Dado que la entrada de 6 noches se aplica a estancias de 6 noches o más, la segunda entrada para 8 noches es un duplicado. Para corregir este error, basta con quitar la entrada durante 8 noches o proporcionar un valor de factor diferente.
{
"MinimumNumberOfNights": 8,
"Factor": "1",
"@odata.type": "#Model.LengthOfStayMultiplier"
},
{
"MinimumNumberOfNights": 6,
"Factor": "1",
"@odata.type": "#Model.LengthOfStayMultiplier"
}
Asociación de un hotel con un grupo de hoteles
Al importar el archivo de fuente del hotel, los hoteles se colocan en el grupo de hoteles no agrupados , que es el grupo de hoteles predeterminado. Un hotel solo puede estar asociado a un grupo de hoteles. Si crea un nuevo grupo de hoteles para organizar lógicamente los hoteles, querrá mover los hoteles del grupo de hoteles no agrupados al nuevo grupo que ha creado. Para asociar un hotel a un nuevo grupo de hoteles, use la plantilla Asociar . Al asociar un hotel a un nuevo grupo de hoteles, el servicio elimina la asociación anterior.
En el siguiente ejemplo POST, se muestra cómo especificar la asociación. El cuerpo de la solicitud es un objeto AssociationCollection . La colección puede contener un máximo de 500 objetos 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"
}
]
}
El método Associate siempre debe devolver correctamente. Si se produce un error en una o varias de las asociaciones, la respuesta contiene la asociación de entrada de las asociaciones con errores y el motivo del error.
La respuesta contiene un objeto CollectionResponse . Si todas las asociaciones se realizaron correctamente, la value matriz está vacía. De lo contrario, value contiene un objeto HotelAssociation para cada asociación con errores. El campo de la Errors asociación contiene los motivos del error.
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>"
}
]
}
]
}
Obtención de asociaciones de hoteles
De forma predeterminada, al solicitar una lista de asociaciones en una subcuenta, la API devuelve un máximo de 1000 asociaciones. Para determinar el número total de asociaciones, use el parámetro de consulta $count . Para especificar el número de asociaciones que se van a devolver, use el parámetro de consulta $top . El número máximo de asociaciones que puede solicitar en una sola llamada es de 5000. Si la subcuenta contiene más de 5000 asociaciones, use los parámetros de consulta $top y $skip para pasar página a través de todas las asociaciones.
Para obtener las primeras 1000 asociaciones de hoteles y grupos de hoteles para una subcuenta, envíe la siguiente solicitud:
GET https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>')/Associations HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Accept: application/json
Host: <host>
La respuesta contiene un objeto CollectionResponse . La value matriz contiene una lista de objetos 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"
},
. . .
]
}
Filtrado de asociaciones hotelera
Para devolver un subconjunto de asociaciones, use el parámetro de consulta OData $filter. Puede filtrar las asociaciones por HotelId o PartnerHotelId solo. La longitud máxima de la dirección URL (2048) determina el número de identificadores que puede especificar. Si la dirección URL supera los 2.048 caracteres, la solicitud devuelve 404.
A continuación se muestra un ejemplo que devuelve las asociaciones de hoteles especificadas.
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>
Procesamiento por lotes
Para enviar varias solicitudes en una sola solicitud HTTP, use la plantilla /$batch . Puede enviar un máximo de 500 solicitudes en una sola solicitud por lotes.
Nota:
El procesamiento por lotes solo se admite para las actualizaciones de hoteles, como los cambios de puja.
La solicitud
A continuación se muestra una solicitud de ejemplo.
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
El encabezado Content-Type debe establecerse en multipart/mixed e incluir el identificador de límite. El identificador de límite es opaco y delimita cada solicitud secundaria de la solicitud por lotes. El identificador puede ser cualquier cadena única. En este ejemplo se usa la cadena> batch_<unique, donde <la cadena> única es un GUID.
El cuerpo de la solicitud por lotes contiene varias solicitudes individuales delimitadas por el identificador de límite. A continuación se muestra un ejemplo del cuerpo de una solicitud por lotes. Asegúrese de finalizar cada línea del cuerpo de la solicitud por lotes con CRLF (retorno de carro y avance de línea).
--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--
Tenga en cuenta que cada identificador de límite se antepone con un guion doble (por ejemplo, --batch_086fe0de-9b26-4d4a-a206-6df2013a2816). Y el identificador de límite de terminación que va después de la última solicitud del lote se incluye con guiones dobles (por ejemplo, --batch_086fe0de-9b26-4d4a-a206-6df2013a2816--).
El delimitador de identificador de límite debe ir seguido de los encabezados Content-Type y Content-Transfer-Encoding, como se muestra. Dado que solo puede actualizar hoteles, la solicitud debe usar el verbo HTTP PATCH y usar la plantilla de hotel para identificar el hotel que se va a actualizar. La solicitud debe incluir el encabezado Content-Type y debe establecerse en application/json; odata.metadata=minimal. El cuerpo de la solicitud es un objeto Hotel . El objeto debe incluir el identificador del hotel y solo debe incluir los campos que va a actualizar.
La respuesta
La respuesta está delimitada de forma similar y cada elemento de la respuesta corresponde directamente a cada elemento de la solicitud. El encabezado Content-Type de la respuesta contiene el identificador de límite. Obtenga el identificador y úselo para analizar cada elemento de respuesta.
A continuación se muestra la respuesta a la solicitud anterior.
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--
Cada elemento de respuesta contiene un estado HTTP. En el caso de las actualizaciones, si la actualización se realiza correctamente, el estado es 204. Si se produce un error en la actualización (por ejemplo, no se encontró el hotel, un valor no es válido o el objeto de hotel tiene un formato incorrecto), el estado es 400 y el cuerpo contiene una lista de errores. (Es posible que se produzca un error en una solicitud con otros códigos de estado).
A continuación se muestra un elemento de respuesta que contiene un error. Si se produce un error, el cuerpo contiene un objeto CollectionResponse y cada elemento de la value matriz es un objeto 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--
Código de ejemplo para procesar solicitudes por lotes
Para obtener código de ejemplo que actualiza los precios de hotel en una solicitud por lotes, vea Ejemplo de procesamiento por lotes.