ホテル広告キャンペーンを管理する

[アーティクル]
10/04/2023

注:

このベータ版のHotel Price Adsは、一部の参加者のみが利用できます。ベータリリースプログラムへの参加の詳細については、アカウントマネージャーに問い合わせるか、こちらで登録してください。

API とドキュメントは変更される可能性があります。

Hotel API を使用すると、ホテル広告キャンペーンと入札を管理できます。サブアカウントは、ホテルの価格広告の最上位レベルの論理organizationを提供します。宿泊キャンペーン(旧ホテルキャンペーン)と考えることができます。アクティブなサブアカウントは最大 75 個までです。

サブアカウントは、キャンペーンの 1 日の予算、最大入札額、および入札数または乗数を指定しない広告の既定の入札と入札の乗数を指定します。

注:

ここで参照するホテル広告キャンペーンは、Microsoft Advertising のキャンペーンとは関係ありません。

まだ行っていない場合は、次のトピックを理解してください。

Hotel API エンドポイントについては、「エンドポイント」を参照してください。

レポートの詳細については、「ホテル価格広告レポート API」を参照してください。

サブアカウントの操作

サブアカウントは、ホテル価格広告の最上位レベルのorganizationです。 Hotel Price Ads にサインアップすると、サービスによって既定のサブアカウントが作成されます。この API を使用すると、サブアカウントの追加、サブアカウントの一覧表示、特定のサブアカウントの取得、サブアカウントの更新を行うことができます。

サブアカウントの管理に使用する REST テンプレートを次に示します。

/SubAccounts—POST を取得する |
/SubAccounts('{subAccountId}') — GET | PATCH

サブアカウントを取得および更新する例については、コード例を参照してください。 (右側のウィンドウの [言語] セレクターを使用して、異なる言語の例を表示します)。

サブアカウントの一覧表示

サブアカウントの一覧を取得するには、次の要求を送信します。

GET https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Accept: application/json
Host: <host>

応答には CollectionResponse オブジェクトが含まれています。配列には valueSubAccount オブジェクトの一覧が含まれています。

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
      }
    }
  ]
}

サブアカウントの更新

サブアカウントは、入札または乗数を指定しないホテルグループとホテルに使用する既定の入札と入札の乗数を指定します。サブアカウントでは、1 日を通して配分される予算と、すべての入札が超過しないようにする最大入札額も指定します。

市場の有効な入札範囲と予算の詳細については、「通貨」トピックの「通貨価値」の表を参照してください。

サブアカウント内のすべてのホテルを一時停止するには、サブアカウントの Bid プロパティを PercentageBid オブジェクトに設定し、入札率を 0 (0.0) に設定します。

サブアカウントで入札乗数を指定し、それらを削除する場合は、空の配列 ("BidMultipliers":[]など) に設定 BidMultipliers します。

サブアカウントを更新するには、PATCH 要求を送信します。要求の本文は SubAccount オブジェクトです。更新するプロパティのみを含めます。この例では、乗数の更新を示します。

PATCH https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>') HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Content-Type: application/json
Host: <host>
Content-Length: 682

{
  "Id":"1902000002",
  "BidMultipliers":[
    { 
	  "Countries":["US"],
	  "Factor":1.1,
	  "@odata.type":"#Model.UserCountryMultiplier"
	},
	{
	  "Sites":["LocalUniversal","MapResults"],
	  "Factor":0.85,
	  "@odata.type":"#Model.SiteMultiplier"
	},
	{
	  "DeviceTypes":["Desktop"],
	  "Factor":0.65,
	  "@odata.type":"#Model.DeviceMultiplier"
	},
	{
	  "MinimumNumberOfNights":5,
	  "Factor":1.3,
	  "@odata.type":"#Model.LengthOfStayMultiplier"
	},
	{
	  "DaysOfWeek":["Thursday","Friday","Saturday"],
	  "Factor":1.2,
	  "@odata.type":"#Model.CheckinDayOfWeekMultiplier"
	},
	{
	  "DaysOfWeek":["Sunday","Monday"],
	  "Factor":0.9,
	  "@odata.type":"#Model.CheckinDayOfWeekMultiplier"
	},
	{
	  "MinimumNumberOfDays":3,
	  "Factor":1.3,
	  "@odata.type":"#Model.AdvanceBookingWindowMultiplier"
	} 
  ]
}

