即時出價疑難排解

本指南涵蓋即時出價疑難排解資源，方便您透過程式存取 即時出價廣告活動指標 也會透過 Authorized Buyers 使用者介面。這些元素包括 bidders.filterSets、bidders.accounts.filterSets 和 依階層結構顯示所有資源

運用即時出價疑難排解資源中的指標，進一步瞭解錯失的商機 以贏得曝光，進而最佳化即時出價廣告活動。

調整 API 結構和樣式

即時出價疑難排解資源做了幾項調整，以明確指出擁有權以及 對 API 傳回的資料進行更精細的控制，並且更好地符合 Google API 設計做法。

出價方層級和帳戶層級資源

資源結構同時位於 bidders 和 bidders.accounts 底下。可讓您指定 API 呼叫是否指定了出價方 (也稱為上層帳戶) 以及所有相關 子帳戶或個別 Authorized Buyers 帳戶在即時出價方面 疑難排解，採用 bidders.filterSets 結構的資源會傳回匯總指標 為指定的出價方和所有相關子帳戶設定。相對地 bidders.accounts.filterSets 只會傳回指定帳戶的指標，無論是否加入 出價工具或子帳戶

注意：將出價委派給其他買方的帳戶並非出價方帳戶。 因此無法存取出價工具層級資源。此外，非出價者帳戶無法 存取帳戶層級的 impressionMetrics、filteredBidResponses、bidResponseErrors 和 bidResponsesWithoutBids 資源。

隆重推出以資源名稱做為專屬 ID

資源名稱的用途是 專屬 ID，而非整數或字串 ID。建立 資源類型，現在您必須指定 相對 資源名稱，使用資源 URI 路徑，後面加上偏好的資源 ID。 以下列舉幾個與即時出價疑難排解資源相關的名稱範例：

資源	名稱範例
bidders.filterSets	bidders/12345678/filterSets/fset_1
bidders.accounts.filterSets	bidders/12345678/accounts/87654321/filterSets/fset_2

注意：在名稱中為 bidders 指定的資源 ID 必須是出價方的 Authorized Buyers 帳戶 ID。如果是 accounts，資源 ID 必須是 出價方或其管理的子帳戶。如果您不知道哪個 Authorized Buyers 這兩個帳戶都與您的 Google 帳戶連結，您可以使用 accounts.list 方法來找出這些金鑰。

篩選器集

篩選器組合代表可用的篩選選項，且可 出價工具或帳戶層級用於篩選即時出價疑難排解的結果清單 資源，用於擷取即時出價廣告活動指標。

擷取指標時套用的篩選器，是指定值中每個篩選器的交集。 篩選組合。系統會將清單篩選器 (例如 platforms) 解讀為清單中的每個項目的聯集。

出價方和帳戶層級篩選器組合各自獨立，且只能從所屬的層級存取 無論當初用來建立這些素材資源的帳戶為何，系統都會建立通知。出價方和子帳戶共用 篩選器組合是在帳戶層級建立的，但只有出價方可以存取 出價工具層級下表摘要說明出價方和子帳戶存取資源的方式 兩個層級：

	bidders.filterSets	bidders.accounts.filterSets
出價方帳戶	只會影響出價工具層級篩選器集的 API 呼叫。	只影響帳戶層級篩選器集的 API 呼叫。
孩童帳戶	這項 API 呼叫會傳回錯誤回應。	只影響帳戶層級篩選器集的 API 呼叫。

建立篩選器組合

建立篩選器組合時，您必須以 relativeDateRange 格式指定時間範圍。 absoluteDateRange 或 realtimeTimeRange。擷取指標時 預設行為是提供給整個時間範圍內的所有資料。如果希望收到 時間序列細目時，您可以指定 timeSeriesGranularity 表示 HOURLY 或 DAILY 間隔。

如果您僅需要短期的篩選器設定，可以將 isTransient 查詢參數加入 true 中。這表示篩選器組合是暫時性的，因此不會無限期保留。暫時篩選器組合建立完成後，至少還有一小時可用，但最終會遭到刪除。根據預設，篩選器集並不是暫時性的。

出價方層級範例

如要建立新的出價工具層級篩選器組合，請將 POST 要求傳送至 bidders.filterSets 資源 URI，格式如下：

https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets

警告：出價方層級篩選器組合無法按廣告素材或交易 ID 篩選。如果您在建立出價工具層級篩選器集時指定這些篩選條件，您會收到錯誤回應。

要求

以下是建立新的非暫時性出價工具層級篩選器組合的 POST 要求範例：

