即時出價疑難排解

本指南涵蓋即時出價疑難排解資源，讓您透過程式輔助方式存取即時出價廣告活動指標。這些指標也會透過 Authorized Buyers UI 中的即時出價明細工具顯示。包括 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 必須是出價方或由其管理的子帳戶 ID。如果您不知道哪些 Authorized Buyers 帳戶與您的 Google 帳戶相關聯，可以使用 accounts.list 方法尋找。

篩選器集

篩選器集代表可用的篩選選項，可在出價方或帳戶層級建立。可用於篩選 RTB 疑難排解資源的清單結果，這些資源會擷取即時出價廣告活動的指標。

擷取指標時套用的篩選器是指定篩選器組合中每個篩選器的交集。系統會將清單篩選器 (例如 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，可以是 URI 中指定的出價方帳戶可存取的任何 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"
}

列出篩選器集

list 方法只會傳回從呼叫呼叫的層級可存取的篩選器集。舉例來說，出價工具帳戶呼叫 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

回應

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

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

用於接收指標的所有即時出價疑難排解資源，都是以類似方式運作的單一方法，可以列出透過 filterSetName 路徑參數指定的篩選器集指標。指定的篩選器集會決定您在查詢指標時要套用哪些篩選器與設定。從出價方層級呼叫這些資源時，系統會傳回出價方帳戶和所有相關聯子帳戶的匯總指標，而來自帳戶層級的呼叫只會傳回個人帳戶的指標。

出價指標

bidMetrics 資源可用於擷取以出價次數計算的指標。舉例來說，您可以使用這個指標來判斷特定時間範圍內的出價總數，以及未從競價中篩除或贏得曝光的出價總數。就像用於收集指標的其他所有 RTB 疑難排解資源一樣，只有 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，格式如下：

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 的資料列，而所有指標均為零。