サブアカウントの取得

特定のサブアカウントを取得するには、次の要求を送信します。示すように、サブアカウント ID は単一引用符で囲む必要があります。

GET https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>') HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Accept: application/json
Host: <host>

応答には SubAccount オブジェクトが含まれています。

HTTP/1.1 200 OK
x-ms-requestid: 58d37dd1-78ae-4ced-91e4-7f57e647ddee
x-ms-trackingid: 5345bf4f-e64a-47a6-8d1e-43cc0231dc1b

{
  "Id":"1902000002",
  "Name":"DefaultSubAccount1",
  "Status":"Active",
  "Bid":{
    "@odata.type":"#Model.FixedBid",
	"Amount":2.75
  },
  "BidMultipliers":[
    {
      "@odata.type":"#Model.DeviceMultiplier",
	  "Factor":0.65,
	  "DeviceTypes":["Desktop"]
    },
	{
      "@odata.type":"#Model.LengthOfStayMultiplier",
	  "Factor":1.3,
	  "MinimumNumberOfNights":5
    },
	{
      "@odata.type":"#Model.UserCountryMultiplier",
	  "Factor":1.1,
	  "Countries":["US"]
    },
	{
      "@odata.type":"#Model.AdvanceBookingWindowMultiplier",
	  "Factor":1.3,
	  "MinimumNumberOfDays":3
    },
	{
      "@odata.type":"#Model.CheckinDayOfWeekMultiplier",
	  "Factor":0.9,
	  "DaysOfWeek":["Monday","Sunday"]
    },
	{
      "@odata.type":"#Model.CheckinDayOfWeekMultiplier",
	  "Factor":1.2,
	  "DaysOfWeek":["Thursday","Friday","Saturday"]
    },
	{
      "@odata.type":"#Model.SiteMultiplier",
	  "Factor":0.85,
	  "Sites":["MapResults","LocalUniversal"]
    }
  ],
  "DailyBudget":{
    "Amount":125.25
  },
  "MaximumBid":{
    "Amount":10.0
  },
  "HotelAssociationCount":39540
}

ホテルグループの操作

ホテルグループは、ホテルをグループ化するために使用するorganizationの 2 番目のレベルです。サブアカウントを作成すると、既定のホテルグループが、グループ化解除という名前のサブアカウントの下に作成されます。 API を使用すると、ホテルグループの一覧表示、取得、更新、追加を行うことができます。

ホテルグループの管理に使用する REST テンプレートを次に示します。

/SubAccounts('{subAccountId}')/HotelGroups—POST を取得する |
/SubAccounts('{subAccountId}')/HotelGroups('{hotelGroupId}')— パッチ削除を | 取得する |

ホテルグループを取得、追加、更新する例については、コード例を参照してください。 (右側のウィンドウの [言語] セレクターを使用して、異なる言語の例を表示します)。

ホテルグループの一覧表示

既定では、サブアカウントでホテルグループの一覧を要求すると、API は最大 1,000 グループを返します。サブアカウント内のグループの合計数を確認するには、 $count クエリパラメーターを使用します。返すグループの数を指定するには、 $top クエリパラメーターを使用します。 1 回の呼び出しで要求できるグループの最大数は 5,000 です。サブアカウントに 5,000 を超えるグループが含まれている場合は、$topと $skip クエリパラメーターを使用して、すべてのグループをページングします。

サブアカウントの下にある最初の 1,000 のホテルグループの一覧を取得するには、次の要求を送信します。

GET https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>')/HotelGroups HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Accept: application/json
Host: <host>

応答には CollectionResponse オブジェクトが含まれています。配列には value 、 HotelGroup オブジェクトの一覧が含まれています。この例では、既定のグループ化されていないグループを示します。

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
x-ms-requestid: f526c0e6-f7d8-48c7-9270-8fb0a0465153
x-ms-trackingid: 21fafae0-4053-46e0-8271-87bc5fce6312

