Gestire le campagne di Hotel Ad
Nota
Questa versione beta di Hotel Price Ads è disponibile solo per selezionare i partecipanti. Per informazioni sulla partecipazione al programma di versione beta, contattare il proprio account manager o registrarsi qui.
L'API e la documentazione sono soggette a modifiche.
L'API Hotel consente di gestire le campagne pubblicitarie e le offerte degli hotel. Un account secondario fornisce l'organizzazione logica di primo livello degli annunci sui prezzi degli hotel. Si può pensare ad esso come una campagna di alloggio (in precedenza campagne di hotel). È possibile che siano presenti al massimo 75 account secondari attivi.
Un account secondario specifica il budget giornaliero della campagna, l'offerta massima consentita e i moltiplicatori di offerte e offerte predefiniti per gli annunci che non specificano offerte o moltiplicatori.
Nota
Le campagne pubblicitarie di hotel a cui si fa riferimento qui non hanno alcuna relazione con le campagne in Microsoft Advertising.
Se non è già stato fatto, acquisire familiarità con gli argomenti seguenti:
Per gli endpoint dell'API Hotel, vedere Endpoint.
Per informazioni sulla creazione di report, vedere API Report di Hotel Price Ads.
Uso degli account secondari
Gli account secondari sono l'organizzazione di primo livello di Hotel Price Ads. Il servizio crea automaticamente l'account secondario predefinito quando si esegue l'iscrizione ad Hotel Price Ads. L'API consente di aggiungere account secondari, elencare gli account secondari, ottenere un account secondario specifico e aggiornare un account secondario.
Di seguito sono riportati i modelli REST usati per gestire gli account secondari.
Per un esempio che ottiene e aggiorna gli account secondari, vedere esempi di codice. Usare il selettore Lingua nel riquadro di destra per visualizzare l'esempio in lingue diverse.
Elencare gli account secondari
Per ottenere l'elenco degli account secondari, inviare la richiesta seguente.
GET https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Accept: application/json
Host: <host>
La risposta contiene un oggetto CollectionResponse . La value matrice contiene un elenco di oggetti 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
}
}
]
}
Aggiornamento di un account secondario
Il sottoaccount specifica i moltiplicatori di offerte e offerte predefiniti da utilizzare per gruppi di hotel e hotel che non specificano un'offerta o moltiplicatori. Il sottoaccount specifica anche il budget distribuito durante il giorno e l'offerta massima che si desidera non superare tutte le offerte.
Per informazioni dettagliate sull'intervallo di offerte e sul budget validi per il mercato, vedere la tabella Currency Value nell'argomento Currencies .
Per sospendere tutti gli hotel nell'account secondario, impostare la proprietà del Bid subaccount su un oggetto PercentageBid e l'importo percentuale dell'offerta su zero (0,0).
Se il sottoaccount specifica i moltiplicatori di offerta e si desidera rimuoverli, impostare su BidMultipliers una matrice vuota, ad esempio "BidMultipliers":[]).
Per aggiornare un account secondario, inviare una richiesta PATCH. Il corpo della richiesta è un oggetto SubAccount . Includere solo le proprietà che si desidera aggiornare. Questo esempio mostra l'aggiornamento dei moltiplicatori.
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"
}
]
}
Recupero di un account secondario
Per ottenere un account secondario specifico, inviare la richiesta seguente. L'ID dell'account secondario deve essere racchiuso tra virgolette singole, come illustrato.
GET https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>') HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Accept: application/json
Host: <host>
La risposta contiene un oggetto 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
}
Uso di gruppi di hotel
I gruppi di hotel sono il secondo livello di organizzazione usato per raggruppare gli hotel. Quando si crea un account secondario, il servizio crea un gruppo di hotel predefinito nell'account secondario denominato Ungrouped. L'API consente di elencare, ottenere, aggiornare e aggiungere gruppi di hotel.
Di seguito sono riportati i modelli REST usati per gestire i gruppi di hotel.
/SubAccounts('{subAccountId}')/HotelGroups— GET | POST/SubAccounts('{subAccountId}')/HotelGroups('{hotelGroupId}')— GET | PATCH | DELETE
Per un esempio che ottiene, aggiunge e aggiorna i gruppi di hotel, vedere esempi di codice. Usare il selettore Lingua nel riquadro di destra per visualizzare l'esempio in lingue diverse.
Elenco di gruppi di hotel
Per impostazione predefinita, quando si richiede un elenco di gruppi di hotel in un account secondario, l'API restituisce un massimo di 1.000 gruppi. Per determinare il numero totale di gruppi nell'account secondario, usare il parametro di query $count . Per specificare il numero di gruppi da restituire, usare il parametro di query $top . Il numero massimo di gruppi che è possibile richiedere in una singola chiamata è 5.000. Se l'account secondario contiene più di 5.000 gruppi, usare i parametri di query $top e $skip per scorrere tutti i gruppi.
Per ottenere un elenco dei primi 1.000 gruppi di hotel in un account secondario, inviare la richiesta seguente.
GET https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>')/HotelGroups HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Accept: application/json
Host: <host>
La risposta contiene un oggetto CollectionResponse . La value matrice contiene un elenco di oggetti HotelGroup . Questo esempio mostra il gruppo ungrouped predefinito.
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":[]
}
]
}
Aggiunta di un gruppo di hotel
Creare un nuovo gruppo di hotel se si vuole creare un nuovo raggruppamento logico di hotel. Per specificare il gruppo di hotel, utilizzare l'oggetto HotelGroup . L'unico campo obbligatorio è Name. Usare un nome descrittivo che indica il raggruppamento. I Bid campi e BidMultipliers sono facoltativi. Se non vengono specificati, il gruppo usa i moltiplicatori di offerta e offerta del sottoaccount. Specificarli se si desidera eseguire l'override dei valori dell'account secondario. È possibile specificare l'offerta, i moltiplicatori o entrambi.
Per informazioni dettagliate sull'intervallo di offerte valido per il mercato, vedere la tabella Valore valuta nell'argomento Valute .
Nell'esempio seguente viene creato un gruppo di hotel che eredita i moltiplicatori di offerta e offerta dal sottoaccount.
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 risposta è un oggetto AddResponse che contiene l'ID del gruppo di hotel aggiunto.
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"
}
Dopo aver aggiunto un gruppo di hotel, usare il modello associato per aggiungere hotel al gruppo. Per informazioni, vedere Associazione di un hotel a un gruppo di hotel.
Aggiornamento di un gruppo di hotel
Il gruppo di hotel specifica i moltiplicatori di offerta e offerta predefiniti da utilizzare per gli hotel del gruppo. Il gruppo li specifica in modo esplicito o li eredita dall'account secondario a cui appartiene. È possibile usare l'API per aggiornare i moltiplicatori di offerte e offerte da usare per gli hotel che non specificano un'offerta o moltiplicatori.
Per informazioni dettagliate sull'intervallo di offerte e sul budget validi per il mercato, vedere la tabella Currency Value nell'argomento Currencies .
Se il conto secondario specifica un'offerta massima, l'offerta del gruppo alberghiero deve essere inferiore all'offerta massima del conto secondario.
Per sospendere tutti gli hotel del gruppo di hotel, impostare la proprietà del Bid gruppo su un oggetto PercentageBid e l'importo percentuale dell'offerta su zero (0,0).
Se il gruppo specifica un'offerta maggiore di zero ma gli hotel del gruppo non servono, può essere perché l'offerta del conto secondario è zero.
Per rimuovere l'offerta del gruppo di hotel, impostare su Bid Null (ad esempio, "Bid":null).
Se il gruppo di hotel specifica i moltiplicatori di offerta e si desidera rimuoverli, impostare su BidMultipliers una matrice vuota, ad esempio "BidMultipliers":[]).
Per aggiornare un gruppo di hotel, inviare una richiesta PATCH. Il corpo della richiesta è un oggetto HotelGroup . Includere solo le proprietà che si desidera aggiornare. Questo esempio mostra l'aggiornamento dell'offerta e dei moltiplicatori.
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"
}
]
}
Ottenere un gruppo di hotel
Per ottenere un gruppo di hotel specifico, inviare la richiesta seguente. L'ID gruppo di hotel deve essere racchiuso tra virgolette singole, come illustrato.
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 risposta contiene un oggetto 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
}
Uso degli hotel
Gli hotel rappresentano gli hotel nel feed dell'hotel. L'API consente di elencare, ottenere e aggiornare gli hotel. Non è possibile usare l'API per aggiungere hotel; per aggiungere hotel, usare il feed Hotel. Gli hotel sono univoci per ogni account secondario: più di un account secondario potrebbe non contenere lo stesso hotel.
Di seguito sono riportati i modelli REST usati per gestire gli hotel.
/SubAccounts('{subAccountId}')/Hotels— GET/SubAccounts('{subAccountId}')/HotelGroups('{hotelGroupId}')/Hotels— GET/SubAccounts('{subAccountId}')/HotelGroups('{hotelGroupId}')/Hotels('{hotelId}')— GET | PATCH
Per un esempio che ottiene e aggiorna gli hotel, vedere esempi di hotel. Usare il selettore Lingua nel riquadro di destra per visualizzare l'esempio in lingue diverse.
Elenco di hotel
Per impostazione predefinita, quando si richiede un elenco di hotel in un gruppo di hotel, l'API restituisce un massimo di 1.000 hotel. Per determinare il numero totale di hotel nel gruppo di hotel, usare il parametro di query $count . Per specificare il numero di hotel da restituire, usare il parametro di query $top . Il numero massimo di hotel che è possibile richiedere in una singola chiamata è 5.000. Se il gruppo di hotel contiene più di 5.000 hotel, usare i parametri di query $top e $skip per scorrere gli hotel.
Nota
È consigliabile usare i parametri di query $top e $skip per scorrere solo gli hotel in un'esperienza dell'interfaccia utente. Per ottenere tutti gli hotel, usare la funzionalità Report per scaricare gli hotel.
- /SubAccounts('{subAccountId}')/Hotels
- /SubAccounts('{subaccountid}')/HotelGroups('{hotelgroupid}')/Hotels
- /SubAccounts('{subAccountId}')/Ungrouped
Per ottenere i primi 1.000 hotel in un gruppo di hotel, inviare la richiesta seguente.
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 risposta contiene un oggetto CollectionResponse . La value matrice contiene un elenco di oggetti 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":[]
}
]
}
Aggiornamento di un hotel
L'hotel specifica i moltiplicatori di offerte e offerte da utilizzare per gli annunci di prezzo dell'hotel. L'hotel li specifica in modo esplicito o li eredita dal gruppo o dall'account secondario dell'hotel, in tale ordine. Puoi usare l'API per aggiornare i moltiplicatori di offerte e offerte da usare per l'annuncio dell'hotel.
Per informazioni dettagliate sull'intervallo di offerte valido per il mercato, vedere la tabella Valore valuta nell'argomento Valute .
Se il conto secondario specifica un'offerta massima, l'offerta dell'hotel deve essere inferiore all'offerta massima del conto secondario.
Per sospendere un hotel, impostare la proprietà Bid su un oggetto PercentageBid e l'importo dell'offerta percentuale su zero (0,0).
Se l'hotel specifica un'offerta maggiore di zero ma non serve, può essere perché l'offerta del gruppo di hotel o del conto secondario a cui appartiene è zero.
Per rimuovere l'offerta di un hotel, impostarne il Bid valore su null (ad esempio, "Bid":null).
Se l'hotel specifica i moltiplicatori di offerta e si desidera rimuoverli, impostare su BidMultipliers una matrice vuota, ad esempio "BidMultipliers":[]).
Per aggiornare un hotel, inviare una richiesta PATCH . La richiesta può specificare l'ID assegnato da Microsoft all'hotel o l'ID assegnato dall'inserzionista all'hotel. Se si specifica l'ID assegnato dall'inserzionista, la richiesta deve impostare il parametro di query PartnerHotelIdsu true.
Il corpo della richiesta è un oggetto Hotel . Includere solo le proprietà che si desidera aggiornare. Questo esempio mostra l'aggiornamento dei moltiplicatori.
{
"BidMultipliers":[
{
"Countries":["US"],
"Factor":1.1,
"@odata.type":"#Model.UserCountryMultiplier"
},
{
"DeviceTypes":["Desktop"],
"Factor":2.65,
"@odata.type":"#Model.DeviceMultiplier"
}
]
}
Ottenere un hotel
Per ottenere un hotel specifico, inviare la richiesta seguente. L'ID hotel deve essere racchiuso tra virgolette singole, come illustrato.
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 risposta contiene un oggetto 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"]
}
]
}
Durata del soggiorno e moltiplicatori avanzati della finestra di prenotazione
La descrizione per LengthOfStayMultiplier indica che Bing applica il moltiplicatore se l'utente rimane il numero specificato di notti o più. E la descrizione per AdvanceBookingWindowMultiplier indica anche che Bing applica il moltiplicatore se la prenotazione avviene in anticipo rispetto al numero specificato di giorni o più. La parte chiave della descrizione è la frase o più lunga.
Se si specificano più moltiplicatori, la combinazione di fattore e giorni/notti deve essere univoca; in caso contrario, la chiamata ha esito negativo con un errore DuplicateValues. Nell'esempio LengthOfStayMultiplier seguente il fattore per ogni voce è 1. Poiché l'ingresso per 6 notti si applica a soggiorni di 6 o più notti, il secondo ingresso per 8 notti è un duplicato. Per correggere questo errore, è sufficiente rimuovere la voce per 8 notti o fornire un valore di fattore diverso.
{
"MinimumNumberOfNights": 8,
"Factor": "1",
"@odata.type": "#Model.LengthOfStayMultiplier"
},
{
"MinimumNumberOfNights": 6,
"Factor": "1",
"@odata.type": "#Model.LengthOfStayMultiplier"
}
Associazione di un hotel a un gruppo di hotel
Quando si importa il file del feed dell'hotel, gli hotel vengono inseriti nel gruppo di hotel non raggruppati , che è il gruppo di hotel predefinito. Un hotel può essere associato a un solo gruppo di hotel. Se crei un nuovo gruppo di hotel per organizzare logicamente i tuoi hotel, dovrai spostare gli hotel dal gruppo di hotel non raggruppati al nuovo gruppo creato. Per associare un hotel a un nuovo gruppo di hotel, usare il modello Associa . Quando si associa un hotel a un nuovo gruppo di hotel, il servizio rimuove l'associazione precedente.
Nell'esempio POST seguente viene illustrato come specificare l'associazione. Il corpo della richiesta è un oggetto AssociationCollection . La raccolta può contenere un massimo di 500 oggetti 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"
}
]
}
Il metodo Associate deve sempre restituire l'esito positivo. Se una o più associazioni hanno esito negativo, la risposta contiene l'associazione di input delle associazioni non riuscite e il motivo dell'errore.
La risposta contiene un oggetto CollectionResponse . Se tutte le associazioni hanno avuto esito positivo, la value matrice è vuota. In caso contrario, value contiene un oggetto HotelAssociation per ogni associazione non riuscita. Il campo dell'associazione Errors contiene i motivi dell'errore.
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>"
}
]
}
]
}
Ottenere associazioni di hotel
Per impostazione predefinita, quando si richiede un elenco di associazioni in un account secondario, l'API restituisce un massimo di 1.000 associazioni. Per determinare il numero totale di associazioni, usare il parametro di query $count . Per specificare il numero di associazioni da restituire, usare il parametro di query $top . Il numero massimo di associazioni che è possibile richiedere in una singola chiamata è 5.000. Se l'account secondario contiene più di 5.000 associazioni, usare i parametri di query $top e $skip per scorrere tutte le associazioni.
Per ottenere le prime 1.000 associazioni di hotel e gruppi di hotel per un account secondario, inviare la richiesta seguente:
GET https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>')/Associations HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Accept: application/json
Host: <host>
La risposta contiene un oggetto CollectionResponse . La value matrice contiene un elenco di oggetti 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"
},
. . .
]
}
Filtro delle associazioni di hotel
Per restituire un subset di associazioni, usare il parametro di query OData $filter. È possibile filtrare le associazioni in base HotelId o PartnerHotelId solo. La lunghezza massima dell'URL (2.048) determina il numero di ID che è possibile specificare. Se l'URL supera i 2.048 caratteri, la richiesta restituisce 404.
Di seguito viene illustrato un esempio che restituisce le associazioni di hotel specificate.
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>
Elaborazione batch
Per inviare più richieste in una singola richiesta HTTP, usare il modello /$batch . È possibile inviare un massimo di 500 richieste in una singola richiesta batch.
Nota
L'elaborazione batch è supportata solo per gli aggiornamenti degli hotel, ad esempio le modifiche delle offerte.
La richiesta
Di seguito viene illustrata una richiesta di esempio.
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
L'intestazione Content-Type deve essere impostata su multipart/mixed e includere l'ID limite. L'ID limite è opaco e delimita ogni richiesta secondaria nella richiesta batch. L'ID può essere qualsiasi stringa univoca. Questo esempio usa, batch_< stringaunique>, dove <la stringa> univoca è un GUID.
Il corpo della richiesta batch contiene più singole richieste delimitate dall'ID limite. Di seguito viene illustrato un esempio del corpo di una richiesta batch. Assicurarsi di terminare ogni riga nel corpo della richiesta batch con CRLF (ritorno a capo e avanzamento riga).
--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--
Si noti che ogni ID limite viene anteposto con un doppio trattino (ad esempio, --batch_086fe0de-9b26-4d4a-a206-6df2013a2816). E l'ID limite di terminazione che segue l'ultima richiesta nel batch è racchiuso tra trattino doppio (ad esempio, --batch_086fe0de-9b26-4d4a-a206-6df2013a2816--).
Il delimitatore dell'ID limite deve essere seguito dalle intestazioni Content-Type e Content-Transfer-Encoding, come illustrato. Poiché è possibile aggiornare solo gli hotel, la richiesta deve usare il verbo HTTP PATCH e usare il modello di hotel per identificare l'hotel da aggiornare. La richiesta deve includere l'intestazione Content-Type e deve essere impostata su application/json; odata.metadata=minimal. Il corpo della richiesta è un oggetto Hotel . L'oggetto deve includere l'ID dell'hotel e includere solo i campi che si sta aggiornando.
Risposta
La risposta è analogamente delimitata e ogni elemento nella risposta corrisponde direttamente a ogni elemento della richiesta. L'intestazione Content-Type della risposta contiene l'ID limite. Ottenere l'ID e usarlo per analizzare ogni elemento di risposta.
Di seguito viene illustrata la risposta alla richiesta precedente.
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--
Ogni elemento di risposta contiene uno stato HTTP. Per gli aggiornamenti, se l'aggiornamento ha esito positivo, lo stato è 204. Se l'aggiornamento non riesce(ad esempio, l'hotel non è stato trovato, un valore non è valido o l'oggetto hotel non è valido), lo stato è 400 e il corpo contiene un elenco di errori. Una richiesta potrebbe non riuscire con altri codici di stato.
Di seguito viene illustrato un elemento di risposta che contiene un errore. Se si verifica un errore, il corpo contiene un oggetto CollectionResponse e ogni elemento nella value matrice è un oggetto 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--
Codice di esempio per l'elaborazione delle richieste batch
Per un esempio di codice che aggiorna i prezzi degli hotel in una richiesta batch, vedere Esempio di elaborazione batch.