POST https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets
Authorization: Bearer access token here
Content-Type: application/json

{
  "name": "bidders/12345678/filterSets/bidder-fs",
  "format": "DISPLAY",
  "environment": "APP",
  "platforms": ["TABLET", "MOBILE"],
  "absoluteDateRange": {
    "startDate": {
      "month": 11,
      "day": 26,
      "year": 2017
    },
    "endDate": {
      "month": 12,
      "day": 3,
      "year": 2017
    }
  },
  "timeSeriesGranularity": "DAILY"
}

敬上 回覆

如果要求成功，伺服器會以 200 OK 狀態碼回應。回應主體會包含建立的篩選器集資源，與要求中提交的篩選器組合相同。

帳戶層級範例

如要建立新的帳戶層級篩選器組合，請將 POST 要求傳送至 bidders.accounts.filterSets 資源 URI，格式如下：

https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets

注意：為 accounts 指定的資源 ID 可以 是出價方可存取的任何 Authorized Buyers 帳戶 ID 帳戶，包括出價方帳戶本身。

要求

以下是利用 POST 要求建立新的非暫時性帳戶層級篩選器組合的範例：

POST https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets
Authorization: Bearer access token here
Content-Type: application/json

{
  "name": "bidders/12345678/accounts/87654321/filterSets/account-fs",
  "format": "VIDEO",
  "environment": "WEB",
  "platforms": ["DESKTOP"],
  "absoluteDateRange": {
    "startDate": {
      "month": 11,
      "day": 26,
      "year": 2017
    },
    "endDate": {
      "month": 12,
      "day": 3,
      "year": 2017
    }
  },
  "timeSeriesGranularity": "DAILY"
}

敬上 回覆

如果要求成功，伺服器會以 200 OK 狀態碼回應。回應主體會 加入建立的篩選器集資源，必須與您在 要求。

取得篩選器組合

get 方法只能取得在建立時位於相同層級的篩選器。例如，出價方 帳戶應使用 bidders.accounts.filterSets.get 擷取在帳戶中建立的篩選器組合 而非 bidders.filterSets.get 方法

出價方層級

如要擷取出價工具層級篩選器設定，請將 HTTP GET 要求傳送至下列格式的 bidders.filterSets 資源 URI：

GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets/{filter set resource ID}

敬上 要求

範例如下：

GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets/bidder-fs

敬上 回覆

如果要求成功，伺服器會以 200 OK HTTP 狀態碼回應，以及擷取的篩選器組合：

{
  "name": "bidders/12345678/filterSets/bidder-fs",
  "format": "DISPLAY",
  "environment": "APP",
  "platforms": ["TABLET", "MOBILE"],
  "absoluteDateRange": {
    "startDate": {
      "month": 11,
      "day": 26,
      "year": 2017
    },
    "endDate": {
      "month": 12,
      "day": 3,
      "year": 2017
    }
  },
  "timeSeriesGranularity": "DAILY"
}

帳戶層級

如要擷取帳戶層級篩選器設定，請將 HTTP GET 要求傳送至下列格式的 bidders.accounts.filterSets 資源 URI：

GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets/{filter set resource ID}

敬上 要求

範例如下：

GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets/account-fs

敬上 回覆

如果要求成功，伺服器會以 200 OK HTTP 狀態碼回應，以及擷取的篩選器組合：

{
  "name": "bidders/12345678/accounts/87654321/filterSets/account-fs",
  "format": "VIDEO",
  "environment": "WEB",
  "platforms": ["DESKTOP"],
  "absoluteDateRange": {
    "startDate": {
      "month": 11,
      "day": 26,
      "year": 2017
    },
    "endDate": {
      "month": 12,
      "day": 3,
      "year": 2017
    }
  },
  "timeSeriesGranularity": "DAILY"
}

列出篩選器集

清單方法只會傳回可從所呼叫層級存取的篩選器組合。 舉例來說，出價方帳戶不會顯示為自己建立的篩選器組合 呼叫 bidders.filterSets.list 時為 bidders.accounts.filterSets.create。

出價方層級

您可以傳送 HTTP GET，擷取特定出價方的所有出價工具層級篩選器組合 要求至 bidders.filtersets 資源 URI，且格式如下：

GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets

敬上 要求

以下範例是針對帳戶 ID 為 12345678 的出價工具，列出所有出價方層級篩選器組合：

GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets

敬上 回覆