{
  "@odata.count":6,
  "value":[
    {
      "Id":"55113020342274",
      "Name":"UnGrouped",
      "Status":"Active",
      "Bid":{
        "@odata.type":"#Model.FixedBid",
        "Amount":3.0
      },
      "BidSource":"SubAccount",
      "BidMultiplierSource":null,
      "BidMultipliers":[]
    },
	
	. . .
	
    {
      "Id":"55113020351605",
      "Name":"test-2",
      "Status":"Active",
      "Bid":{
        "@odata.type":"#Model.FixedBid",
        "Amount":1.5
      },
      "BidSource":"HotelGroup",
      "BidMultiplierSource":null,
      "BidMultipliers":[]
    }
  ]
}

ホテルグループの追加

ホテルの新しい論理グループを作成する場合は、新しいホテルグループを作成します。ホテルグループを指定するには、 HotelGroup オブジェクトを使用します。必須フィールドはのみです Name。グループ化を示すわかりやすい名前を使用します。 Bid と BidMultipliers フィールドは省略可能です。指定しない場合、グループはサブアカウントの入札と入札の乗数を使用します。サブアカウント値をオーバーライドする場合は、それらを指定します。入札、乗数、またはその両方を指定できます。

市場の有効な入札範囲の詳細については、「通貨」トピックの「通貨値」の表を参照してください。

次の例では、サブアカウントから入札と入札の乗数を継承するホテルグループを作成します。

POST https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>')/HotelGroups HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Accept: application/json
Host: <host>
Content-Length: 26

{"Name":"test-3"}

応答は、追加されたホテルグループの ID を含む AddResponse オブジェクトです。

HTTP/1.1 200 OK
Content-Length: 140
Content-Type: application/json; odata.metadata=minimal
x-ms-requestid: 8a2e2026-e170-4607-b4fe-06954a67b80a
x-ms-trackingid: e86fcdbd-613e-44a9-b5fc-528cfa87297a

{
  "value":"55113020351606"
}

ホテルグループを追加した後、関連付けテンプレートを使用してグループにホテルを追加します。詳細については、「ホテルとホテルグループの関連付け」を参照してください。

ホテルグループの更新

ホテルグループは、グループ内のホテルに使用する既定の入札と入札乗数を指定します。グループは明示的に指定するか、属するサブアカウントから継承します。 API を使用して、入札または乗数を指定しないホテルに使用する入札と入札の乗数を更新できます。

市場の有効な入札範囲と予算の詳細については、「通貨」トピックの「通貨価値」の表を参照してください。

サブアカウントで最大入札額が指定されている場合、ホテルグループの入札額はサブアカウントの最大入札額を下回る必要があります。

ホテルグループ内のすべてのホテルを一時停止するには、グループの Bid プロパティを PercentageBid オブジェクトに設定し、入札率を 0 (0.0) に設定します。

グループが 0 より大きい入札を指定したが、グループのホテルが提供されていない場合は、サブアカウントの入札価格が 0 であることが原因である可能性があります。

ホテルグループの入札を削除するには、null ("Bid":null など) に設定 Bid します。

ホテルグループで入札乗数を指定し、それらを削除する場合は、空の配列 ("BidMultipliers":[]) に設定 BidMultipliers します。

ホテルグループを更新するには、PATCH 要求を送信します。要求の本文は、HotelGroup オブジェクトです。更新するプロパティのみを含めます。この例では、入札と乗数の更新を示します。

PATCH https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>')/HotelGroups('<hotelgroupid>') HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Content-Type: application/json
Content-Length: 474
Host: <host>

{
  "Id":"55113020351606",
  "Bid":{
    "Amount":4.75,
    "@odata.type":"#Model.FixedBid"
  },
  "BidMultipliers":[
    {
      "DeviceTypes":["Desktop"],
      "Factor":0.65,
      "@odata.type":"#Model.DeviceMultiplier"
    },
    {
      "MinimumNumberOfNights":7,
      "Factor":1.3,
      "@odata.type":"#Model.LengthOfStayMultiplier"
    },
    {
      "DaysOfWeek":["Thursday","Friday","Saturday"],
      "Factor":1.5,
      "@odata.type":"#Model.CheckinDayOfWeekMultiplier"
    },
    {
      "DaysOfWeek":["Sunday","Monday"],
      "Factor":2.5,
      "@odata.type":"#Model.CheckinDayOfWeekMultiplier"
    }
  ]
}

ホテルグループの取得

