Эта страница переведена с помощью 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 со столбцом.

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

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

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

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

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

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

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

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

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

Этот запрос работает как обычный запрос "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"
  ]
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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