讀取及寫入開發人員中繼資料

開發人員中繼資料功能可讓您將中繼資料與試算表中的各種實體和位置建立關聯。接著，您可以查詢這項中繼資料，並使用該中繼資料來尋找相關聯的物件。

你可以將中繼資料與資料列、資料欄、試算表或試算表建立關聯。

開發人員中繼資料可讓您執行以下作業：

• 將任意資料與試算表中的各種實體和地點建立關聯 - 舉例來說，將 totals 與欄 D 建立關聯，或將 responseId = 1234 與第 7 列建立關聯。

• 找出與特定中繼資料鍵或屬性相關聯的所有位置和資料 - 舉例來說，當指定與資料欄 D 相關聯的鍵 totals 或指定 responseId 時，傳回所有含有 responseId 中繼資料及其相關中繼資料值的資料列。

• 尋找與特定實體或位置相關聯的所有資料 - 例如，指定 D 欄，會傳回與該位置相關的所有中繼資料。

• 透過指定相關聯的中繼資料來擷取特定位置中的值：例如，假設 totals 會傳回相關資料欄或資料列所含值的表示法，或是指定 summary 傳回相關聯試算表資源的表示法。

• 指定相關聯的中繼資料，藉此更新位置中的值：舉例來說，您可以指定中繼資料 ID 來更新值，而不要透過 A1 標記法更新資料列中的值。

讀取及寫入中繼資料

spreadsheets.developerMetadata 資源可讓您存取與試算表中的地點或物件相關聯的開發人員中繼資料。

關於開發人員中繼資料

本節說明使用試算表 API 時，開發人員中繼資料的幾個重要方面。

以中繼資料做為標記

開發人員中繼資料的其中一種用途是標記，使用僅以金鑰和位置命名試算表中的地點。舉例來說，您可以將 headerRow 與特定資料列或 totals 建立關聯，連結至工作表中的特定資料欄。您可以使用標記，以語意方式將試算表的某些部分繫結到第三方工具或資料庫中的欄位，因此對試算表進行的變更並不會破壞應用程式。

以中繼資料做為屬性

透過指定鍵、位置和值建立的中繼資料，可做為在工作表中與該位置相關聯的鍵/值組合。舉例來說，您可以建立下列項目：

• 含有一列的formResponseId = resp123
• lastUpdated = 1477369882 與資料欄。

這可讓您儲存及存取與試算表中特定區域或資料相關聯的自訂命名屬性。

專案與文件可見中繼資料

為避免某個開發人員專案幹擾其他使用者的中繼資料，系統提供 2 項中繼資料 visibility 設定：project 和 document。如要使用試算表 API，只有建立專案中繼資料的開發人員專案才能查看及存取專案中繼資料。任何具有該文件存取權的開發人員專案都可以存取文件中繼資料。

未明確指定瀏覽權限的查詢，會傳回符合文件中繼資料，且與提出要求開發人員專案相符的專案中繼資料。

請勿使用專案可見的開發人員中繼資料做為安全機製或儲存密鑰。使用者如果具備文件檢視權限，就可能會看到中繼資料。

唯一性

中繼資料鍵可以重複，但 metadataId 必須不同。如果您建立中繼資料且不指定 ID 欄位，API 會指派一個。此 ID 可用來識別中繼資料，鍵和其他屬性則可用於識別中繼資料組合。

雖然建立中繼資料時可以自行指定「metadataId」，但我們建議您允許試算表服務為您指派「metadataId」。

建立中繼資料

如要建立中繼資料，請使用 batchUpdate 方法，並提供包含 metadataKey、location 和 visibility 的 createDeveloperMetadataRequest。您可以視需要指定 metadataValue 或明確的 metadataId。

如果指定的 ID 已在使用中，要求就會失敗。如未提供 ID，API 會指派一個 ID。

顯示範例

在此範例中，我們在要求中提供鍵、值和一個資料列。回應會傳回以下開發人員中繼資料值，以及已指派的中繼資料 ID。

要求

{
  "requests": [
    {
      "createDeveloperMetadata": {
        "developerMetadata": {
          "location": {
            "dimensionRange": {
              "sheetId": sheetId,
              "dimension": "ROWS",
              "startIndex": 6,
              "endIndex": 7
            }
          },
          "visibility": "DOCUMENT",
          "metadataKey": "Sales",
          "metadataValue": "2022"
        }
      }
    }
  ]
}

回應