特定のホテルグループを取得するには、次の要求を送信します。ホテルグループ ID は、次に示すように、単一引用符で囲む必要があります。

GET https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>')/HotelGroups('<hotelgroupid>') HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Accept: application/json
Host: <host>

応答には、HotelGroup オブジェクトが含まれています。

HTTP/1.1 200 OK
Content-Length: 813
Content-Type: application/json; odata.metadata=minimal
x-ms-requestid: 3be2a39c-723c-41bd-9e74-0a9e44c4fa3c
x-ms-trackingid: e5eba818-2ef7-4fe6-9225-9e2325414e3b

{
  "Id":"55113020351606",
  "Name":"test-2",
  "Status":"Active",
  "Bid":{
    "@odata.type":"#Model.FixedBid",
    "Amount":4.75
  },
  "BidSource":"HotelGroup",
  "BidMultiplierSource":"HotelGroup",
  "BidMultipliers":[
    {
      "@odata.type":"#Model.DeviceMultiplier",
      "Factor":0.65,
      "DeviceTypes":["Desktop"]
    },
    {
      "@odata.type":"#Model.LengthOfStayMultiplier",
      "Factor":1.3,
      "MinimumNumberOfNights":7
    },
    {
      "@odata.type":"#Model.CheckinDayOfWeekMultiplier",
      "Factor":2.5,
      "DaysOfWeek":["Monday","Sunday"]
    },
    {
      "@odata.type":"#Model.CheckinDayOfWeekMultiplier",
      "Factor":1.5,
      "DaysOfWeek":["Thursday","Friday","Saturday"]
    }
  ],
  "HotelAssociationCount":0
}

ホテルでの作業

ホテルはホテルフィードのホテルを表します。 API を使用すると、ホテルの一覧表示、取得、更新を行うことができます。 API を使用してホテルを追加することはできません。ホテルを追加するには、ホテルフィードを使用します。ホテルはサブアカウントごとに一意です。複数のサブアカウントに同じホテルが含まれていない場合があります。

ホテルの管理に使用する REST テンプレートを次に示します。

/SubAccounts('{subAccountId}')/Hotels — GET
/SubAccounts('{subAccountId}')/HotelGroups('{hotelGroupId}')/Hotels — GET
/SubAccounts('{subAccountId}')/HotelGroups('{hotelGroupId}')/Hotels('{hotelId}') — GET | PATCH

ホテルを取得して更新する例については、ホテルの例を参照してください。 (右側のウィンドウの [言語] セレクターを使用して、異なる言語の例を表示します)。

一覧のホテル

既定では、ホテルグループ内のホテルの一覧を要求すると、API は最大 1,000 のホテルを返します。ホテルグループ内のホテルの合計数を確認するには、 $count クエリパラメーターを使用します。返すホテルの数を指定するには、 $top クエリパラメーターを使用します。 1 回の通話で要求できるホテルの最大数は 5,000 です。ホテルグループに 5,000 を超えるホテルが含まれている場合は、 $topを使用し、$skipクエリパラメーターを使用してホテルをページングします。

注:

$TOP と $skip クエリパラメーターを使用して、UI エクスペリエンスのホテルをページングする必要があります。すべてのホテルを取得するには、レポート機能を使用してホテルをダウンロードします。

/SubAccounts('{subAccountId}')/Hotels
/SubAccounts('{subaccountid}')/HotelGroups('{hotelgroupid}')/Hotels
/SubAccounts('{subAccountId}')/Ungrouped

ホテルグループの最初の 1,000 ホテルを取得するには、次の要求を送信します。

GET https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>')/HotelGroups('<hotelgroupid>')/Hotels HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Accept: application/json
Host: <host>

応答には CollectionResponse オブジェクトが含まれています。配列には value 、 Hotel オブジェクトの一覧が含まれています。

HTTP/1.1 200 OK
Content-Length: 1611
Content-Type: application/json; odata.metadata=minimal
x-ms-requestid: d836f741-8083-4d54-b49e-e1f14287b944
x-ms-trackingid: 3787a393-eca3-4ad0-be3d-dd4c7ae08906

