本頁面由 Cloud Translation API 翻譯而成。

提升效能

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

使用 gzip 壓縮

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

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

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

使用部分資源

另一種提高 API 呼叫成效的方式，就是只收發您有興趣的資料。這麼做可避免讓您的應用程式傳輸、剖析及儲存不需要的欄位，進而更有效地使用網路、CPU 以及記憶體等資源。

部分要求分為兩類：

部分回應：您可以在這類要求中，指定要在回應中加入哪些欄位 (使用 fields 要求參數)。
修補：透過這類更新要求，您可以只傳送想要變更的欄位 (使用 PATCH HTTP 動詞)。

接下來的章節將會詳細說明如何提交部分要求。

部分回應

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

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

請注意，fields 參數只會影響回應資料；不會影響您需要傳送的資料 (如果有的話)。如果要減少您在修改資源時傳送的資料量，請使用修補要求。

範例

以下範例顯示 fields 參數與某個通用 (虛構) 的「Demo」API 的搭配用法。

簡易要求：此 HTTP GET 要求會省略 fields 參數，並傳回完整的資源。

https://www.googleapis.com/demo/v1

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

{
  "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?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 參數語法摘要

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

使用以逗號分隔的清單來選取多個欄位。
使用 a/b 在 a 欄位的巢狀結構內選取 b 欄位；使用 a/b/c 在 b 的巢狀結構內選取 c 欄位。

例外狀況：如果 API 回應使用「data」包裝函式，也就是在 data 物件中建立看起來像 data: { ... } 的巢狀回應，請勿在 fields 規格中加入「data」。將 data 物件加入類似 data/a/b 的 fields 規格會造成錯誤。請改為只使用 fields 規格，例如 a/b。
透過在括號「( )」中放入運算式，使用子選擇器來要求一組指定的陣列或物件子欄位。
例如：fields=items(id,author/email) 只會傳回項目陣列中各個元素的項目 ID 以及作者的電子郵件地址。您也可以指定單一子欄位，其中 fields=items(id) 等於 fields=items/id。
必要時，在欄位選取項目中使用萬用字元。
例如：fields=items/pagemap/* 可選取網頁地圖中的所有物件。

使用 fields 參數的其他範例

以下範例包含 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?fields=kind,items(title,characteristics/length)

部分回應的樣式如下所示：

200 OK

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

附註：如果 API 支援用於資料分頁的查詢參數 (例如 maxResults 和 nextPageToken)，請使用這些參數將每個查詢的結果減少到方便管理的大小。否則，可能無法有效提升部分回應的效能。

修補 (部分更新)

修改資源時，您也可以避免傳送不必要的資料。如果是僅為要變更的特定欄位傳送更新資料，請使用 HTTP PATCH 動詞。相較於舊版的 GData 部分更新執行方式，在本文中，「修補」一詞的語意變得更加簡單。

下面的簡短範例將會示範如何使用修補功能，在進行小規模更新時將您需要傳送的資料量減到最小。

範例

此範例將會示範如何使用一段簡短的修補要求，只更新一個通用 (虛構) 的「Demo」API 資源標題。這項資源同時包含註解、一組特性、狀態以及許多其他欄位，但此要求只會傳送 title 欄位，因為這是唯一需要修改的欄位：

PATCH https://www.googleapis.com/demo/v1/324
Authorization: Bearer your_auth_token
Content-Type: application/json

{
  "title": "New title"
}

回應：

200 OK

{
  "title": "New title",
  "comment": "First comment.",
  "characteristics": {
    "length": "short",
    "accuracy": "high",
    "followers": ["Jo", "Will"],
  },
  "status": "active",
  ...
}

伺服器會傳回 200 OK 狀態碼，以及更新後資源的完整表示法。由於修補要求只包含 title 欄位，因此這個值是唯一與以往不同的值。

附註：如果您將部分回應 fields 參數與修補一起使用，就可以進一步提高更新要求的效率。修補請求只能減少要求的大小，而部分回應則能減少回應的大小。因此，要減少雙向傳送的資料量，請將修補要求與 fields 參數搭配使用。

修補要求的語意

修補要求的主體只包含您想要修改的資源欄位。您必須在指定欄位時加入任何其內含的父項物件，而這些欄位內含的父項物件將會連同部分回應一併傳回。修改後的資料會在傳送時合併至父物件的資料中 (如果有父物件存在的話)。

新增：若要新增一個還不存在的欄位，請指定新的欄位及其欄位值。
修改：若要變更現有欄位的值，請指定該欄位，並設為新的值。
刪除：如要刪除欄位，請指定欄位並設為 null。例如 "comment": null。您也可以將可變動的物件設為 null，以便將整個物件刪除。如果您使用的是 Java API 用戶端程式庫，請改用 Data.NULL_STRING；詳情請參閱 JSON null 的相關說明。

有關陣列的注意事項：含有陣列的修補要求會以您提供的陣列取代現有的陣列。您無法個別修改、新增或刪除陣列中的項目。

在「讀取 - 修改 - 寫入」週期中使用修補功能

建議您可以從擷取附帶想要修改的資料的部分回應著手，特別是當資源使用 ETag 時。這是因為您必須提供 If-Match HTTP 標頭目前的 ETag 值，才能成功更新資源。取得資料之後，您便可以接著修改需要變更的值，並將修改過的部分表示法連同修補要求一併傳回。以下是一個假設 Demo 資源使用 ETag 的範例：

GET https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: Bearer your_auth_token

以下是部分回應：

200 OK

{
  "etag": "ETagString"
  "title": "New title"
  "comment": "First comment.",
  "characteristics": {
    "length": "short",
    "level": "5",
    "followers": ["Jo", "Will"],
  }
}

以下修補要求是以該回應為建構依據。此要求同時使用 fields 參數來限制修補回應傳回的資料，如下所示：

PATCH https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: Bearer your_auth_token
Content-Type: application/json
If-Match: "ETagString"

{
  "etag": "ETagString"
  "title": "",                  /* Clear the value of the title by setting it to the empty string. */
  "comment": null,              /* Delete the comment by replacing its value with null. */
  "characteristics": {
    "length": "short",
    "level": "10",              /* Modify the level value. */
    "followers": ["Jo", "Liz"], /* Replace the followers array to delete Will and add Liz. */
    "accuracy": "high"          /* Add a new characteristic. */
  },
}