{
  "spreadsheetId": spreadsheetId,
  "replies": [
    {
      "createDeveloperMetadata": {
        "developerMetadata": {
          "metadataId": metadataId,
          "metadataKey": "Sales",
          "metadataValue": "2022",
          "location": {
            "locationType": "ROW",
            "dimensionRange": {
              "sheetId": sheetId,
              "dimension": "ROWS",
              "startIndex": 6,
              "endIndex": 7
            }
          },
          "visibility": "DOCUMENT"
        }
      }
    }
  ]
}

讀取單一中繼資料項目

如要擷取單一不同的開發人員中繼資料，請使用 spreadsheets.developerMetadata.get 方法，指定包含中繼資料的 spreadsheetId，以及開發人員中繼資料的專屬 metadataId。

顯示範例

要求

在這個範例中，我們在要求中提供試算表 ID 和中繼資料 ID。回應會傳回中繼資料 ID 的開發人員中繼資料值。

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/developerMetadata/metadataId

回應

{
  "metadataId": metadataId,
  "metadataKey": "Sales",
  "metadataValue": "2022",
  "location": {
    "locationType": "ROW",
    "dimensionRange": {
      "sheetId": sheetId,
      "dimension": "ROWS",
      "startIndex": 6,
      "endIndex": 7
    }
  },
  "visibility": "DOCUMENT"
}

讀取多個中繼資料項目

如要擷取開發人員中繼資料的多個項目，請使用 spreadsheets.developerMetadata.search 方法。您必須指定與任何屬性組合 (例如鍵、值、位置或瀏覽權限) 中任何現有中繼資料相符的 DataFilter。

顯示範例

在本例中，我們在要求中提供多個中繼資料 ID。回應會傳回每個中繼資料 ID 的開發人員中繼資料值。

要求

{
  "dataFilters": [
    {
      "developerMetadataLookup": {
        "metadataId": metadataId
      }
    },
    {
      "developerMetadataLookup": {
        "metadataId": metadataId
      }
    }
  ]
}

回應

{
  "matchedDeveloperMetadata": [
    {
      "developerMetadata": {
        "metadataId": metadataId,
        "metadataKey": "Revenue",
        "metadataValue": "2022",
        "location": {
          "locationType": "SHEET",
          "sheetId": sheetId
        },
        "visibility": "DOCUMENT"
      },
      "dataFilters": [
        {
          "developerMetadataLookup": {
            "metadataId": metadataId
          }
        }
      ]
    },
    {
      "developerMetadata": {
        "metadataId": metadataId,
        "metadataKey": "Sales",
        "metadataValue": "2022",
        "location": {
          "locationType": "SHEET",
          "sheetId": sheetId
        },
        "visibility": "DOCUMENT"
      },
      "dataFilters": [
        {
          "developerMetadataLookup": {
            "metadataId": metadataId
          }
        }
      ]
    }
  ]
}

更新中繼資料

如要更新開發人員中繼資料，請使用 spreadsheets.batchUpdate 方法，並提供 UpdateDeveloperMetadataRequest。您需要指定 DataFilter 來指定要更新的中繼資料、包含新值的 DeveloperMetadata 物件，以及說明要更新欄位的欄位遮罩。

顯示範例

在本例中，我們在要求中提供中繼資料 ID、工作表 ID 和新的中繼資料鍵。回應會傳回這些開發人員中繼資料值，以及更新後的中繼資料鍵。

要求

{
  "requests": [
    {
      "updateDeveloperMetadata": {
        "dataFilters": [
          {
            "developerMetadataLookup": {
              "metadataId": metadataId
            }
          }
        ],
        "developerMetadata": {
          "location": {
            "sheetId": sheetId
          },
          "metadataKey": "SalesUpdated"
        },
        "fields": "location,metadataKey"
      }
    }
  ]
}

回應

{
  "spreadsheetId": spreadsheetId,
  "replies": [
    {
      "updateDeveloperMetadata": {
        "developerMetadata": [
          {
            "metadataId": metadataId,
            "metadataKey": "SalesUpdated",
            "metadataValue": "2022",
            "location": {
              "locationType": "SHEET",
              "sheetId": sheetId
            },
            "visibility": "DOCUMENT"
          }
        ]
      }
    }
  ]
}

刪除中繼資料

如要刪除開發人員中繼資料，請使用 batchUpdate 方法，並提供 DeleteDeveloperMetadataRequest。您需要指定 DataFilter，才能選取要刪除的中繼資料。

顯示範例

在這個範例中，我們會在要求中提供中繼資料 ID。回應會傳回中繼資料 ID 的開發人員中繼資料值。

