成效改善訣竅

本文說明提升應用程式成效的幾個訣竅。在某些情況下,我們會使用其他 API 或通用 API 的範例來說明這些技巧背後的概念。不過,同樣的概念也適用於 AdSense Host API。

內容

  1. 使用 gzip
  2. 使用部分資源
    1. 部分回應

使用 gzip

要減少每個請求占用的頻寬,最簡單的方法就是使用 gzip 壓縮檔。雖然此方法需要額外的 CPU 時間解壓縮,但相對可省下可觀的網路成本。

如果要接收以 gzip 編碼的回應,您必須執行下列兩項操作:設定 Accept-Encoding 標頭,並修改您的使用者代理程式來加入字串 gzip。以下是一個啟用 gzip 壓縮的正確 HTTP 標頭格式範例:

Accept-Encoding: gzip
User-Agent: my program (gzip)

使用部分資源

另一種提高 API 呼叫成效的方式,就是只請求您想要的部分資料。如此可避免應用程式傳輸、剖析及儲存不需要的欄位,進而更有效地使用網路、CPU 以及記憶體等資源。

部分回應

根據預設,伺服器會在處理請求後傳回完整的資源表示法。為改善成效,您可以要求伺服器只傳送您真正需要的欄位,並改為取得部分回應

如果要請求部分回應,請使用 fields 請求參數來指定您想要傳回的欄位。您可以將此參數搭配任何會傳回回應資料的請求使用。

範例

以下舉例說明如何將 fields 參數搭配一般 (虛構)「示範」API 使用。

簡易請求:此 HTTP GET 請求會省略 fields 參數,並傳回完整的資源。

https://www.googleapis.com/demo/v1?key=YOUR-API-KEY

完整資源回應:完整資源資料包括下列欄位 (為節省篇幅,此處省略許多其他欄位)。

{
  "kind": "demo",
  ...
  "items": [
  {
    "title": "First title",
    "comment": "First comment.",
    "characteristics": {
      "length": "short",
      "accuracy": "high",
      "followers": ["Jo", "Will"],
    },
    "status": "active",
    ...
  },
  {
    "title": "Second title",
    "comment": "Second comment.",
    "characteristics": {
      "length": "long",
      "accuracy": "medium"
      "followers": [ ],
    },
    "status": "pending",
    ...
  },
  ...
  ]
}

請求部分回應:相同資源的下列請求使用 fields 參數,大幅減少傳回的資料量。

https://www.googleapis.com/demo/v1?key=YOUR-API-KEY&fields=kind,items(title,characteristics/length)

部分回應:在上方的請求回應中,伺服器傳回的回應只包含類型資訊,以及經過簡化的項目陣列 (只包含個別項目的 HTML 標題和長度特性資訊)。

200 OK

{
  "kind": "demo",
  "items": [
  {
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  },
  {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]

請注意,回應是一個 JSON 物件,且此物件只包含選定的欄位及其歸屬的父物件。

以下將詳述如何設定 fields 參數的格式,接著則會進一步說明回應中實際傳回的內容。

欄位參數語法摘要

fields 請求參數值的格式約略以 XPath 語法為基礎。支援的語法簡述如下,其他範例如下節所示。

  • 使用以逗號分隔的清單來選取多個欄位。
  • 使用 a/b 選取巢狀配置在欄位 a 中的欄位 b;使用 a/b/c 選取巢狀配置在 b 中的欄位 c

    例外情況:當 API 回應使用「data」包裝函式時 (也就是將回應巢狀配置在 data 物件中,看起來像是 data:{ ... },請勿在 fields 規格中加入「data」。將資料物件加入類似 data/a/b 的欄位規格會造成錯誤。請改為只使用 fields 規格,例如 a/b

  • 透過在括號「( )」中放入運算式,使用子選擇器來請求一組指定的陣列或物件子欄位。

    範例:fields=items(id,author/email) 只會傳回項目陣列中各個元素的項目編號,以及作者的電子郵件地址。您也可以指定一個子欄位,其中 fields=items(id) 等於 fields=items/id

  • 必要時,在欄位選取項目中使用萬用字元。

    範例:fields=items/pagemap/* 可選擇網頁地圖中的所有物件。

使用欄位參數的其他範例

以下範例包含 fields 參數值會如何影響回應的說明。

注意事項:和所有查詢參數值一樣,fields 參數值也必須經過網址編碼。為方便閱讀,本文中的範例會省略編碼。

找出您要傳回的欄位,或選取欄位
fields 請求參數值是以逗號分隔的欄位清單,每個欄位是根據回應的根來指定。因此,如果您執行的是清單作業,回應會是一個集合,其中通常包含資源陣列。如果您執行的作業傳回單一資源,欄位會根據該資源來指定。如果您選取的欄位是一個陣列 (或陣列的一部分),則伺服器會傳回該陣列中所有元素的選定部分。

以下提供幾個集合層級的範例:
範例 作用
items 傳回項目陣列中的所有元素,包括每個元素中的所有欄位,但不包含其他欄位。
etag,items 同時傳回 etag 欄位和項目陣列中的所有元素。
items/title 只傳回項目陣列中所有元素的 title 欄位。

每當傳回巢狀欄位時,回應會包含其所含父物件。父欄位不會包含任何其他的子欄位 (除非已同時明確地選擇這些欄位)。
context/facets/label 只傳回 facets 陣列所有成員的 label 欄位,其本身巢狀配置在 context 物件底下。
items/pagemap/*/title 針對項目陣列中的每個元素,只傳回屬於 pagemap 子項之所有物件的 title 欄位 (如果有的話)。

以下提供幾個資源層級的範例:
範例 作用
title 會傳回所請求資源的 title 欄位。
author/uri 會傳回所請求資源中 author 物件的 uri 子欄位。
links/*/href
會傳回 links 子項所有物件的 href 欄位。
使用「子選取項目」只請求指定欄位部分。
根據預設,如果您的請求指定特定的欄位,伺服器會傳回整個物件或陣列元素。您可以指定只包含某些子欄位的回應。如果要這麼做,請使用「( )」子選取項目語法,如下方範例所示。
範例 作用
items(title,author/uri) 只傳回項目陣列中每個元素項目的 title 以及作者的 uri 值。

處理部分回應

伺服器處理包含 fields 查詢參數的有效請求後,會傳送回一個 HTTP 200 OK 狀態碼,以及所請求的資料。如果 fields 查詢參數發生錯誤或無效,伺服器會傳回 HTTP 400 Bad Request 狀態碼和錯誤訊息,指出使用者選擇欄位時發生的錯誤 (例如 "Invalid field selection a/b")。

以下是上方簡介一節中的部分回應範例。此請求使用 fields 參數來指定要傳回的欄位。

https://www.googleapis.com/demo/v1?key=YOUR-API-KEY&fields=kind,items(title,characteristics/length)

部分回應看起來會像這樣:

200 OK

{
  "kind": "demo",
  "items": [
  {
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  },
  {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]

注意事項:當 API 支援資料分頁查詢參數 (例如 maxResultsnextPageToken) 時,請使用這些參數將每筆查詢的結果減少到方便管理的大小。否則,部分回應的成效可能無法增加。

傳送您對下列選項的寶貴意見...

這個網頁
AdSense Host API
AdSense Host API