伺服器會在回應中提供 200 OK HTTP 狀態碼，以及更新後資源的部分表示法：

200 OK

{
  "etag": "newETagString"
  "title": "",                 /* Title is cleared; deleted comment field is missing. */
  "characteristics": {
    "length": "short",
    "level": "10",             /* Value is updated.*/
    "followers": ["Jo" "Liz"], /* New follower Liz is present; deleted Will is missing. */
    "accuracy": "high"         /* New characteristic is present. */
  }
}

直接建構修補要求

部分修補要求必須以您先前擷取的資料做為建構依據。舉例來說，如果您想要在陣列中新增一個項目，卻又不想失去任何現有的陣列元素，則您必須先取得現有的資料。同樣地，當 API 使用 ETag 時，您必須將先前的 ETag 值連同您的要求一起送出，才能成功更新資源。

附註：使用 ETag 時，您可以使用 "If-Match: *" HTTP 標頭強制通過修補。這麼一來，您就不需要在寫入之前先進行讀取。

然而，在其他情況下，您可以直接建構修補要求，而不需要先擷取現有的資料。舉例來說，您可以輕鬆建構一個用來更新欄位值或新增欄位的修補要求。範例如下：

PATCH https://www.googleapis.com/demo/v1/324?fields=comment,characteristics
Authorization: Bearer your_auth_token
Content-Type: application/json

{
  "comment": "A new comment",
  "characteristics": {
    "volume": "loud",
    "accuracy": null
  }
}

此要求會將註解欄位設為新的值，或是以新的值覆寫掉註解欄位現有的值。同樣地，如果有 volume 特性存在，則會覆寫掉該值；否則就會建立該特性。如果有設定好的精確度欄位存在，則會移除該欄位。

處理修補回應

API 會在處理完有效的修補要求之後，傳回 200 OK HTTP 回應代碼以及修改後資源的完整表示法。如果 API 有使用 ETag 的話，伺服器會在成功處理完修補要求時更新 ETag 的值，就像 PUT 一樣。

修補要求會傳回整個資源表示法，除非您使用 fields 參數來減少傳回的資料量。