如要確認開發人員中繼資料是否已移除，請使用 spreadsheets.developerMetadata.get 方法指定已刪除的中繼資料 ID。您應該會收到 404: Not Found HTTP 狀態碼回應，以及「找不到 ID 為 metadataId 的開發人員中繼資料」的訊息。

要求

{
  "requests": [
    {
      "deleteDeveloperMetadata": {
        "dataFilter": {
          "developerMetadataLookup": {
            "metadataId": metadataId
          }
        }
      }
    }
  ]
}

回應

{
  "spreadsheetId": spreadsheetId,
  "replies": [
    {
      "deleteDeveloperMetadata": {
        "deletedDeveloperMetadata": [
          {
            "metadataId": metadataId,
            "metadataKey": "SalesUpdated",
            "metadataValue": "2022",
            "location": {
              "locationType": "SHEET",
              "sheetId": sheetId
            },
            "visibility": "DOCUMENT"
          }
        ]
      }
    }
  ]
}

讀取及寫入與中繼資料相關聯的值

您也可以指定相關聯的開發人員中繼資料和您要更新的值，擷取及更新資料列和資料欄中的儲存格值。方法是使用以下適當的方法搭配比對的 DataFilter。

依中繼資料取得儲存格值

如要透過中繼資料取得儲存格值，請使用 spreadsheets.values.batchGetByDataFilter 方法。您必須指定試算表 ID，以及一或多個與中繼資料相符的資料篩選器。

顯示範例

在這個範例中，我們會在要求中提供中繼資料 ID。回應會傳回中繼資料 ID 的資料列儲存格值 (型號、每月銷售額)。

要求

{
  "dataFilters": [
    {
      "developerMetadataLookup": {
        "metadataId": metadataId
      }
    }
  ],
  "majorDimension": "ROWS"
}

回應

{
  "spreadsheetId": spreadsheetId,
  "valueRanges": [
    {
      "valueRange": {
        "range": "Sheet7!A7:Z7",
        "majorDimension": "ROWS",
        "values": [
          [
            "W-24",
            "74"
          ]
        ]
      },
      "dataFilters": [
        {
          "developerMetadataLookup": {
            "metadataId": metadataId
          }
        }
      ]
    }
  ]
}

依中繼資料取得試算表

擷取試算表時，您可以使用 spreadsheets.getByDataFilter 方法傳回部分資料。您必須指定試算表 ID，以及一或多個與中繼資料相符的資料篩選器。

這項要求會做為一般的「試算表 GET」要求運作，但與指定資料篩選器相符的中繼資料清單會決定要傳回哪些工作表、格線資料，以及其他含有中繼資料的物件資源。如果將 includeGridData 設為 true，試算表也會傳回與指定格線範圍相交的格線資料。

顯示範例

在本例中，我們要在要求中提供中繼資料 ID，並將 includeGridData 設為 false。回應會同時傳回試算表和工作表屬性。

要求

{
  "dataFilters": [
    {
      "developerMetadataLookup": {
        "metadataId": metadataId
      }
    }
  ],
  "includeGridData": false
}

回應