{
  "@odata.count":2,
  "value":[
    {
      "Id":"55113020344013",
      "Name":"Contoso Inn Singer",
      "PartnerHotelId":"942909",
      "Status":"Active",
      "CountryCode":"US",
      "Bid":{
        "@odata.type":"#Model.FixedBid",
        "Amount":2.75
      },
      "BidSource":"HotelGroup",
      "BidMultiplierSource":"HotelGroup",
      "BidMultipliers":[
        {
          "@odata.type":"#Model.DeviceMultiplier",
          "Factor":2.65,
          "DeviceTypes":["Desktop"]
        },
        {
          "@odata.type":"#Model.LengthOfStayMultiplier",
          "Factor":1.3,
          "MinimumNumberOfNights":8
        },
        {
          "@odata.type":"#Model.UserCountryMultiplier",
          "Factor":1.1,
          "Countries":["US"]
        },
        {
          "@odata.type":"#Model.AdvanceBookingWindowMultiplier",
          "Factor":1.3,
          "MinimumNumberOfDays":3
        },
        {
          "@odata.type":"#Model.CheckinDayOfWeekMultiplier",
          "Factor":0.9,
          "DaysOfWeek":["Monday","Sunday"]
        },
        {
          "@odata.type":"#Model.CheckinDayOfWeekMultiplier",
          "Factor":1.2,
          "DaysOfWeek":["Thursday","Friday","Saturday"]
        },
        {
          "@odata.type":"#Model.SiteMultiplier",
          "Factor":0.85,"Sites":["MapResults","LocalUniversal"]
        }
      ]
    },
    {
      "Id":"55113020351595",
      "Name":"Contoso Inn Casino Center",
      "PartnerHotelId":"60278",
      "Status":"Active",
      "CountryCode":"US",
      "Bid":{
        "@odata.type":"#Model.FixedBid",
        "Amount":2.75
      },
      "BidSource":"HotelGroup",
      "BidMultiplierSource":null,
      "BidMultipliers":[]
    }
  ]
}

ホテルの更新

ホテルでは、ホテルの価格広告に使用する入札と入札の乗数を指定します。ホテルは明示的にそれらを指定するか、ホテルグループまたはサブアカウントからその順序で継承します。 API を使用して、ホテルの広告に使用する入札と入札の乗数を更新できます。

市場の有効な入札範囲の詳細については、「通貨」トピックの「通貨値」の表を参照してください。

サブアカウントで最大入札額が指定されている場合、ホテルの入札額はサブアカウントの最大入札額を下回る必要があります。

ホテルを一時停止するには、プロパティを BidPercentageBid オブジェクトに設定し、入札率を 0 (0.0) に設定します。

ホテルが 0 より大きい入札を指定したが、提供されていない場合は、属するホテルグループまたはサブアカウントの入札が 0 である可能性があります。

ホテルの入札を削除するには、その Bid 入札を null ("Bid":null など) に設定します。

ホテルで入札乗数を指定し、それらを削除する場合は、空の配列 ("BidMultipliers":[]) に設定 BidMultipliers します。

ホテルを更新するには、 PATCH 要求を送信します。要求では、Microsoft がホテルに割り当てた ID、または広告主がホテルに割り当てた ID を指定できます。広告主割り当て ID を指定する場合、要求で PartnerHotelId クエリパラメーターを true に設定する必要があります。

要求の本文は、Hotel オブジェクトです。更新するプロパティのみを含めます。この例では、乗数の更新を示します。

{
  "BidMultipliers":[
    {
      "Countries":["US"],
      "Factor":1.1,
      "@odata.type":"#Model.UserCountryMultiplier"
    },
    {
      "DeviceTypes":["Desktop"],
      "Factor":2.65,
      "@odata.type":"#Model.DeviceMultiplier"
    }
  ]
}

ホテルの取得

特定のホテルを取得するには、次の要求を送信します。ホテル ID は、次のように単一引用符で囲む必要があります。

GET https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>')/HotelGroups('<hotelgroupid>')/Hotels('<hotelid>') HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Accept: application/json
Host: <host>

応答には、Hotel オブジェクトが含まれています。

HTTP/1.1 200 OK
Content-Length: 1122
Content-Type: application/json; odata.metadata=minimal
x-ms-requestid: a9a591c2-01c1-4e1c-8a6a-5cdece574460
x-ms-trackingid: ceb70eb3-36ca-4b99-a5f7-b1a04de1e4ae