如果修補要求產生的新資源狀態具有無效的語法或語意，則伺服器會傳回 400 Bad Request 或 422 Unprocessable Entity HTTP 狀態碼，且資源狀態維持不變。舉例來說，如果您嘗試刪除必填欄位的值，則伺服器會傳回錯誤。

當 PATCH HTTP 動詞未受支援時可使用的替代標示方法

如果您的防火牆禁止使用 HTTP PATCH 要求，請執行 HTTP POST 要求，並將替換標頭設定為 PATCH，如下所示：

POST https://www.googleapis.com/...
X-HTTP-Method-Override: PATCH
...

修補和更新之間的差異

就實務層面而言，為使用了 HTTP PUT 動詞的更新要求傳送資料時，您只需要傳送必填或選填欄位；如果您傳送了由伺服器設定的欄位值，這些值將會遭到忽略。雖然這看起來像是執行部分更新的另一種方法，但此方法有一些限制存在。使用 HTTP PUT 動詞進行更新時，如果您沒有提供必要參數，則要求將會失敗；此外，如果您沒有提供選用參數，則要求將會清除先前設定的資料。

這也是在此情況下使用修補更加安全的原因。您只需要為您想要變更的欄位提供資料，而您省略的欄位將不會被清除。此規則唯一的例外便是重複元素或陣列：如果您全數省略，它們將會保持原狀；如果您提供了任何重複元素或陣列，則整組元素或陣列都會替換成您提供的組合。

批次要求

本文說明如何批次處理 API 呼叫，以減少 HTTP 連線數量而非客戶需要做的事

本文專門說明如何透過傳送 HTTP 要求來提交批次要求。如果您是使用 Google 用戶端程式庫提交批次要求，請參閱用戶端程式庫的說明文件。

總覽

用戶端的每個 HTTP 連線都會造成一定程度的負擔。Google Drive API 支援批次作業，可讓用戶端在單一 HTTP 要求中加入數個 API 呼叫。

以下是您可能想要使用批次作業的狀況範例：

擷取大量檔案的中繼資料。
大量更新中繼資料或屬性。
變更大量檔案的權限，例如新增使用者或群組。
首次同步處理或長時間離線後，同步處理本機客戶資料。

在任一案例中，都不需要個別傳送每一個呼叫，只需將這些呼叫分組後組成單一 HTTP 要求。所有內部要求都必須前往相同的 Google API。

單一批次要求最多可包含 100 個呼叫。如果您發出的呼叫數量超過這個上限，請使用多個批次要求。

注意：Google Drive API 批次系統使用的語法與 OData 批次處理系統相同，但語意不同。

其他限制包括：

如果批次要求含有超過 100 個呼叫，可能就會發生錯誤。
每個內部要求的網址長度限制為 8,000 個字元。
Google 雲端硬碟不支援針對媒體的批次作業，無論是上傳、下載或匯出檔案都不適用。

批次詳細資料

批次要求是由多個 API 呼叫合併成一個 HTTP 要求，系統會將這個要求傳送至 API 探索文件中指定的 batchPath。預設路徑為 /batch/api_name/api_version。本節將詳細說明批次語法。後面還有範例。

注意：系統會將一組批次處理的 n 要求計入用量限制，並計為 n 要求，而非單一要求。在這個處理之前，批次要求會拆分成一組要求。

批次要求的格式

批次要求是單一標準 HTTP 要求，內含多個使用 multipart/mixed 內容類型的 Google Drive API 呼叫。在主要 HTTP 要求中，每個分部都含有一個巢狀的 HTTP 要求。

每個部分都以自己的 Content-Type: application/http HTTP 標頭開始。也可以有選用的 Content-ID 標頭。但分部標頭只是用來標示部分開頭。內容與巢狀請求無關伺服器將批次要求解除包裝成個別要求後，系統會忽略該部分標頭。

每個部分的主體都是完整的 HTTP 要求，具有自己的動詞、網址、標頭和內文。HTTP 要求只能包含 URL 的路徑部分；批次要求禁止納入完整的 URL。

外部批次要求的 HTTP 標頭會套用於批次中的每項要求，但 Content- 標頭 (例如 Content-Type) 除外。如果您在外部要求和個別呼叫中均指定所提供的 HTTP 標頭，則個別呼叫標頭的值會覆寫外部批次要求標頭的值。個別呼叫的標頭只會套用於該呼叫。

