Nazwane i chronione zakresy

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

Przykłady te są przedstawione w postaci żą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 Google API, przeczytaj artykuł Aktualizowanie arkuszy kalkulacyjnych.

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

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

Dodawanie zakresów nazwanych lub chronionych

Poniższy spreadsheets.batchUpdate przykładowy kod pokazuje, jak używać 2 obiektów żądania. Pierwszy z nich używa AddNamedRangeRequest , aby przypisać zakresowi A1:E3 nazwę "Counts". Drugi używa AddProtectedRangeRequest aby przypisać zakresowi A4:E4 ochronę 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ą odpowiednio AddNamedRangeResponse i AddProtectedRangeResponse, które zawierają identyfikatory i właściwości zakresu.

Protokół żądania jest pokazany 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 spreadsheets.batchUpdate przykładowy kod pokazuje, jak używać 2 obiektów żądania. Pierwszy z nich używa DeleteNamedRangeRequest aby usunąć istniejący zakres nazwany, używając NAMED_RANGE_ID z poprzedniego wywołania interfejsu API. Drugi używa DeleteProtectedRangeRequest , aby usunąć istniejącą ochronę zakresu, używając PROTECTED_RANGE_ID z poprzedniego wywołania interfejsu API.

Protokół żądania jest pokazany 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 spreadsheets.batchUpdate przykładowy kod pokazuje, jak używać 2 obiektów żądania. Pierwszy z nich używa UpdateNamedRangeRequest , aby zaktualizować nazwę istniejącego zakresu nazwanego na "InitialCounts", używając NAMED_RANGE_ID z poprzedniego wywołania interfejsu API. Drugi używa UpdateProtectedRangeRequest , aby zaktualizować istniejący zakres chroniony, tak aby chronił on teraz ten sam zakres nazwany. Metoda Editors umożliwia edytowanie tych komórek tylko wymienionym użytkownikom. To żądanie używa NAMED_RANGE_ID i PROTECTED_RANGE_ID z poprzednich wywołań interfejsu API.

Protokół żądania jest pokazany 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"
      }
    }
  ]
}