{
  "Id":"55113020344013",
  "Name":"Contoso Inn Singer",
  "PartnerHotelId":"942909",
  "Status":"Active",
  "CountryCode":"US",
  "Bid":{
    "@odata.type":"#Model.FixedBid",
    "Amount":3.0
  },
  "BidSource":"SubAccount",
  "BidSource":"Hotel",
  "BidMultipliers":[
    {
      "@odata.type":"#Model.DeviceMultiplier",
      "Factor":2.65,
      "DeviceTypes":["Desktop"]
    },
    {
      "@odata.type":"#Model.UserCountryMultiplier",
      "Factor":1.1,
      "Countries":["US"]
    }
  ]
}

滞在期間と高度な予約期間の乗数

LengthOfStayMultiplier の説明では、ユーザーが指定した宿泊日数以上滞在している場合Bing乗数が適用されます。また、AdvanceBookingWindowMultiplier の説明では、予約が指定した日数以上前に発生した場合、Bing乗数が適用されることも示されています。説明の重要な部分は語句 、またはそれ以上です。

これらの乗数の複数を指定する場合、係数と日数/夜間の組み合わせは一意である必要があります。それ以外の場合、呼び出しは DuplicateValues エラーで失敗します。次の LengthOfStayMultiplier の例では、各エントリの係数は 1 です。 6泊以上の滞在には6泊分の入場が適用されるため、8泊目の2回目の入場は重複です。このエラーを解決するには、8 泊分のエントリを削除するか、別の係数値を指定します。

  {
      "MinimumNumberOfNights": 8,
      "Factor": "1",
      "@odata.type": "#Model.LengthOfStayMultiplier"
    },
    {
      "MinimumNumberOfNights": 6,
      "Factor": "1",
      "@odata.type": "#Model.LengthOfStayMultiplier"
  }

ホテルとホテルグループの関連付け

ホテルフィードファイルをインポートすると、ホテルは既定のホテルグループである グループ化されていない ホテルグループに配置されます。ホテルは、1 つのホテルグループにのみ関連付けられます。ホテルを論理的に整理する新しいホテルグループを作成する場合は、グループ 化されていない ホテルグループから作成した新しいグループにホテルを移動します。ホテルを新しいホテルグループに関連付けるには、関連付けテンプレートを使用します。ホテルを新しいホテルグループに関連付けると、サービスは以前の関連付けを削除します。

次の POST の例では、関連付けを指定する方法を示します。要求の本文は AssociationCollection オブジェクトです。コレクションには、最大 500 個の HotelAssociation オブジェクトが含まれる場合があります。

POST https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>')/Associate HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Content-Type: application/json
Host: <host>
Content-Length: 169

{
  "HotelAssociations":[
    {
      "HotelGroupId":"55113020351226",
      "HotelId":"55113020351595"
    },
    {
      "HotelGroupId":"55113020351226",
      "HotelId":"55113020344013"
    }
  ]
}

Associate メソッドは常に成功を返す必要があります。 1 つ以上の関連付けが失敗した場合、応答には失敗した関連付けの入力関連付けと失敗の理由が含まれます。

応答には CollectionResponse オブジェクトが含まれています。すべての関連付けが成功した場合、 value 配列は空です。それ以外の場合は、 value 失敗した関連付けごとに HotelAssociation オブジェクトが含まれます。関連付けの Errors フィールドには、エラーの理由が含まれています。

HTTP/1.1 200 OK
Content-Length: 770
Content-Type: application/json; odata.metadata=minimal
x-ms-requestid: 574fe6c6-503d-427d-8921-a259f76de0ed
x-ms-trackingid: a5f2510e-709a-4370-876e-bfb05ef2b8df

{
  "value":[
    {
      "HotelId":"55113020351595",
      "HotelName":null,
      "PartnerHotelId":null,
      "HotelGroupId":"55113020351226",
      "HotelGroupName":null,
      "Errors@odata.type":"#Collection(Model.AdsApiError)",
      "Errors":[
        {
          "Code":"<code>","Property":"<propertyname>","Message":"<messagestring>"
        }
      ]
    }
  ]
}

ホテルの協会を取得する