{
  "spreadsheetId": spreadsheetId,
  "properties": {
    "title": "Sales Sheet",
    "locale": "en_US",
    "autoRecalc": "ON_CHANGE",
    "timeZone": "America/Los_Angeles",
    "defaultFormat": {
      "backgroundColor": {
        "red": 1,
        "green": 1,
        "blue": 1
      },
      "padding": {
        "top": 2,
        "right": 3,
        "bottom": 2,
        "left": 3
      },
      "verticalAlignment": "BOTTOM",
      "wrapStrategy": "OVERFLOW_CELL",
      "textFormat": {
        "foregroundColor": {},
        "fontFamily": "arial,sans,sans-serif",
        "fontSize": 10,
        "bold": false,
        "italic": false,
        "strikethrough": false,
        "underline": false,
        "foregroundColorStyle": {
          "rgbColor": {}
        }
      },
      "backgroundColorStyle": {
        "rgbColor": {
          "red": 1,
          "green": 1,
          "blue": 1
        }
      }
    },
    "spreadsheetTheme": {
      "primaryFontFamily": "Arial",
      "themeColors": [
        {
          "colorType": "TEXT",
          "color": {
            "rgbColor": {}
          }
        },
        {
          "colorType": "BACKGROUND",
          "color": {
            "rgbColor": {
              "red": 1,
              "green": 1,
              "blue": 1
            }
          }
        },
        {
          "colorType": "ACCENT1",
          "color": {
            "rgbColor": {
              "red": 0.25882354,
              "green": 0.52156866,
              "blue": 0.95686275
            }
          }
        },
        {
          "colorType": "ACCENT2",
          "color": {
            "rgbColor": {
              "red": 0.91764706,
              "green": 0.2627451,
              "blue": 0.20784314
            }
          }
        },
        {
          "colorType": "ACCENT3",
          "color": {
            "rgbColor": {
              "red": 0.9843137,
              "green": 0.7372549,
              "blue": 0.015686275
            }
          }
        },
        {
          "colorType": "ACCENT4",
          "color": {
            "rgbColor": {
              "red": 0.20392157,
              "green": 0.65882355,
              "blue": 0.3254902
            }
          }
        },
        {
          "colorType": "ACCENT5",
          "color": {
            "rgbColor": {
              "red": 1,
              "green": 0.42745098,
              "blue": 0.003921569
            }
          }
        },
        {
          "colorType": "ACCENT6",
          "color": {
            "rgbColor": {
              "red": 0.27450982,
              "green": 0.7411765,
              "blue": 0.7764706
            }
          }
        },
        {
          "colorType": "LINK",
          "color": {
            "rgbColor": {
              "red": 0.06666667,
              "green": 0.33333334,
              "blue": 0.8
            }
          }
        }
      ]
    }
  },
  "sheets": [
    {
      "properties": {
        "sheetId": sheetId,
        "title": "Sheet7",
        "index": 7,
        "sheetType": "GRID",
        "gridProperties": {
          "rowCount": 1000,
          "columnCount": 26
        }
      }
    }
  ],
  "spreadsheetUrl": spreadsheetUrl
}

依中繼資料更新值

如要更新符合特定中繼資料的儲存格值，請使用 spreadsheets.values.batchUpdateByDataFilter 方法。您必須指定試算表 ID、valueInputOption 和一或多個與中繼資料相符的 DataFilterValueRange。

顯示範例

在此範例中，我們在要求中提供中繼資料 ID 和更新的資料列值。回應會同時傳回更新後的屬性和資料 (該中繼資料 ID)。

要求

{
  "data": [
    {
      "dataFilter": {
        "developerMetadataLookup": {
          "metadataId": metadataId
        }
      },
      "majorDimension": "ROWS",
      "values": [
        [
          "W-24",
          "84"
        ]
      ]
    }
  ],
  "includeValuesInResponse": true,
  "valueInputOption": "USER_ENTERED"
}

回應

{
  "spreadsheetId": spreadsheetId,
  "totalUpdatedRows": 1,
  "totalUpdatedColumns": 2,
  "totalUpdatedCells": 2,
  "totalUpdatedSheets": 1,
  "responses": [
    {
      "updatedRange": "Sheet7!A7:B7",
      "updatedRows": 1,
      "updatedColumns": 2,
      "updatedCells": 2,
      "dataFilter": {
        "developerMetadataLookup": {
          "metadataId": metadataId
        }
      },
      "updatedData": {
        "range": "Sheet7!A7:Z7",
        "majorDimension": "ROWS",
        "values": [
          [
            "W-24",
            "84"
          ]
        ]
      }
    }
  ]
}

依中繼資料清除值

如要清除符合特定中繼資料的儲存格值，請使用 spreadsheets.values.batchClearByDataFilter 方法。你必須指定資料篩選器，才能選取要清除的中繼資料。

顯示範例

要求

在這個範例中，我們會在要求中提供中繼資料 ID。回應會傳回試算表 ID 和清除的範圍。

{
  "dataFilters": [
    {
      "developerMetadataLookup": {
        "metadataId": metadataId
      }
    }
  ]
}

回應

{
  "spreadsheetId": spreadsheetId,
  "clearedRanges": [
    "Sheet7!A7:Z7"
  ]
}

中繼資料儲存空間限制

可儲存在試算表中的中繼資料總量設有限制。這項限制是以字元計算，且由 2 個元件組成：

項目	儲存空間限制分配
試算表	30,000 個半形字元
試算表中的每個工作表	30,000 個半形字元

試算表最多可儲存 30,000 個字元。此外，您還可以在試算表中為每個工作表儲存 30,000 個字元 (工作表 1 為 30,000 個字元，工作表 2 為 30,000 個字元，依此類推)。因此，內含 3 個頁面的試算表最多可以包含 120,000 個字元的開發人員中繼資料。

developerMetadata 物件鍵和值屬性中的每個字元都會計入這項限制。

這些限制日後可能會改變。