Эта страница переведена с помощью Cloud Translation API.

Прочтите & писать метаданные разработчика

Функция метаданных разработчика позволяет вам связывать метаданные с различными сущностями и местоположениями в электронной таблице. Затем вы можете запросить эти метаданные и использовать их для поиска объектов, с которыми они связаны.

Вы можете связать метаданные со строками, столбцами, листами или электронной таблицей.

Метаданные разработчика позволяют выполнять такие операции, как:

Свяжите произвольные данные с различными сущностями и местоположениями в электронной таблице — например, свяжите totals со столбцом D или responseId = 1234 со строкой 7.
Найти все местоположения и данные, связанные с определенным ключом или атрибутом метаданных . Например, если заданы totals ключа, связанные со столбцом D, или задан responseId , вернуть все строки с метаданными responseId и связанными с ними значениями метаданных.
Найти все данные, связанные с определенной сущностью или местоположением . Например, для заданного столбца D вернуть все метаданные, связанные с этим местоположением.
Извлечение значений в указанном месте путем указания связанных метаданных — например, если заданы totals значения, возвращается представление значений, содержащихся в связанном столбце или строке, или если задана summary возвращается представление связанного ресурса таблицы.
Обновите значения в определенном месте, указав связанные метаданные. Например, вместо обновления значений в строке с помощью нотации A1 обновите значения, указав идентификатор метаданных.

Чтение и запись метаданных

Ресурс spreadsheets.developerMetadata обеспечивает доступ к метаданным разработчика, связанным с местоположением или объектом в электронной таблице.

О метаданных разработчика

В этом разделе описываются некоторые ключевые аспекты метаданных разработчика, которые следует учитывать при работе с API Таблиц.

Метаданные как теги

Одним из вариантов использования метаданных разработчика является тег , который называет местоположение в таблице, используя только ключ и местоположение. Например, вы можете связать headerRow с определенной строкой или totals с определенным столбцом в таблице. Теги можно использовать для семантической привязки частей таблицы к полям в стороннем инструменте или базе данных, поэтому изменения в таблице не нарушат работу вашего приложения.

Метаданные как свойства

Метаданные, созданные путем указания ключа, местоположения и значения, действуют как пара ключ-значение, связанная с этим местоположением на листе. Например, вы можете связать:

formResponseId = resp123 со строкой
lastUpdated = 1477369882 со столбцом.

Это позволяет хранить и получать доступ к пользовательским именованным свойствам, связанным с определенными областями или данными в электронной таблице.

Видимые метаданные проекта и документа

Чтобы предотвратить вмешательство одного проекта разработчика в метаданные другого, есть 2 настройки visibility метаданных: project и document . При использовании API Таблиц метаданные проекта видны и доступны только из проекта разработчика, который их создал. Метаданные документа доступны из любого проекта разработчика, имеющего доступ к документу.

Запросы, в которых явно не указана видимость, возвращают соответствующие метаданные документа и соответствующие метаданные проекта для проекта разработчика, сделавшего запрос.

Уникальность

Ключи метаданных не обязательно должны быть уникальными, но metadataId должен быть уникальным. Если вы создаете метаданные и оставляете поле идентификатора неуказанным, API назначает его. Этот идентификатор можно использовать для идентификации метаданных, в то время как ключи и другие атрибуты можно использовать для идентификации наборов метаданных.

Создать метаданные

Для создания метаданных используйте метод batchUpdate и предоставьте createDeveloperMetadataRequest с metadataKey , location и visibility . При желании можно указать metadataValue или явный metadataId .

Если вы укажете ID, который уже используется, запрос будет неудачным. Если вы не предоставите ID, API назначит его.

В этом примере мы предоставляем ключ, значение и строку в запросе. Ответ возвращает эти значения метаданных разработчика, а также назначенный идентификатор метаданных.

Запрос