既定では、サブアカウント内の関連付けの一覧を要求すると、API は最大 1,000 個の関連付けを返します。関連付けの合計数を確認するには、 $count クエリパラメーターを使用します。返す関連付けの数を指定するには、 $top クエリパラメーターを使用します。 1 回の呼び出しで要求できる関連付けの最大数は 5,000 です。サブアカウントに 5,000 を超える関連付けが含まれている場合は、$topと $skip クエリパラメーターを使用して、すべての関連付けをページングします。

サブアカウントの最初の 1,000 のホテルとホテルグループの関連付けを取得するには、次の要求を送信します。

GET https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>')/Associations HTTP/1.1
Authorization: Bearer <oauthaccesstoken>
Accept: application/json
Host: <host>

応答には CollectionResponse オブジェクトが含まれています。配列には value 、 HotelAsssociation オブジェクトの一覧が含まれています。

HTTP/1.1 200 OK
Content-Length: 6880
Content-Type: application/json; odata.metadata=minimal
x-ms-requestid: 50bb9a63-f324-4c28-84f9-733b24ab3d0f
x-ms-trackingid: 4fa56e03-7e86-4f44-b671-8e00a67c2eed

{
  "@odata.count":39540,
  "value":[
    {
      "HotelId":"55113020342273",
      "HotelName":"Contoso Inn Downtown DC/Convention Center",
      "PartnerHotelId":"99995",
      "HotelGroupId":"55113020342274",
      "HotelGroupName":"UnGrouped"
    },
    {
      "HotelId":"55113020342274",
      "HotelName":"The Contoso Hotel",
      "PartnerHotelId":"999896",
      "HotelGroupId":"55113020342274",
      "HotelGroupName":"UnGrouped"
    },
    
    . . .
    
  ]
}

ホテルの関連付けのフィルター処理

関連付けのサブセットを返すには、OData $filter クエリパラメーターを使用します。関連付けをフィルター処理できるのは、または PartnerHotelId のみHotelIdです。 URL の最大長 (2,048) によって、指定できる ID の数が決まります。 URL が 2,048 文字を超える場合、要求は 404 を返します。

指定したホテルの関連付けを返す例を次に示します。

GET https://<host>/Travel/V1/Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>')/Associations?$filter=HotelId+eq+'55113020342282'+or+HotelId+eq+'55113020344943' HTTP/1.1
Authorization: Bearer <accesstokengoeshere>
Accept: application/json
Host: <host>

バッチ処理

1 つの HTTP 要求で複数の要求を送信するには、 /$batch テンプレートを使用します。 1 つのバッチ要求で最大 500 件の要求を送信できます。

注:

バッチ処理は、入札変更などのホテルの更新に対してのみサポートされます。

要求

要求の例を次に示します。

POST https://<host>/Travel/V1/$batch HTTP/1.1
Authorization: Bearer <accesstokengoeshere>
Content-Type: multipart/mixed; boundary=batch_086fe0de-9b26-4d4a-a206-6df2013a2816
Host: <host>
Content-Length: 1371

Content-Type ヘッダーは、マルチパート/混合に設定し、境界 ID を含める必要があります。境界 ID は不透明であり、バッチ要求の各サブ要求を区切ります。 ID には、任意の一意の文字列を指定できます。この例では、一意batch_<文字列>を使用します。一 <意の文字列> は GUID です。

バッチ要求の本文には、境界 ID で区切られた複数の個々の要求が含まれています。バッチ要求の本文の例を次に示します。バッチ要求の本文の各行を CRLF (キャリッジリターンとラインフィード) で終了してください。

--batch_086fe0de-9b26-4d4a-a206-6df2013a2816
Content-Type: application/http
Content-Transfer-Encoding: binary

PATCH Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>')/HotelGroups('<groupid>')/Hotels('<hotelid>') HTTP/1.1
Content-Type: application/json; odata.metadata=minimal
Host: partner.api.sandbox.bingads.microsoft.com

{"Id":"<hotelid>","Bid":{"Amount":1.75,"@odata.type":"#Model.FixedBid"}}

--batch_086fe0de-9b26-4d4a-a206-6df2013a2816
Content-Type: application/http
Content-Transfer-Encoding: binary

PATCH Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>')/HotelGroups('groupid>')/Hotels('<hotelid>') HTTP/1.1
Content-Type: application/json; odata.metadata=minimal
Host: partner.api.sandbox.bingads.microsoft.com

