Именованный & защищенные диапазоны

API Google Таблиц позволяет создавать, изменять и удалять именованные или защищенные диапазоны. Примеры на этой странице иллюстрируют, как можно выполнить некоторые распространенные операции с Таблицами с помощью Sheets API.

Эти примеры представлены в виде HTTP-запросов, которые не зависят от языка. Чтобы узнать, как реализовать пакетное обновление на разных языках с помощью клиентских библиотек Google API, см. раздел Обновление электронных таблиц .

В этих примерах заполнители SPREADSHEET_ID и SHEET_ID указывают, где вы будете предоставлять эти идентификаторы. Идентификатор таблицы можно найти в URL-адресе таблицы. Вы можете получить идентификатор листа , используя метод spreadsheets.get . Диапазоны указаны с использованием обозначения A1 . Пример диапазона: Лист1!A1:D5.

Кроме того, заполнители NAMED_RANGE_ID и PROTECTED_RANGE_ID предоставляют идентификаторы именованных и защищенных диапазонов. namedRangeId и protectedRangeId используются при отправке запросов на обновление или удаление связанных диапазонов. Идентификатор возвращается в ответ на запрос API Таблиц, который создает именованный или защищенный диапазон. Вы можете получить идентификаторы существующих диапазонов с помощью метода spreadsheets.get в теле ответа Spreadsheet .

Добавить именованные или защищенные диапазоны

В следующем примере кода spreadsheets.batchUpdate показано, как использовать два объекта запроса. Первый использует AddNamedRangeRequest чтобы присвоить диапазону A1:E3 имя «Counts». Второй использует AddProtectedRangeRequest для прикрепления защиты уровня предупреждения к диапазону A4:E4. Этот уровень защиты по-прежнему позволяет редактировать ячейки в пределах диапазона, но перед внесением изменения выдается предупреждение.

Эти запросы возвращают AddNamedRangeResponse и AddProtectedRangeResponse , содержащие идентификаторы диапазонов и свойства.

Протокол запроса показан ниже.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
  "requests": [
    {
      "addNamedRange": {
        "namedRange": {
          "name": "Counts",
          "range": {
            "sheetId": SHEET_ID,
            "startRowIndex": 0,
            "endRowIndex": 3,
            "startColumnIndex": 0,
            "endColumnIndex": 5,
          },
        }
      }
    },
    {
      "addProtectedRange": {
        "protectedRange": {
          "range": {
            "sheetId": SHEET_ID,
            "startRowIndex": 3,
            "endRowIndex": 4,
            "startColumnIndex": 0,
            "endColumnIndex": 5,
          },
          "description": "Protecting total row",
          "warningOnly": true
        }
      }
    }
  ]
}

Удаление именованных или защищенных диапазонов

В следующем примере кода spreadsheets.batchUpdate показано, как использовать два объекта запроса. Первый использует DeleteNamedRangeRequest для удаления существующего именованного диапазона, используя NAMED_RANGE_ID из предыдущего вызова API. Второй использует DeleteProtectedRangeRequest для удаления существующей защиты диапазона, используя PROTECTED_RANGE_ID из предыдущего вызова API.

Протокол запроса показан ниже.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
  "requests": [
    {
      "deleteNamedRange": {
          "namedRangeId": "NAMED_RANGE_ID",
      }
    },
    {
      "deleteProtectedRange": {
        "protectedRangeId": PROTECTED_RANGE_ID,
      }
    }
  ]
}

Обновление именованных или защищенных диапазонов

В следующем примере кода spreadsheets.batchUpdate показано, как использовать два объекта запроса. Первый использует UpdateNamedRangeRequest для обновления имени существующего именованного диапазона до «InitialCounts», используя NAMED_RANGE_ID из предыдущего вызова API. Второй использует UpdateProtectedRangeRequest для обновления существующего защищенного диапазона, чтобы он теперь защищал тот же именованный диапазон. Метод Editors позволяет редактировать эти ячейки только перечисленным пользователям. В этом запросе используются NAMED_RANGE_ID и PROTECTED_RANGE_ID из предыдущих вызовов API.

Протокол запроса показан ниже.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
  "requests": [
    {
      "updateNamedRange": {
        "namedRange": {
          "namedRangeId": NAMED_RANGE_ID,
          "name": "InitialCounts",
        },
        "fields": "name",
      }
    },
    {
      "updateProtectedRange": {
        "protectedRange": {
          "protectedRangeId": PROTECTED_RANGE_ID,
          "namedRangeId": NAMED_RANGE_ID,
          "warningOnly": false,
          "editors": {
            "users": [
              "charlie@example.com",
              "sasha@example.com"
            ]
          }
        },
        "fields": "namedRangeId,warningOnly,editors"
      }
    }
  ]
}