提升效能

本文件將說明幾個技巧，有助您改善應用程式在某些情況下，也會使用來自其他已實作 API 的範例說明提案內容然而，相同的概念多媒體和Video 360 API。

使用部分資源

另一個提高 API 呼叫效能的方法，就是只在要求時特定部分的資料這樣一來避免傳輸、剖析及儲存不需要的欄位，以使用更有效率地管理網路、CPU 和記憶體等資源

部分回應

根據預設，伺服器會在來處理要求如要改善效能，您可以要求伺服器只傳回您真正需要的欄位，並改為取得部分回應。

如要請求部分回應，請使用 fields 要求參數來指定您要傳回的欄位。任何請求都可以使用這個參數。

範例

以下範例顯示如何使用 fields 參數搭配多媒體和Video 360 API。

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

GET https://displayvideo.googleapis.com/v3/advertisers?partnerId=1

完整資源回應：完整資源資料包含下列內容：許多欄位，以及為求簡潔起見，我們省略了許多其他欄位。

200 OK

{
 "advertisers": [
  {
   "name": "advertisers/1",
   "advertiserId": "1",
   "partnerId": "1",
   "displayName": "Example Advertiser 1",
   "entityStatus": "ENTITY_STATUS_ACTIVE",
   "updateTime": "2019-01-01T00:00:00.000000Z",
   "generalConfig": {
    "domainUrl": "http://example.com",
    "timeZone": "America/New_York",
    "currencyCode": "USD",
    "address": {
    }
   },
   "adServerConfig": {
    "thirdPartyOnlyConfig": {
    }
   },
   "creativeConfig": {
   },
   "dataAccessConfig": {
    "sdfConfig": {
     "sdfConfig": {
      "version": "VERSION_3_1"
     }
    }
   },
   "integrationDetails": {
   }
  },
  {
   "name": "advertisers/2",
   "advertiserId": "2",
   "partnerId": "1",
   "displayName": "Example Advertiser 2",
   "entityStatus": "ENTITY_STATUS_ACTIVE",
   "updateTime": "2019-01-01T00:00:00.000000Z",
   "generalConfig": {
    "domainUrl": "http://example.com",
    "timeZone": "America/New_York",
    "currencyCode": "USD",
    "address": {
    }
   },
   "adServerConfig": {
    "thirdPartyOnlyConfig": {
    }
   },
   "creativeConfig": {
   },
   "dataAccessConfig": {
    "sdfConfig": {
     "sdfConfig": {
      "version": "VERSION_3_1"
     }
    }
   },
   "integrationDetails": {
   }
  },
  ...
 ],
 "nextPageToken": "..."
}

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

GET https://displayvideo.googleapis.com/v3/advertisers?partnerId=1&fields=advertisers(advertiserId,partnerId,displayName)

部分回應：為了回應上方的要求，伺服器會傳回回應包含簡化的廣告客戶陣列，其中只包含每個廣告主的廣告主 ID、顯示名稱及合作夥伴 ID 屬性 (如果。

200 OK

{
 "advertisers": [
  {
   "advertiserId": "1",
   "partnerId": "1",
   "displayName": "Example Advertiser 1"
  },
  {
   "advertiserId": "2",
   "partnerId": "1",
   "displayName": "Example Advertiser 2"
  },
  ...
 ]
}

請注意，回應為 JSON 物件，且只包含所選欄位和物件包圍的父項物件

以下將詳細介紹如何設定 fields 參數的格式，後面接著詳細瞭解回應中傳回的內容

欄位參數語法摘要

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

使用以逗號分隔的清單來選取多個欄位。
使用 a/b 在 a 欄位的巢狀結構中選取 b 欄位；使用「a/b/c」以選取 b 中的巢狀欄位 c 欄位。
使用子選擇器來請求一組特定的陣列子欄位，或物件。( )

例如：fields=advertisers(advertiserId,generalConfig/domainUrl) 只會傳回廣告客戶陣列。您也可以指定單一子欄位，其中 fields=advertisers(advertiserId) 相當於 fields=advertisers/advertiserId。

使用 fields 參數的其他範例

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

找出您要傳回的欄位，或「選取欄位」。

fields 要求參數值是以逗號分隔的欄位清單，每個欄位都會根據回應的根層級指定。因此，如果您正在執行 list 作業，回應是集合，而通常包含資源陣列如果您正在執行作業會傳回單一資源，欄位會根據該資源資源。若所選欄位是陣列或陣列的一部分，伺服器會傳回陣列中所有元素選取的部分。

以下提供幾個集合層級的範例：

範例	效果
`advertisers`	傳回 `advertisers` 陣列，包含每個元素中的所有欄位沒有其他欄位。
`advertisers,nextPageToken`	同時傳回 `nextPageToken` 欄位和 `advertisers` 陣列。
`advertisers/advertiserId`	只傳回 `advertiserId` 包含所有元素的 `advertisers` 陣列。只要巢狀欄位則回應會包含物件內所含的父項物件父項欄位不包含否則任何子欄位也已選取。
`advertisers/generalConfig/domainUrl`	傳回 `domainUrl` 欄位定義 `generalConfig` 物件的參數資源本身位於 `advertisers` 陣列。

以下提供幾個資源層級的範例：

範例	效果
`advertiserId`	傳回 `advertiserId` 欄位所要求資源的存取層級
`generalConfig/domainUrl`	傳回 `domainUrl` 欄位針對 `generalConfig` 物件在要求的資源中。

使用「子選取項目」只請求指定欄位部分。

根據預設，如果您的要求指定特定欄位，伺服器會傳回完整的物件或陣列元素您可以指定只包含特定子欄位方法是使用「( )」子選取項目語法，如下方範例所示。

範例	效果
`advertisers(advertiserId,generalConfig/domainUrl)`	僅傳回值 `advertiserId` 和 GeneralConfig `domainUrl`：每個元素的 `advertisers` 陣列。

處理部分回應

伺服器處理包含 fields 查詢的有效要求之後參數，它會傳回 HTTP 200 OK 狀態碼，以及所請求資料。如果 fields 查詢參數發生錯誤或無效，伺服器會傳回 HTTP 400 Bad Request 狀態碼，且發生錯誤指出選取欄位有誤的訊息 (例如， "Invalid field selection a/b")。