{"Id":"<hotelid>","Bid":{"Amount":1.75,"@odata.type":"#Model.FixedBid"}}

--batch_086fe0de-9b26-4d4a-a206-6df2013a2816
Content-Type: application/http
Content-Transfer-Encoding: binary

PATCH Customers(<customerid>)/Accounts(<accountid>)/SubAccounts('<subaccountid>')/HotelGroups('groupid>')/Hotels('<hotelid>') HTTP/1.1
Content-Type: application/json; odata.metadata=minimal
Host: partner.api.sandbox.bingads.microsoft.com

{"Id":"<hotelid>","Bid":{"Amount":1.75,"@odata.type":"#Model.FixedBid"}}

--batch_086fe0de-9b26-4d4a-a206-6df2013a2816--

各境界 ID の先頭に二重ダッシュ (たとえば、 --batch_086fe0de-9b26-4d4a-a206-6df2013a2816) があることに注意してください。バッチ内の最後の要求の後に行く終了境界 ID は、二重ダッシュで囲まれます (たとえば、 --batch_086fe0de-9b26-4d4a-a206-6df2013a2816--)。

境界 ID 区切り記号の後に、次に示すように、Content-Type ヘッダーと Content-Transfer-Encoding ヘッダーを指定する必要があります。ホテルのみを更新できるため、要求では HTTP PATCH 動詞を使用し、ホテルテンプレートを使用して、更新するホテルを識別する必要があります。要求には Content-Type ヘッダーが含まれている必要があり、 application/json、odata.metadata=minimal に設定する必要があります。要求の本文は、Hotel オブジェクトです。オブジェクトにはホテルの ID を含める必要があり、更新するフィールドのみを含める必要があります。

応答

応答も同様に区切られ、応答の各項目は要求の各項目に直接対応します。応答の Content-Type ヘッダーには、境界 ID が含まれています。 ID を取得し、それを使用して各応答項目を解析します。

上記の要求に対する応答を次に示します。

HTTP/1.1 200 OK
Content-Type: multipart/mixed; boundary=batchresponse_d33d1715-3dd3-45aa-80a9-854493c8764e
x-ms-requestid: c0fb9b49-2af0-4b41-bf57-0e4a0f8b55b9
x-ms-trackingid: 8b652a73-1bef-488d-b7d5-f371a31867a4
Date: Tue, 27 Mar 2018 20:30:19 GMT
Content-Length: 512

--batchresponse_d33d1715-3dd3-45aa-80a9-854493c8764e
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 204 No Content


--batchresponse_d33d1715-3dd3-45aa-80a9-854493c8764e
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 204 No Content


--batchresponse_d33d1715-3dd3-45aa-80a9-854493c8764e
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 204 No Content


--batchresponse_d33d1715-3dd3-45aa-80a9-854493c8764e--

各応答項目には HTTP 状態が含まれます。更新の場合、更新が成功した場合、状態は 204 です。更新が失敗した場合 (たとえば、ホテルが見つからなかった場合、値が無効な場合、またはホテルオブジェクトの形式が正しくない場合)、状態は 400 で、本文にはエラーの一覧が含まれます。 (要求が他の状態コードで失敗する可能性があります)。

エラーを含む応答項目を次に示します。エラーが発生した場合、本文には CollectionResponse オブジェクトが含まれており、配列内の value 各項目は AdsApiError オブジェクトです。

--batchresponse_d0048f4c-8a3f-40aa-9392-718943ecc5f3
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 400 Bad Request
x-ms-requestid: 00b551c2-b552-4cca-9e1b-04e0e5ffb4b7
x-ms-trackingid: ad383e45-4174-43d7-95bc-cca2ac6176e8
Content-Type: application/json; odata.metadata=minimal; odata.streaming=true
OData-Version: 4.0

{
  "@odata.count":1,
  "value":[
    {
      "Code":"EntityDoesNotExist","Property":null,"Message":null
    }
  ]
}
--batchresponse_d0048f4c-8a3f-40aa-9392-718943ecc5f3--

バッチ要求を処理するためのコード例

バッチ要求でホテルの価格を更新するコード例については、「バッチ処理の例」を参照してください。