例如，如果您提供 Authorization 標頭用於特定呼叫，則該標頭只會套用於該呼叫。如果您提供 Authorization 標頭用於外部要求，則除非個別呼叫以自己的 Authorization 標頭覆寫所提供的標頭，否則所提供的 Authorization 標頭會套用於所有個別呼叫。

當伺服器收到批次要求時，即會將外部要求的查詢參數和標頭 (在適用情況下) 套用至每一個分部，然後將每個分部視為不同的 HTTP 要求。

回應批次要求

伺服器回應是含有 multipart/mixed 內容類型的單一標準 HTTP 回應。每個部分都是回應批次要求中其中一個要求的回應，回應順序與要求順序相同。

就像要求中的分部一樣，每個回應分部都含有完整的 HTTP 回應，包括狀態碼、標頭和內文；如同要求的各個部分，每個回應部分的前面都會加上 Content-Type 標頭，用來標示該部分的開頭。

如果要求的指定部分有 Content-ID 標頭，則回應的對應部分會有相符的 Content-ID 標頭，且原始值在前面加上 response- 字串，如以下範例所示。

注意：伺服器可能會按任意順序執行呼叫。不要期望呼叫會按您的指定順序執行。如果您想要確保兩個呼叫依指定順序執行，就不能以單一要求傳送它們，而要先傳送第一個呼叫，然後等到第一個呼叫的回應後才能傳送第二個呼叫。

範例

以下範例顯示如何使用 Google Drive API 進行批次處理。

批次要求範例

POST https://www.googleapis.com/batch/drive/v3 Accept-Encoding: gzip User-Agent: Google-HTTP-Java-Client/1.20.0 (gzip) Content-Type: multipart/mixed; boundary=END_OF_PART Content-Length: 963

--END_OF_PART Content-Length: 337 Content-Type: application/http content-id: 1 content-transfer-encoding: binary

POST https://www.googleapis.com/drive/v3/files/fileId/permissions?fields=id Authorization: Bearer authorization_token Content-Length: 70 Content-Type: application/json; charset=UTF-8

{ "emailAddress":"example@appsrocks.com", "role":"writer", "type":"user" } --END_OF_PART Content-Length: 353 Content-Type: application/http content-id: 2 content-transfer-encoding: binary

POST https://www.googleapis.com/drive/v3/files/fileId/permissions?fields=id&sendNotificationEmail=false Authorization: Bearer authorization_token Content-Length: 58 Content-Type: application/json; charset=UTF-8

{ "domain":"appsrocks.com", "role":"reader", "type":"domain" } --END_OF_PART--

批次回應範例

這是前一節中範例要求的回應。

HTTP/1.1 200 OK Alt-Svc: quic=":443"; p="1"; ma=604800 Server: GSE Alternate-Protocol: 443:quic,p=1 X-Frame-Options: SAMEORIGIN Content-Encoding: gzip X-XSS-Protection: 1; mode=block Content-Type: multipart/mixed; boundary=batch_6VIxXCQbJoQ_AATxy_GgFUk Transfer-Encoding: chunked X-Content-Type-Options: nosniff Date: Fri, 13 Nov 2015 19:28:59 GMT Cache-Control: private, max-age=0 Vary: X-Origin Vary: Origin Expires: Fri, 13 Nov 2015 19:28:59 GMT

--batch_6VIxXCQbJoQ_AATxy_GgFUk Content-Type: application/http Content-ID: response-1

HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Date: Fri, 13 Nov 2015 19:28:59 GMT Expires: Fri, 13 Nov 2015 19:28:59 GMT Cache-Control: private, max-age=0 Content-Length: 35

{ "id": "12218244892818058021i" }

--batch_6VIxXCQbJoQ_AATxy_GgFUk Content-Type: application/http Content-ID: response-2

HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Date: Fri, 13 Nov 2015 19:28:59 GMT Expires: Fri, 13 Nov 2015 19:28:59 GMT Cache-Control: private, max-age=0 Content-Length: 35

{ "id": "04109509152946699072k" }

--batch_6VIxXCQbJoQ_AATxy_GgFUk--

傳回要求中的特定欄位

根據預設，伺服器會傳回一組預設資源欄位，使用的方法。舉例來說， files.list 方法可能只會傳回 id、name和mimeType。這些欄位可能不是需求。如需傳回其他欄位，請參閱傳回檔案的特定欄位。