Nazwane i chronione zakresy

Interfejs Google Sheets API umożliwia tworzenie, modyfikowanie i usuwanie nazwanych lub chronionych zakresów. Przykłady na tej stronie pokazują, jak za pomocą interfejsu Sheets API wykonywać niektóre typowe operacje w Arkuszach.

Przykłady te są przedstawione w formie żądań HTTP, aby były niezależne od języka. Aby dowiedzieć się, jak zaimplementować aktualizację zbiorczą w różnych językach za pomocą bibliotek klienta interfejsu API Google, przeczytaj artykuł Aktualizowanie arkuszy kalkulacyjnych.

W tych przykładach symbole zastępcze SPREADSHEET_ID i SHEET_ID wskazują miejsca, w których należy podać te identyfikatory. Identyfikator arkusza kalkulacyjnego znajdziesz w adresie URL arkusza. Identyfikator arkusza możesz uzyskać za pomocą metody spreadsheets.get. Zakresy są określone za pomocą notacji A1. Przykładowy zakres to Arkusz1!A1:D5.

Dodatkowo zmienne NAMED_RANGE_ID i PROTECTED_RANGE_ID zawierają identyfikatory nazwanych i chronionych zakresów. Symbole namedRangeId i protectedRangeId są używane podczas wysyłania żądań aktualizacji lub usunięcia powiązanych zakresów. Identyfikator jest zwracany w odpowiedzi na żądanie interfejsu Arkuszy API, które tworzy nazwany lub chroniony zakres. Identyfikatory istniejących zakresów możesz uzyskać za pomocą metody spreadsheets.get w treści odpowiedzi Spreadsheet.

Dodawanie nazwanych lub chronionych zakresów

Poniższy przykładowy kod spreadsheets.batchUpdate pokazuje, jak używać 2 obiektów żądania. Pierwsza z nich używa znaku AddNamedRangeRequest, aby przypisać zakresowi A1:E3 nazwę „Counts”. Druga używa znaku AddProtectedRangeRequest do przypisania do zakresu A4:E4 ochrony na poziomie ostrzeżenia. Ten poziom ochrony nadal umożliwia edytowanie komórek w zakresie, ale przed wprowadzeniem zmiany wyświetla ostrzeżenie.

Te żądania zwracają obiekt AddNamedRangeResponse i obiekt AddProtectedRangeResponse, zawierające identyfikatory zakresów i właściwości.

Protokół żądania jest widoczny poniżej.

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
        }
      }
    }
  ]
}

Usuwanie zakresów nazwanych lub chronionych

Poniższy przykładowy kod spreadsheets.batchUpdate pokazuje, jak używać 2 obiektów żądania. Pierwszy z nich używa DeleteNamedRangeRequest do usunięcia istniejącego zakresu nazwanego, używając NAMED_RANGE_ID z poprzedniego wywołania interfejsu API. Drugi używa DeleteProtectedRangeRequest do usunięcia istniejącej ochrony zakresu za pomocą PROTECTED_RANGE_ID z poprzedniego wywołania interfejsu API.

Protokół żądania jest widoczny poniżej.

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

Aktualizowanie zakresów nazwanych lub chronionych

Poniższy przykładowy kod spreadsheets.batchUpdate pokazuje, jak używać 2 obiektów żądania. Pierwsze polecenie używa parametru UpdateNamedRangeRequest do zmiany nazwy istniejącego nazwanego zakresu na „InitialCounts” przy użyciu parametru NAMED_RANGE_ID z poprzedniego wywołania interfejsu API. Drugi używa UpdateProtectedRangeRequest do zaktualizowania istniejącego zakresu chronionego, aby chronił on teraz ten sam zakres nazwany. Metoda Editors umożliwia edytowanie tych komórek tylko wymienionym użytkownikom. To żądanie używa parametrów NAMED_RANGE_ID i PROTECTED_RANGE_ID z poprzednich wywołań interfejsu API.

Protokół żądania jest widoczny poniżej.

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"
      }
    }
  ]
}