{
  "filterSets": [{
      "filterSetId": "99994",
      "name": "bidders/12345678/filterSets/test-b-1",
      "relativeDateRange": {
        "durationDays": 30
      }
    },
    {
      "realtimeTimeRange": {
        "startTimeStamp": "2017-11-15T12:30:30.072831583Z"
      },
      "filterSetId": "99995",
      "name": "bidders/12345678/filterSets/test-b-2",
      "timeSeriesGranularity": "HOURLY"
    },
    {
      "absoluteDateRange": {
        "endDate": {
          "day": 12,
          "month": 3,
          "year": 2017
        },
        "startDate": {
          "day": 26,
          "month": 11,
          "year": 2017
        }
      },
      "filterSetId": "99996",
      "name": "bidders/12345678/filterSets/bidder-fs",
      "timeSeriesGranularity": "DAILY",
      "platforms": ["TABLET", "MOBILE"],
      "environment": "APP",
      "format": "DISPLAY"
    }
  ]
}

帳戶層級

您可以傳送 HTTP GET，擷取特定帳戶的所有帳戶層級篩選器組合 要求至 bidders.accounts.filtersets 資源 URI，且格式如下：

GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets

敬上 要求

以下範例為帳戶 ID 為 87654321 的子帳戶，列出所有帳戶層級篩選器組合：

GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets

敬上 回覆

{
  "filterSets": [{
        "realtimeTimeRange": {
        "startTimeStamp": "2017-11-19T04:24:43.252893487Z"
      },
      "filterSetId": "99997",
      "name": "bidders/12345678/accounts/87654321/filterSets/test-a-1",
      "timeSeriesGranularity": "DAILY"
    },
    {
      "absoluteDateRange": {
        "endDate": {
          "day": 3,
          "month": 12,
          "year": 2017
        },
        "startDate": {
          "day": 26,
          "month": 11,
          "year": 2017
        }
      },
      "filterSetId": "99998",
      "name": "bidders/12345678/accounts/87654321/filterSets/account-fs",
      "timeSeriesGranularity": "DAILY",
      "platforms": ["DESKTOP"],
      "environment": "WEB",
      "format": "VIDEO"
    }
  ]
}

刪除篩選器組合

您可以使用 delete 方法，移除任何非暫時性的篩選器集 要求執行虛擬機器只能從目前呼叫的層級移除可存取的篩選器組合。 舉例來說，出價方帳戶無法刪除使用 bidders.accounts.filterSets.create 建立的篩選器組合 bidders.filterSets.delete。

出價方層級

如要刪除特定帳戶的出價方層級篩選器組合，請傳送 HTTP DELETE 請求 附加至 bidders.filtersets 資源 URI，格式如下：

DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets/{filter set resource ID}

敬上 要求

以下舉例說明如何刪除出價工具層級篩選器組合：

DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets/test-b-2

敬上 回覆

如果成功，要求主體會是空白的。將無法再存取指定的篩選器組合。

帳戶層級

您可以傳送 HTTP DELETE，藉此刪除特定帳戶的帳戶層級篩選器組合 要求至 bidders.accounts.filtersets 資源 URI，且格式如下：

DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets/{filter set resource ID}

敬上 要求

以下是刪除帳戶層級篩選器組合的範例：

DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets/test-a-1

敬上 回覆

如果成功，要求主體會是空白的。將無法再存取指定的篩選器組合。

擷取即時出價疑難排解指標

所有用來接收指標的 RTB 疑難排解資源的運作方式都很類似， 使用單一方法，列出透過 filterSetName 路徑指定的篩選器組合指標 參數。指定的篩選器組合會決定要在 查詢指標從出價工具層級呼叫這些資源，會傳回匯總指標 來自出價工具帳戶和所有相關子帳戶，但來自帳戶層級的呼叫 只會傳回個人帳戶的指標。

出價指標

bidMetrics 資源可用來擷取 出價次數舉例來說，這項數據可以用來判定 以及其中有多少人未從競價中篩除並贏得曝光 等等。如同所有其他用來收集指標的即時出價疑難排解資源，它只有 list 方法。

列出出價方層級出價指標

只要傳送 HTTP GET，即可列出特定篩選器組合的出價工具層級出價指標 要求至 bidders.filtersets.bidMetrics 資源 URI，且格式如下：

GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets/{filter set resource ID}/bidMetrics

敬上 要求

以下是列出出價工具層級出價指標的範例：

GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets/bidder-fs/bidMetrics

敬上 回覆

如果要求成功，伺服器會傳回 200 OK 狀態碼回應，內文則包含指定維度和精細程度指標的資料列。

