Gerir campanhas do Hotel Ad
Nota
Esta versão beta do Hotel Price Ads está disponível apenas para participantes selecionados. Para obter informações sobre como participar no programa de versão beta, contacte o seu gestor de conta ou inscreva-se aqui.
A API e a documentação estão sujeitas a alterações.
A API de Hotel permite-lhe gerir as suas campanhas publicitárias e licitações do hotel. Uma subconta fornece a organização lógica de nível superior dos seus anúncios de preços de hotel. Pode pensar nisso como uma campanha de alojamento (anteriormente campanhas hoteleiras). Pode ter um máximo de 75 subcontas ativas.
Uma subconta especifica o orçamento diário da campanha, a oferta máxima permitida, a oferta predefinida e os multiplicadores de ofertas para anúncios que não especificam ofertas ou multiplicadores.
Nota
As campanhas publicitárias de hotel referidas aqui não têm qualquer relação com campanhas no Microsoft Advertising.
Se ainda não o fez, familiarize-se com os seguintes tópicos:
Para pontos finais da API de Hotel, veja Pontos finais.
Para obter informações sobre relatórios, veja API de Relatórios de Anúncios de Preços do Hotel.
Trabalhar com subcontas
As subcontas são a organização de nível superior do Hotel Price Ads. O serviço cria a subconta predefinida quando se inscreve no Hotel Price Ads. A API permite-lhe adicionar subcontas, listar subcontas, obter uma subconta específica e atualizar uma subconta.
Seguem-se os modelos REST que utiliza para gerir subcontas.
Para obter um exemplo que obtém e atualiza subcontas, veja exemplos de código. (Utilize o Seletor de idiomas no painel direito para ver o exemplo em idiomas diferentes.)
Listar subcontas
Para obter a lista de subcontas, envie o seguinte pedido.
GET https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Accept: application/json
Host: <host>
A resposta contém um objeto CollectionResponse . A value matriz contém uma 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
}
}
]
}
Atualizar uma subconta
A subconta especifica a oferta predefinida e os multiplicadores de ofertas a utilizar para grupos hoteleiros e hotéis que não especificam uma oferta ou multiplicadores. A subconta também especifica o orçamento que é distribuído ao longo do dia e a oferta máxima que pretende que todas as ofertas não excedam.
Para obter detalhes sobre o intervalo de ofertas válido e o orçamento para o seu mercado, consulte a tabela Valor da Moeda no tópico Moedas .
Para colocar em pausa todos os hotéis na subconta, defina a propriedade da Bid subconta para um objeto PercentageBid e a percentagem de licitação é de zero (0,0).
Se a subconta especificar multiplicadores de ofertas e pretender removê-los, defina BidMultipliers como uma matriz vazia (por exemplo, "BidMultipliers":[]).
Para atualizar uma subconta, envie um pedido PATCH. O corpo do pedido é um objeto SubAccount . Inclua apenas as propriedades que pretende atualizar. Este exemplo mostra a atualização de multiplicadores.
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"
}
]
}
Obter uma subconta
Para obter uma subconta específica, envie o seguinte pedido. O ID da subconta tem de ser moldado entre plicas, conforme mostrado.
GET https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>') HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Accept: application/json
Host: <host>
A resposta contém um 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
}
Trabalhar com grupos hoteleiros
Os grupos hoteleiros são o segundo nível de organização que utiliza para agrupar hotéis. Quando cria uma subconta, o serviço cria um grupo hoteleiro predefinido na subconta denominada Desagrupar. A API permite-lhe listar, obter, atualizar e adicionar grupos de hotéis.
Seguem-se os modelos REST que utiliza para gerir grupos hoteleiros.
/SubAccounts('{subAccountId}')/HotelGroups— OBTER | MENSAGEM/SubAccounts('{subAccountId}')/HotelGroups('{hotelGroupId}')— OBTER | ELIMINAÇÃODE PATCH |
Para obter um exemplo que obtém, adiciona e atualiza grupos hoteleiros, veja exemplos de código. (Utilize o Seletor de idiomas no painel direito para ver o exemplo em idiomas diferentes.)
Listar grupos hoteleiros
Por predefinição, quando pede uma lista de grupos de hotéis numa subconta, a API devolve um máximo de 1000 grupos. Para determinar o número total de grupos na subconta, utilize o parâmetro de consulta $count . Para especificar o número de grupos a devolver, utilize o parâmetro de consulta $top . O número máximo de grupos que pode pedir numa única chamada é 5000. Se a subconta contiver mais de 5000 grupos, utilize os parâmetros de consulta $top e $skip para percorrer todos os grupos.
Para obter uma lista dos primeiros 1000 grupos hoteleiros numa subconta, envie o seguinte pedido.
GET https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>')/HotelGroups HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Accept: application/json
Host: <host>
A resposta contém um objeto CollectionResponse . A value matriz contém uma lista de objetos HotelGroup . Este exemplo mostra o grupo não agrupado predefinido.
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":[]
}
]
}
Adicionar um grupo hoteleiro
Você criaria um novo grupo hoteleiro se você quiser criar um novo agrupamento lógico de hotéis. Para especificar o grupo hoteleiro, utilize o objeto HotelGroup . O único campo necessário é Name. Utilize um nome descritivo que indique o agrupamento. Os Bid campos e BidMultipliers são opcionais. Se não os especificar, o grupo utiliza os multiplicadores de ofertas e licitações da subconta. Especifique-os se pretender substituir os valores da subconta. Pode especificar a oferta, os multiplicadores ou ambos.
Para obter detalhes sobre o intervalo de ofertas válido para o seu mercado, consulte a tabela Valor da Moeda no tópico Moedas .
O exemplo seguinte cria um grupo hoteleiro que herda a oferta e os multiplicadores de ofertas da subconta.
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"}
A resposta é um objeto AddResponse que contém o ID do grupo hoteleiro adicionado.
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"
}
Depois de adicionar um grupo hoteleiro, utilize o modelo de associação para adicionar hotéis ao grupo. Para obter informações, consulte Associar um hotel a um grupo hoteleiro.
Atualizar um grupo hoteleiro
O grupo hoteleiro especifica a oferta predefinida e os multiplicadores de ofertas a utilizar para hotéis no grupo. O grupo especifica-os explicitamente ou herda-os da subconta à qual pertence. Pode utilizar a API para atualizar os multiplicadores de ofertas e ofertas para utilizar em hotéis que não especifiquem uma oferta ou multiplicadores.
Para obter detalhes sobre o intervalo de ofertas válido e o orçamento para o seu mercado, consulte a tabela Valor da Moeda no tópico Moedas .
Se a subconta especificar uma oferta máxima, a oferta do grupo hoteleiro tem de ser inferior à oferta máxima da subconta.
Para colocar em pausa todos os hotéis no grupo hoteleiro, defina a propriedade do Bid grupo para um objeto PercentageBid e a percentagem de licitação é de zero (0,0).
Se o grupo especificar uma oferta superior a zero, mas os hotéis do grupo não estiverem a servir, pode ser porque a oferta da subconta é zero.
Para remover a oferta do grupo hoteleiro, defina Bid como nula (por exemplo, "Licitação":null).
Se o grupo hoteleiro especificar multiplicadores de ofertas e pretender removê-los, defina BidMultipliers como uma matriz vazia (por exemplo, "BidMultipliers":[]).
Para atualizar um grupo hoteleiro, envie um pedido PATCH. O corpo do pedido é um objeto HotelGroup . Inclua apenas as propriedades que pretende atualizar. Este exemplo mostra a atualização da oferta e dos 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"
}
]
}
Obter um grupo de hotéis
Para obter um grupo hoteleiro específico, envie o seguinte pedido. O ID do grupo hoteleiro tem de ser moldado em plicas, conforme mostrado.
GET https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>')/HotelGroups('<hotelgroupid>') HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Accept: application/json
Host: <host>
A resposta contém um 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
}
Trabalhar com hotéis
Os hotéis representam os hotéis no seu feed de hotel. A API permite-lhe listar, obter e atualizar hotéis. Não pode utilizar a API para adicionar hotéis; para adicionar hotéis, utilize o feed hotel. Os hotéis são exclusivos por subconta — mais do que uma subconta pode não conter o mesmo hotel.
Seguem-se os modelos REST que utiliza para gerir hotéis.
/SubAccounts('{subAccountId}')/Hotels— GET/SubAccounts('{subAccountId}')/HotelGroups('{hotelGroupId}')/Hotels— GET/SubAccounts('{subAccountId}')/HotelGroups('{hotelGroupId}')/Hotels('{hotelId}')— OBTER | PATCH
Para obter um exemplo que obtém e atualiza hotéis, veja exemplos de hotéis. (Utilize o Seletor de idiomas no painel direito para ver o exemplo em idiomas diferentes.)
Listar hotéis
Por predefinição, quando pede uma lista de hotéis num grupo hoteleiro, a API devolve um máximo de 1000 hotéis. Para determinar o número total de hotéis no grupo hoteleiro, utilize o parâmetro de consulta $count . Para especificar o número de hotéis a devolver, utilize o parâmetro de consulta $top . O número máximo de hotéis que pode pedir numa única chamada é de 5000. Se o seu grupo hoteleiro contiver mais de 5000 hotéis, utilize os parâmetros de consulta $top e $skip para percorrer os hotéis.
Nota
Deve utilizar os parâmetros de consulta $top e $skip para analisar hotéis apenas numa experiência de IU. Para obter todos os seus hotéis, utilize a funcionalidade Relatórios para transferir os hotéis.
- /SubAccounts('{subAccountId}')/Hotels
- /SubAccounts('{subaccountid}')/HotelGroups('{hotelgroupid}')/Hotéis
- /SubAccounts('{subAccountId}')/Desagrupar
Para obter os primeiros 1.000 hotéis num grupo hoteleiro, envie o seguinte pedido.
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>
A resposta contém um objeto CollectionResponse . A value matriz contém uma lista de objetos do 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":[]
}
]
}
Atualizar um hotel
O hotel especifica a oferta e os multiplicadores de ofertas a usar para anúncios de preços de hotel. O hotel especifica-os explicitamente ou herda-os do grupo hoteleiro ou da subconta, por essa ordem. Pode utilizar a API para atualizar a oferta e os multiplicadores de ofertas para utilizar para o anúncio do hotel.
Para obter detalhes sobre o intervalo de ofertas válido para o seu mercado, consulte a tabela Valor da Moeda no tópico Moedas .
Se a subconta especificar uma oferta máxima, a oferta do hotel tem de ser inferior à oferta máxima da subconta.
Para colocar um hotel em pausa, defina a respetiva Bid propriedade para um objeto PercentageBid e a percentagem de licitação é de zero (0,0).
Se o hotel especificar uma oferta superior a zero mas não estiver a servir, pode ser porque a oferta do grupo hoteleiro ou subconta a que pertence é zero.
Para remover a oferta de um hotel, defina-a Bid como nula (por exemplo, "Licitação":null).
Se o hotel especificar multiplicadores de ofertas e pretender removê-los, defina BidMultipliers como uma matriz vazia (por exemplo, "BidMultipliers":[]).
Para atualizar um hotel, envie um pedido PATCH . O pedido pode especificar o ID que a Microsoft atribuiu ao hotel ou ID que o anunciante atribuiu ao hotel. Se especificar o ID atribuído pelo anunciante, o pedido tem de definir o parâmetro de consulta PartnerHotelId como verdadeiro.
O corpo do pedido é um objeto hotel . Inclua apenas as propriedades que pretende atualizar. Este exemplo mostra a atualização dos multiplicadores.
{
"BidMultipliers":[
{
"Countries":["US"],
"Factor":1.1,
"@odata.type":"#Model.UserCountryMultiplier"
},
{
"DeviceTypes":["Desktop"],
"Factor":2.65,
"@odata.type":"#Model.DeviceMultiplier"
}
]
}
Obter um hotel
Para obter um hotel específico, envie o seguinte pedido. O ID do hotel deve estar embrulhado em plicas, conforme mostrado.
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>
A resposta contém um 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"]
}
]
}
Duração da estadia e multiplicadores avançados da janela de reservas
A descrição de LengthOfStayMultiplier indica que o Bing aplica o multiplicador se o utilizador permanecer no número especificado de noites ou mais. E a descrição de AdvanceBookingWindowMultiplier também diz que o Bing aplica o multiplicador se a reserva ocorrer antecipadamente o número especificado de dias ou mais. A parte fundamental da descrição é a expressão ou mais longa.
Se especificar mais do que um destes multiplicadores, a combinação de fator e dias/noites tem de ser exclusiva; caso contrário, a chamada falha com um erro DuplicateValues. No seguinte exemplo LengthOfStayMultiplier, o fator para cada entrada é 1. Uma vez que a entrada para 6 noites se aplica a estadias de 6 noites ou mais, a segunda entrada para 8 noites é duplicada. Para corrigir este erro, basta remover a entrada durante 8 noites ou fornecer um valor de fator diferente.
{
"MinimumNumberOfNights": 8,
"Factor": "1",
"@odata.type": "#Model.LengthOfStayMultiplier"
},
{
"MinimumNumberOfNights": 6,
"Factor": "1",
"@odata.type": "#Model.LengthOfStayMultiplier"
}
Associar um hotel a um grupo hoteleiro
Quando importa o seu ficheiro de feed de hotel, os hotéis são colocados no grupo hoteleiro Sem Grupo , que é o grupo hoteleiro predefinido. Um hotel pode estar associado a apenas um grupo hoteleiro. Se criar um novo grupo hoteleiro para organizar logicamente os seus hotéis, vai querer mudar os hotéis do grupo hoteleiro Desagrupar para o novo grupo que criou. Para associar um hotel a um novo grupo hoteleiro, utilize o modelo Associar . Quando associa um hotel a um novo grupo hoteleiro, o serviço remove a associação anterior.
O exemplo post seguinte mostra como especificar a associação. O corpo do pedido é um objeto AssociationCollection . A coleção pode conter um 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"
}
]
}
O método Associado deve sempre devolver êxito. Se uma ou mais das associações falharem, a resposta contém a associação de entrada das associações falhadas e o motivo da falha.
A resposta contém um objeto CollectionResponse . Se todas as associações forem bem-sucedidas, a value matriz estará vazia. Caso contrário, value contém um objeto HotelAssociation para cada associação que falhou. O campo da Errors associação contém os motivos da falha.
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>"
}
]
}
]
}
Obter associações hoteleiras
Por predefinição, quando pede uma lista de associações numa subconta, a API devolve um máximo de 1000 associações. Para determinar o número total de associações, utilize o parâmetro de consulta $count . Para especificar o número de associações a devolver, utilize o parâmetro de consulta $top . O número máximo de associações que pode pedir numa única chamada é 5000. Se a sua subconta contiver mais de 5000 associações, utilize os parâmetros de consulta $top e $skip para analisar todas as associações.
Para obter as primeiras 1000 associações de hotéis e grupos hoteleiros para uma subconta, envie o seguinte pedido:
GET https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>')/Associations HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Accept: application/json
Host: <host>
A resposta contém um objeto CollectionResponse . A value matriz contém uma lista de objetos HotelAssociation .
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"
},
. . .
]
}
Filtrar associações hoteleiras
Para devolver um subconjunto de associações, utilize o parâmetro de consulta OData $filter. Pode filtrar associações por HotelId ou PartnerHotelId apenas. O comprimento máximo do URL (2048) determina o número de IDs que pode especificar. Se o URL exceder 2048 carateres, o pedido devolve 404.
Segue-se um exemplo que devolve as associações hoteleiras 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>
Processamento em lotes
Para enviar vários pedidos num único pedido HTTP, utilize o modelo /$batch . Pode enviar um máximo de 500 pedidos num único pedido em lote.
Nota
O processamento em lotes é suportado apenas para atualizações de hotéis, como alterações de oferta.
O pedido
Segue-se um pedido de exemplo.
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
O cabeçalho Content-Type tem de ser definido como multipart/mixed e incluir o ID de limite. O ID de limite é opaco e delimita cada sub-pedido no pedido de lote. O ID pode ser qualquer cadeia exclusiva. Este exemplo utiliza uma cadeia batch_<unique>, em <que a cadeia> exclusiva é um GUID.
O corpo do pedido em lote contém vários pedidos individuais delimitados pelo ID de limite. Segue-se um exemplo do corpo de um pedido em lote. Certifique-se de que termina cada linha no corpo do pedido de lote com CRLF (símbolo de retorno e alimentação de linha).
--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--
Tenha em atenção que cada ID de limite é precedido com um travessão duplo (por exemplo, --batch_086fe0de-9b26-4d4a-a206-6df2013a2816). E o ID de limite de terminação que vai atrás do último pedido no lote é incluído com traços duplos (por exemplo, --batch_086fe0de-9b26-4d4a-a206-6df2013a2816--).
O delimitador de ID de limite tem de ser seguido pelos cabeçalhos Content-Type e Content-Transfer-Encoding, conforme mostrado. Uma vez que só pode atualizar hotéis, o pedido tem de utilizar o verbo HTTP PATCH e utilizar o modelo de hotel para identificar o hotel a atualizar. O pedido tem de incluir o cabeçalho Content-Type e tem de ser definido como application/json; odata.metadata=minimal. O corpo do pedido é um objeto hotel . O objeto tem de incluir o ID do hotel e deve incluir apenas os campos que está a atualizar.
A resposta
A resposta é igualmente delimitada e cada item na resposta corresponde diretamente a cada item no pedido. O cabeçalho Content-Type da resposta contém o ID de limite. Obtenha o ID e utilize-o para analisar cada item de resposta.
O seguinte mostra a resposta ao pedido acima.
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 item de resposta contém um estado HTTP. Para atualizações, se a atualização for bem-sucedida, o estado é 204. Se a atualização falhar (por exemplo, o hotel não foi encontrado, um valor não é válido ou o objeto do hotel está mal formado), o estado é 400 e o corpo contém uma lista de erros. (Um pedido pode falhar com outros códigos de estado.)
O seguinte mostra um item de resposta que contém um erro. Se ocorrer um erro, o corpo contém um objeto CollectionResponse e cada item na value matriz é um 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 exemplo para processar pedidos em lote
Por exemplo, código que atualiza os preços dos hotéis num pedido de lote, veja Exemplo de processamento do Batch.