{
  "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 метаданных разработчика.

Запрос

В этом примере мы предоставляем идентификатор электронной таблицы и идентификатор метаданных в запросе. Ответ возвращает значения метаданных разработчика для идентификатора метаданных.

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 , который соответствует любым существующим метаданным в любой комбинации свойств, таких как ключ, значение, местоположение или видимость.

В этом примере мы предоставляем несколько идентификаторов метаданных в запросе. Ответ возвращает значения метаданных разработчика для каждого идентификатора метаданных.

Запрос

{
  "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 с новыми значениями и маску поля, описывающую поля, которые нужно обновить.

В этом примере мы предоставляем идентификатор метаданных, идентификатор листа и новый ключ метаданных в запросе. Ответ возвращает эти значения метаданных разработчика, а также обновленный ключ метаданных.

Запрос

{
  "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 , чтобы выбрать метаданные, которые вы хотите удалить.

В этом примере мы предоставляем идентификатор метаданных в запросе. Ответ возвращает значения метаданных разработчика для идентификатора метаданных.

Чтобы подтвердить удаление метаданных разработчика, используйте метод spreadsheets.developerMetadata.get , указав идентификатор удаленных метаданных. Вы должны получить ответ с кодом статуса HTTP 404: Not Found , с сообщением "Нет метаданных разработчика с идентификатором 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 . Вам нужно будет указать идентификатор таблицы и один или несколько фильтров данных, которые соответствуют метаданным.

В этом примере мы предоставляем идентификатор метаданных в запросе. Ответ возвращает значения ячеек строки (номер модели, ежемесячные продажи) для идентификатора метаданных.

Запрос

{
  "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 . Вам нужно будет указать идентификатор таблицы и один или несколько фильтров данных, которые соответствуют метаданным.

Этот запрос функционирует как обычный запрос "spreadsheet GET", за исключением того, что список метаданных, соответствующих указанным фильтрам данных, определяет, какие листы, данные сетки и другие ресурсы объектов с метаданными возвращаются. Если includeGridData имеет значение true, данные сетки, пересекающие указанные диапазоны сетки, также возвращаются для листа.

В этом примере мы предоставляем идентификатор метаданных и устанавливаем 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 . Вам нужно будет указать идентификатор таблицы, valueInputOption и один или несколько DataFilterValueRange , соответствующих метаданным.

В этом примере мы предоставляем идентификатор метаданных и обновленные значения строк в запросе. Ответ возвращает как обновленные свойства, так и данные для идентификатора метаданных.

Запрос

{
  "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 . Вам нужно будет указать фильтр данных, чтобы выбрать метаданные, которые вы хотите очистить.

Запрос

В этом примере мы предоставляем идентификатор метаданных в запросе. Ответ возвращает идентификатор электронной таблицы и очищенные диапазоны.

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

Ответ

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

Ограничения на хранение метаданных

Существует ограничение на общий объем метаданных, которые можно хранить в электронной таблице. Этот лимит измеряется в символах и состоит из 2 компонентов:

Элемент	Распределение лимита хранилища
Электронная таблица	30 000 символов
Каждый лист в электронной таблице	30 000 символов

Вы можете хранить до 30 000 символов для электронной таблицы. Кроме того, вы можете хранить 30 000 символов для каждого листа в электронной таблице (30 000 для листа 1, 30 000 для листа 2 и т. д.). Таким образом, электронная таблица с 3 страницами может содержать до 120 000 символов метаданных разработчика.

Каждый символ в атрибутах ключа и значения объекта developerMetadata учитывается в этом ограничении.

Прочтите & писать метаданные разработчика Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

Чтение и запись метаданных

О метаданных разработчика

Метаданные как теги

Метаданные как свойства

Видимые метаданные проекта и документа

Уникальность

Создать метаданные

Прочитать один элемент метаданных

Чтение нескольких элементов метаданных

Обновить метаданные

Удалить метаданные

Чтение и запись значений, связанных с метаданными

Получить значения ячеек по метаданным

Получить электронную таблицу по метаданным

Обновить значения по метаданным

Очистить значения по метаданным

Ограничения на хранение метаданных

Прочтите & писать метаданные разработчика