{
  "bidMetricsRows": [{
        "bids": {
        "value": "6160"
      },
      "bidsInAuction": {
        "value": "5698"
      },
      "billedImpressions": {
        "value": "1196"
      },
      "impressionsWon": {
        "value": "2920"
      },
      "measurableImpressions": {
        "value": "1160"
      },
      "rowDimensions": {
        "timeInterval": {
          "endTime": "2017-11-29T08:00:00Z",
          "startTime": "2017-11-28T08:00:00Z"
        }
      },
      "viewableImpressions": {
        "value": "683"
      }
    },
    {
      "bids": {
        "value": "104288"
      },
      "bidsInAuction": {
        "value": "94016"
      },
      "billedImpressions": {
        "value": "99"
      },
      "impressionsWon": {
        "value": "125"
      },
      "measurableImpressions": {
        "value": "94"
      },
      "rowDimensions": {
        "timeInterval": {
          "endTime": "2017-11-30T08:00:00Z",
          "startTime": "2017-11-29T08:00:00Z"
        }
      },
      "viewableImpressions": {
        "value": "87"
      }
    },
    {
      "bids": {
        "value": "3999"
      },
      "bidsInAuction": {
        "value": "3631"
      },
      "billedImpressions": {
        "value": "618"
      },
      "impressionsWon": {
        "value": "1819"
      },
      "measurableImpressions": {
        "value": "604"
      },
      "rowDimensions": {
        "timeInterval": {
          "endTime": "2017-12-01T08:00:00Z",
          "startTime": "2017-11-30T08:00:00Z"
        }
      },
      "viewableImpressions": {
        "value": "369"
      }
    },
    {
      "bids": {
        "value": "15"
      },
      "bidsInAuction": {
        "value": "3"
      },
      "billedImpressions": {},
      "impressionsWon": {
        "value": "3"
      },
      "measurableImpressions": {},
      "rowDimensions": {
        "timeInterval": {
          "endTime": "2017-12-02T08:00:00Z",
          "startTime": "2017-12-01T08:00:00Z"
        }
      },
      "viewableImpressions": {}
    }
  ]
}

注意：任何設為 0 的欄位欄位都不會顯示在回應中。 上方空白的 billedImpressions 和 measurableImpressions 指標 表示這些值和變異數都設為 0。

警告：對於回應中的資料細目， 如果沒有任何非零指標，則納入資料列。舉例來說 已指定 timeSeriesGranularity，回應將不會包含任何對應列的資料列 在篩選器組合指定時間範圍內的 timeInterval，其中所有指標都是零。

列出帳戶層級出價指標

您可以傳送 HTTP GET，列出特定篩選器組合的帳戶層級出價指標 要求傳送至 bidders.accounts.filtersets.bidMetrics 資源 URI，且該 URI 具有 格式如下：

GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets/{filter set resource ID}/bidMetrics

敬上 要求

以下是列出帳戶層級出價指標的範例：

GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets/account-fs/bidMetrics

敬上 回覆

如果要求成功，伺服器會傳回 200 OK 狀態碼回應，內文則包含指定維度和精細程度指標的資料列。

{
  "bidMetricsRows": [{
      "bids": {
        "value": "1748"
      },
      "bidsInAuction": {
        "value": "1421"
      },
      "billedImpressions": {
        "value": "301"
      },
      "impressionsWon": {
        "value": "915"
      },
      "measurableImpressions": {
        "value": "298"
      },
      "rowDimensions": {
        "timeInterval": {
          "endTime": "2017-12-01T08:00:00Z",
          "startTime": "2017-11-30T08:00:00Z"
        }
      },
      "viewableImpressions": {
        "value": "172"
      }
    },
    {
      "bids": {
        "value": "6"
      },
      "bidsInAuction": {
        "value": "2"
      },
      "billedImpressions": {},
      "impressionsWon": {
        "value": "1"
      },
      "measurableImpressions": {},
      "rowDimensions": {
        "timeInterval": {
          "endTime": "2017-12-02T08:00:00Z",
          "startTime": "2017-12-01T08:00:00Z"
        }
      },
      "viewableImpressions": {}
    }
  ]
}

注意：任何設為 0 的欄位欄位都不會顯示在回應中。 上方空白的 billedImpressions 和 measurableImpressions 指標代表 這些值和變異數都設為 0

警告：如需查看回應中的資料細目，則回應不會包含 。舉例來說 已指定 timeSeriesGranularity，回應將不會包含任何對應列的資料列 在篩選器組合指定時間範圍內的 timeInterval，其中所有指標都是零。