Verwalten von Hotelanzeigekampagnen
Hinweis
Diese Betaversion von HotelPreisanzeigen ist nur für ausgewählte Teilnehmer verfügbar. Informationen zur Teilnahme am Beta-Release-Programm finden Sie bei Ihrem Account Manager, oder registrieren Sie sich hier.
Api und Dokumentation können geändert werden.
Mit der Hotel-API können Sie Ihre Hotelanzeigenkampagnen und -angebote verwalten. Ein Unterkonto stellt die logische organization Ihrer Hotelpreisanzeigen auf oberster Ebene bereit. Sie können es sich als Eine Unterkunftskampagne (früher Hotelkampagnen) vorstellen. Möglicherweise verfügen Sie über maximal 75 aktive Unterkonten.
Ein Unterkonto gibt das Tagesbudget der Kampagne, das maximal zulässige Gebot sowie Standardgebots- und Gebotsmultiplikatoren für Anzeigen an, die keine Gebote oder Multiplikatoren angeben.
Hinweis
Hotelanzeigenkampagnen, auf die hier verwiesen wird, haben keine Beziehung zu Kampagnen in Microsoft Advertising.
Wenn Sie dies noch nicht getan haben, machen Sie sich mit den folgenden Themen vertraut:
Informationen zu Hotel-API-Endpunkten finden Sie unter Endpunkte.
Informationen zur Berichterstellung finden Sie unter Berichterstellungs-API für Hotelpreisanzeigen.
Arbeiten mit Unterkonten
Unterkonten sind die organization von Hotelpreisanzeigen auf oberster Ebene. Der Dienst erstellt das Standardunterkonto für Sie, wenn Sie sich für Hotelpreisanzeigen registrieren. Mit der API können Sie Unterkonten hinzufügen, Unterkonten auflisten, ein bestimmtes Unterkonto abrufen und ein Unterkonto aktualisieren.
Im Folgenden sind die REST-Vorlagen aufgeführt, die Sie zum Verwalten von Unterkonten verwenden.
Ein Beispiel zum Abrufen und Aktualisieren von Unterkonten finden Sie unter Codebeispiele. (Verwenden Sie die Sprachauswahl im rechten Bereich, um das Beispiel in verschiedenen Sprachen anzuzeigen.)
Auflisten von Unterkonten
Um die Liste der Unterkonten abzurufen, senden Sie die folgende Anforderung.
GET https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Accept: application/json
Host: <host>
Die Antwort enthält ein CollectionResponse-Objekt . Das value Array enthält eine Liste von SubAccount-Objekten .
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
}
}
]
}
Aktualisieren eines Unterkontos
Das Unterkonto gibt die Standardgebots- und Gebotsmultiplikatoren an, die für Hotelgruppen und Hotels verwendet werden sollen, die kein Gebot oder Multiplikatoren angeben. Das Unterkonto gibt auch das Budget an, das über den Tag verteilt ist, und das maximale Gebot, das alle Gebote nicht überschreiten sollen.
Ausführliche Informationen zum gültigen Gebotsbereich und budget für Ihren Markt finden Sie in der Tabelle Währungswert im Thema Währungen .
Um alle Hotels im Unterkonto anzuhalten, legen Sie die -Eigenschaft des Unterkontos auf ein PercentageBid-Objekt und den Prozentsatz des Gebots Bid auf Null (0,0) fest.
Wenn das Unterkonto Gebotsmultiplikatoren angibt und Sie sie entfernen möchten, legen Sie auf ein leeres Array fest BidMultipliers (z. B. "BidMultipliers":[]).
Um ein Unterkonto zu aktualisieren, senden Sie eine PATCH-Anforderung. Der Text der Anforderung ist ein SubAccount-Objekt . Schließen Sie nur die Eigenschaften ein, die Sie aktualisieren möchten. Dieses Beispiel zeigt das Aktualisieren von Multiplikatoren.
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"
}
]
}
Abrufen eines Unterkontos
Um ein bestimmtes Unterkonto abzurufen, senden Sie die folgende Anforderung. Die Unterkonto-ID muss wie gezeigt in einfache Anführungszeichen eingeschlossen werden.
GET https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>') HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Accept: application/json
Host: <host>
Die Antwort enthält ein SubAccount-Objekt .
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
}
Arbeiten mit Hotelgruppen
Hotelgruppen sind die zweite Ebene von organization, die Sie zum Gruppieren von Hotels verwenden. Wenn Sie ein Unterkonto erstellen, erstellt der Dienst unter dem Unterkonto Ungrouped eine Standardhotelgruppe. Mit der API können Sie Hotelgruppen auflisten, abrufen, aktualisieren und hinzufügen.
Im Folgenden sind die REST-Vorlagen aufgeführt, die Sie zum Verwalten von Hotelgruppen verwenden.
/SubAccounts('{subAccountId}')/HotelGroups— GET | POST/SubAccounts('{subAccountId}')/HotelGroups('{hotelGroupId}')— GET | PATCH | DELETE
Ein Beispiel zum Abrufen, Hinzufügen und Aktualisieren von Hotelgruppen finden Sie unter Codebeispiele. (Verwenden Sie die Sprachauswahl im rechten Bereich, um das Beispiel in verschiedenen Sprachen anzuzeigen.)
Auflisten von Hotelgruppen
Wenn Sie eine Liste von Hotelgruppen unter einem Unterkonto anfordern, gibt die API standardmäßig maximal 1.000 Gruppen zurück. Verwenden Sie den Abfrageparameter $count , um die Gesamtzahl der Gruppen im Unterkonto zu ermitteln. Verwenden Sie den Abfrageparameter $top , um die Anzahl der zurückzugebenden Gruppen anzugeben. Die maximale Anzahl von Gruppen, die Sie in einem einzelnen Anruf anfordern können, beträgt 5.000. Wenn das Unterkonto mehr als 5.000 Gruppen enthält, verwenden Sie die $top und $skip Abfrageparameter, um alle Gruppen zu durchlaufen.
Um eine Liste der ersten 1.000 Hotelgruppen unter einem Unterkonto abzurufen, senden Sie die folgende Anforderung.
GET https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>')/HotelGroups HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Accept: application/json
Host: <host>
Die Antwort enthält ein CollectionResponse-Objekt . Das value Array enthält eine Liste von HotelGroup-Objekten . Dieses Beispiel zeigt die Standardgruppe Nicht gruppiert.
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":[]
}
]
}
Hinzufügen einer Hotelgruppe
Sie würden eine neue Hotelgruppe erstellen, wenn Sie eine neue logische Gruppierung von Hotels erstellen möchten. Verwenden Sie das HotelGroup-Objekt , um die Hotelgruppe anzugeben. Das einzige erforderliche Feld ist Name. Verwenden Sie einen beschreibenden Namen, der die Gruppierung angibt. Die Felder Bid und BidMultipliers sind optional. Wenn Sie sie nicht angeben, verwendet die Gruppe die Gebots- und Gebotsmultiplikatoren aus dem Unterkonto. Geben Sie sie an, wenn Sie die Werte des Unterkontos überschreiben möchten. Sie können das Gebot, die Multiplikatoren oder beides angeben.
Ausführliche Informationen zum gültigen Gebotsbereich für Ihren Markt finden Sie in der Tabelle Währungswert im Thema Währungen .
Im folgenden Beispiel wird eine Hotelgruppe erstellt, die die Gebots- und Gebotsmultiplikatoren vom Unterkonto erbt.
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"}
Die Antwort ist ein AddResponse-Objekt , das die ID der hinzugefügten Hotelgruppe enthält.
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"
}
Nachdem Sie eine Hotelgruppe hinzugefügt haben, verwenden Sie die Zuordnen-Vorlage , um der Gruppe Hotels hinzuzufügen. Weitere Informationen finden Sie unter Zuordnen eines Hotels zu einer Hotelgruppe.
Aktualisieren einer Hotelgruppe
Die Hotelgruppe gibt die Standardgebots- und Gebotsmultiplikatoren an, die für Hotels in der Gruppe verwendet werden sollen. Die Gruppe gibt sie entweder explizit an oder erbt sie von dem Unterkonto, zu dem sie gehört. Sie können die API verwenden, um die Gebots- und Gebotsmultiplikatoren für Hotels zu aktualisieren, die kein Gebot oder Multiplikatoren angeben.
Ausführliche Informationen zum gültigen Gebotsbereich und budget für Ihren Markt finden Sie in der Tabelle Währungswert im Thema Währungen .
Wenn das Unterkonto ein maximales Gebot angibt, muss das Gebot der Hotelgruppe kleiner als das maximale Gebot des Unterkontos sein.
Um alle Hotels in der Hotelgruppe anzuhalten, legen Sie die Eigenschaft der Gruppe auf ein PercentageBid-Objekt und den Prozentsatz des Gebots Bid auf Null (0,0) fest.
Wenn die Gruppe ein Gebot größer als 0 (null) angibt, die Hotels der Gruppe jedoch nicht bedienen, liegt dies möglicherweise daran, dass das Gebot des Unterkontos 0 (null) ist.
Um das Gebot der Hotelgruppe zu entfernen, legen Sie auf NULL fest Bid (z. B. "Bid":null).
Wenn die Hotelgruppe Gebotsmultiplikatoren angibt und Sie sie entfernen möchten, legen Sie auf ein leeres Array fest BidMultipliers (z. B. "BidMultipliers":[]).
Um eine Hotelgruppe zu aktualisieren, senden Sie eine PATCH-Anforderung. Der Text der Anforderung ist ein HotelGroup-Objekt . Schließen Sie nur die Eigenschaften ein, die Sie aktualisieren möchten. Dieses Beispiel zeigt die Aktualisierung des Gebots und der Multiplikatoren.
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"
}
]
}
Erhalten einer Hotelgruppe
Um eine bestimmte Hotelgruppe zu erhalten, senden Sie die folgende Anforderung. Die Hotelgruppen-ID muss wie gezeigt in einfache Anführungszeichen eingeschlossen werden.
GET https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>')/HotelGroups('<hotelgroupid>') HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Accept: application/json
Host: <host>
Die Antwort enthält ein HotelGroup-Objekt .
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
}
Arbeiten mit Hotels
Hotels stellen die Hotels in Ihrem Hotelfeed dar. Mit der API können Sie Hotels auflisten, abrufen und aktualisieren. Sie können die API nicht zum Hinzufügen von Hotels verwenden. Um Hotels hinzuzufügen, verwenden Sie den Hotelfeed. Hotels sind pro Unterkonto eindeutig – mehr als ein Unterkonto darf nicht dasselbe Hotel enthalten.
Im Folgenden sind die REST-Vorlagen aufgeführt, die Sie zum Verwalten von Hotels verwenden.
/SubAccounts('{subAccountId}')/Hotels— GET/SubAccounts('{subAccountId}')/HotelGroups('{hotelGroupId}')/Hotels— GET/SubAccounts('{subAccountId}')/HotelGroups('{hotelGroupId}')/Hotels('{hotelId}')— GET | PATCH
Ein Beispiel zum Abrufen und Aktualisieren von Hotels finden Sie unter Hotelbeispiele. (Verwenden Sie die Sprachauswahl im rechten Bereich, um das Beispiel in verschiedenen Sprachen anzuzeigen.)
Hotels auflisten
Wenn Sie eine Liste von Hotels in einer Hotelgruppe anfordern, gibt die API standardmäßig maximal 1.000 Hotels zurück. Verwenden Sie den Abfrageparameter $count , um die Gesamtzahl der Hotels in der Hotelgruppe zu ermitteln. Verwenden Sie den Abfrageparameter $top , um die Anzahl der zurückzugebenden Hotels anzugeben. Die maximale Anzahl von Hotels, die Sie in einem einzelnen Anruf anfordern können, beträgt 5.000. Wenn Ihre Hotelgruppe mehr als 5.000 Hotels enthält, verwenden Sie die $top und $skip Abfrageparameter, um die Hotels zu durchlaufen.
Hinweis
Sie sollten die Abfrageparameter $top und $skip verwenden, um Hotels nur in einer Benutzeroberfläche zu durchlaufen. Um alle Ihre Hotels zu erhalten, verwenden Sie die Berichterstellungsfunktion , um die Hotels herunterzuladen.
- /SubAccounts('{subAccountId}')/Hotels
- /SubAccounts('{subaccountid}')/HotelGroups('{hotelgroupid}')/Hotels
- /SubAccounts('{subAccountId}')/Ungrouped
Um die ersten 1.000 Hotels in einer Hotelgruppe zu erhalten, senden Sie die folgende Anfrage.
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>
Die Antwort enthält ein CollectionResponse-Objekt . Das value Array enthält eine Liste von Hotel-Objekten .
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":[]
}
]
}
Aktualisieren eines Hotels
Das Hotel gibt die Gebots- und Gebotsmultiplikatoren an, die für Hotelpreisanzeigen verwendet werden sollen. Das Hotel gibt sie entweder explizit an oder erbt sie von der Hotelgruppe oder dem Unterkonto in dieser Reihenfolge. Sie können die API verwenden, um die Gebots- und Gebotsmultiplikatoren für die Anzeige des Hotels zu aktualisieren.
Ausführliche Informationen zum gültigen Gebotsbereich für Ihren Markt finden Sie in der Tabelle Währungswert im Thema Währungen .
Wenn das Unterkonto ein Maximales Gebot angibt, muss das Gebot des Hotels kleiner als das maximale Gebot des Unterkontos sein.
Um ein Hotel anzuhalten, legen Sie seine Bid Eigenschaft auf ein PercentageBid-Objekt und den Prozentsatz des Gebots auf Null (0,0) fest.
Wenn das Hotel ein Gebot angibt, das größer als 0 (null) ist, aber nicht bedient wird, liegt dies möglicherweise daran, dass das Gebot der Hotelgruppe oder des Unterkontos, zu dem es gehört, null ist.
Um das Gebot eines Hotels zu entfernen, legen Sie es Bid auf NULL fest (z. B. "Bid":null).
Wenn das Hotel Gebotsmultiplikatoren angibt und Sie sie entfernen möchten, legen Sie auf ein leeres Array fest BidMultipliers (z. B. "BidMultipliers":[]).
Um ein Hotel zu aktualisieren, senden Sie eine PATCH-Anforderung . Die Anforderung kann die ID angeben, die Microsoft dem Hotel zugewiesen hat, oder die ID, die der Werbetreibende dem Hotel zugewiesen hat. Wenn Sie die vom Werbetreibenden zugewiesene ID angeben, muss die Anforderung den PartnerHotelId-Abfrageparameter auf true festlegen.
Der Text der Anforderung ist ein Hotel-Objekt . Schließen Sie nur die Eigenschaften ein, die Sie aktualisieren möchten. Dieses Beispiel zeigt das Aktualisieren der Multiplikatoren.
{
"BidMultipliers":[
{
"Countries":["US"],
"Factor":1.1,
"@odata.type":"#Model.UserCountryMultiplier"
},
{
"DeviceTypes":["Desktop"],
"Factor":2.65,
"@odata.type":"#Model.DeviceMultiplier"
}
]
}
Hotel bekommen
Um ein bestimmtes Hotel zu erhalten, senden Sie die folgende Anfrage. Die Hotel-ID muss wie gezeigt in einfache Anführungszeichen eingeschlossen werden.
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>
Die Antwort enthält ein Hotel-Objekt .
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"]
}
]
}
Verweildauer und Multiplikatoren für erweitertes Buchungsfenster
Die Beschreibung für LengthOfStayMultiplier besagt, dass Bing den Multiplikator anwendet, wenn der Benutzer die angegebene Anzahl von Nächten oder länger bleibt. Und die Beschreibung für AdvanceBookingWindowMultiplier besagt auch, dass Bing den Multiplikator anwendet, wenn die Buchung im Voraus die angegebene Anzahl von Tagen oder länger erfolgt. Der wichtigste Teil der Beschreibung ist der Ausdruck oder länger.
Wenn Sie mehr als einen dieser Multiplikatoren angeben, muss die Kombination aus Faktor und Tagen/Nächten eindeutig sein; Andernfalls schlägt der Aufruf mit einem DuplicateValues-Fehler fehl. Im folgenden LengthOfStayMultiplier-Beispiel ist der Faktor für jeden Eintrag 1. Da der Eintrag für 6 Nächte für Aufenthalte von 6 Nächten oder länger gilt, ist der zweite Eintrag für 8 Nächte ein Duplikat. Um diesen Fehler zu beheben, entfernen Sie einfach den Eintrag für 8 Nächte, oder geben Sie einen anderen Faktorwert an.
{
"MinimumNumberOfNights": 8,
"Factor": "1",
"@odata.type": "#Model.LengthOfStayMultiplier"
},
{
"MinimumNumberOfNights": 6,
"Factor": "1",
"@odata.type": "#Model.LengthOfStayMultiplier"
}
Zuordnen eines Hotels zu einer Hotelgruppe
Wenn Sie Ihre Hotelfeeddatei importieren, werden die Hotels in der Gruppe Nicht gruppierte Hotels platziert, bei der es sich um die Standardhotelgruppe handelt. Ein Hotel kann nur einer Hotelgruppe zugeordnet werden. Wenn Sie eine neue Hotelgruppe erstellen, um Ihre Hotels logisch zu organisieren, sollten Sie Hotels aus der Gruppe Nicht gruppierte Hotels in die neue Gruppe verschieben, die Sie erstellt haben. Um ein Hotel einer neuen Hotelgruppe zuzuordnen, verwenden Sie die Vorlage Zuordnen . Wenn Sie ein Hotel einer neuen Hotelgruppe zuordnen, entfernt der Dienst die vorherige Zuordnung.
Im folgenden POST-Beispiel wird gezeigt, wie die Zuordnung angegeben wird. Der Text der Anforderung ist ein AssociationCollection-Objekt . Die Auflistung darf maximal 500 HotelAssociation-Objekte enthalten.
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"
}
]
}
Die Associate-Methode sollte immer einen Erfolg zurückgeben. Wenn eine oder mehrere Zuordnungen fehlschlagen, enthält die Antwort die Eingabezuordnung der fehlerhaften Zuordnungen und den Grund für den Fehler.
Die Antwort enthält ein CollectionResponse-Objekt . Wenn alle Zuordnungen erfolgreich waren, ist das value Array leer. value Andernfalls enthält ein HotelAssociation-Objekt für jede Zuordnung, bei der ein Fehler aufgetreten ist. Das Feld der Errors Zuordnung enthält die Gründe für den Fehler.
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>"
}
]
}
]
}
Abrufen von Hotelzuordnungen
Wenn Sie eine Liste von Zuordnungen in einem Unterkonto anfordern, gibt die API standardmäßig maximal 1.000 Zuordnungen zurück. Verwenden Sie den Abfrageparameter $count , um die Gesamtzahl der Zuordnungen zu bestimmen. Verwenden Sie den Abfrageparameter $top , um die Anzahl der zurückzugebenden Zuordnungen anzugeben. Die maximale Anzahl von Zuordnungen, die Sie in einem einzelnen Anruf anfordern können, beträgt 5.000. Wenn Ihr Unterkonto mehr als 5.000 Zuordnungen enthält, verwenden Sie die $top und $skip Abfrageparameter, um alle Zuordnungen zu durchlaufen.
Um die ersten 1.000 Hotel- und Hotelgruppenzuordnungen für ein Unterkonto abzurufen, senden Sie die folgende Anforderung:
GET https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>')/Associations HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Accept: application/json
Host: <host>
Die Antwort enthält ein CollectionResponse-Objekt . Das value Array enthält eine Liste von HotelAsssociation-Objekten .
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"
},
. . .
]
}
Filtern von Hotelzuordnungen
Um eine Teilmenge von Zuordnungen zurückzugeben, verwenden Sie den Abfrageparameter OData $filter. Sie können Zuordnungen nur nach HotelId oder PartnerHotelId filtern. Die maximale URL-Länge (2.048) bestimmt die Anzahl der IDs, die Sie angeben können. Wenn die URL 2.048 Zeichen überschreitet, gibt die Anforderung 404 zurück.
Im Folgenden sehen Sie ein Beispiel, das die angegebenen Hotelzuordnungen zurückgibt.
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>
Batch-Verarbeitung
Verwenden Sie die Vorlage /$batch , um mehrere Anforderungen in einer einzelnen HTTP-Anforderung zu senden. Sie können maximal 500 Anforderungen in einer einzelnen Batchanforderung senden.
Hinweis
Die Batchverarbeitung wird nur für Hotelupdates wie Gebotsänderungen unterstützt.
Die Anforderung
Im Folgenden sehen Sie eine Beispielanforderung.
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
Der Content-Type-Header muss auf mehrteilig/gemischt festgelegt werden und die Begrenzungs-ID enthalten. Die Begrenzungs-ID ist nicht transparent und begrenzt jede Unteranforderung in der Batchanforderung. Die ID kann eine beliebige eindeutige Zeichenfolge sein. In diesem Beispiel wird batch_<unsique string> verwendet, wobei <eindeutige Zeichenfolge> eine GUID ist.
Der Text der Batchanforderung enthält mehrere einzelne Anforderungen, die durch die Begrenzungs-ID getrennt sind. Im Folgenden sehen Sie ein Beispiel für den Text einer Batchanforderung. Achten Sie darauf, jede Zeile im Text der Batchanforderung mit CRLF (Wagenrücklauf und Zeilenvorschub) zu beenden.
--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--
Beachten Sie, dass jeder Begrenzungs-ID ein doppelter Bindestrich vorangestellt ist (z --. B. batch_086fe0de-9b26-4d4a-a206-6df2013a2816). Und die endende Begrenzungs-ID, die nach der letzten Anforderung im Batch geht, --wird in doppelte Bindestriche eingeschlossen (z. B. batch_086fe0de-9b26-4d4a-a206-6df2013a2816--).
Auf das Begrenzungs-ID-Trennzeichen müssen die Header Content-Type und Content-Transfer-Encoding folgen, wie gezeigt. Da Sie nur Hotels aktualisieren dürfen, muss die Anforderung das HTTP PATCH-Verb verwenden und die Hotelvorlage verwenden, um das zu aktualisierende Hotel zu identifizieren. Die Anforderung muss den Content-Type-Header enthalten, und sie muss auf application/json; odata.metadata=minimal festgelegt werden. Der Text der Anforderung ist ein Hotel-Objekt . Das Objekt muss die ID des Hotels enthalten und sollte nur die Felder enthalten, die Sie aktualisieren.
Die Antwort
Die Antwort ist ähnlich durch Trennzeichen getrennt, und jedes Element in der Antwort entspricht direkt jedem Element in der Anforderung. Der Content-Type-Header der Antwort enthält die Begrenzungs-ID. Rufen Sie die ID ab, und verwenden Sie sie zum Analysieren der einzelnen Antwortelemente.
Im Folgenden wird die Antwort auf die obige Anforderung gezeigt.
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--
Jedes Antwortelement enthält eine HTTP-status. Bei Updates lautet die status 204, wenn das Update erfolgreich ist. Wenn die Aktualisierung fehlschlägt (z. B. wenn das Hotel nicht gefunden wurde, ein Wert ungültig ist oder das Hotelobjekt falsch formatiert ist), ist die status 400, und der Text enthält eine Liste von Fehlern. (Eine Anforderung kann mit anderen status Codes fehlschlagen.)
Das folgende Beispiel zeigt ein Antwortelement, das einen Fehler enthält. Wenn ein Fehler auftritt, enthält der Textkörper ein CollectionResponse-Objekt , und jedes Element im value Array ist ein AdsApiError-Objekt .
--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--
Beispielcode für die Verarbeitung von Batchanforderungen
Beispielcode zum Aktualisieren der Hotelpreise in einer Batchanforderung finden Sie unter Beispiel für die Batchverarbeitung.