Benannte und geschützte Bereiche

Mit der Google Sheets API können Sie benannte oder geschützte Bereiche erstellen, ändern und löschen. Die Beispiele auf dieser Seite veranschaulichen, wie Sie einige häufige Sheets-Vorgänge mit der Sheets API ausführen können.

Diese Beispiele werden in Form von HTTP-Anfragen dargestellt, um sprachneutral zu sein. Informationen zum Implementieren eines Batch-Updates in verschiedenen Sprachen mit den Google API-Clientbibliotheken finden Sie unter Tabellen aktualisieren.

In diesen Beispielen geben die Platzhalter SPREADSHEET_ID und SHEET_ID an, wo Sie diese IDs angeben müssen. Die Tabellen ID finden Sie in der Tabellen-URL. Sie können die Tabellenblatt-ID mit der spreadsheets.get Methode abrufen. Die Bereiche werden in der A1-Notation angegeben. Ein Beispielbereich ist Sheet1!A1:D5.

Außerdem enthalten die Platzhalter NAMED_RANGE_ID und PROTECTED_RANGE_ID die IDs für die benannten und geschützten Bereiche. Die IDs namedRangeId und protectedRangeId werden verwendet, wenn Anfragen zum Aktualisieren oder Löschen der zugehörigen Bereiche gesendet werden. Die ID wird in der Antwort auf eine Sheets API-Anfrage zurückgegeben, mit der ein benannter oder geschützter Bereich erstellt wird. Sie können die IDs vorhandener Bereiche mit der spreadsheets.get Methode im Antworttext Spreadsheet abrufen.

Benannte oder geschützte Bereiche hinzufügen

Das folgende spreadsheets.batchUpdate Codebeispiel zeigt, wie Sie zwei Anfrageobjekte verwenden. Mit dem ersten wird mit dem AddNamedRangeRequest dem Bereich A1:E3 der Name „Counts“ zugewiesen. Mit dem zweiten wird mit AddProtectedRangeRequest dem Bereich A4:E4 ein Schutz auf Warnstufe zugewiesen. Bei dieser Schutzstufe können Zellen im Bereich weiterhin bearbeitet werden, aber vor der Änderung wird eine Warnung angezeigt.

Diese Anfragen geben ein AddNamedRangeResponse und ein AddProtectedRangeResponse, mit den Bereichs-IDs und -Eigenschaften zurück.

Das Anfrageprotokoll ist unten dargestellt.

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

Benannte oder geschützte Bereiche löschen

Das folgende spreadsheets.batchUpdate Codebeispiel zeigt, wie Sie zwei Anfrageobjekte verwenden. Mit dem ersten wird mit DeleteNamedRangeRequest ein vorhandener benannter Bereich gelöscht. Dabei wird die NAMED_RANGE_ID aus einem vorherigen API-Aufruf verwendet. Mit dem zweiten wird mit DeleteProtectedRangeRequest ein vorhandener Bereichsschutz gelöscht. Dabei wird die PROTECTED_RANGE_ID aus einem vorherigen API-Aufruf verwendet.

Das Anfrageprotokoll ist unten dargestellt.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "deleteNamedRange": {
          "namedRangeId": "NAMED_RANGE_ID",
      }
    },
    {
      "deleteProtectedRange": {
        "protectedRangeId": PROTECTED_RANGE_ID,
      }
    }
  ]
}

Benannte oder geschützte Bereiche aktualisieren

Das folgende spreadsheets.batchUpdate Codebeispiel zeigt, wie Sie zwei Anfrageobjekte verwenden. Mit dem ersten wird mit UpdateNamedRangeRequest der Name eines vorhandenen benannten Bereichs in „InitialCounts“ geändert. Dabei wird die NAMED_RANGE_ID aus einem vorherigen API-Aufruf verwendet. Mit dem zweiten wird mit dem UpdateProtectedRangeRequest ein vorhandener geschützter Bereich so aktualisiert, dass er jetzt denselben benannten Bereich schützt. Die Editors Methode können nur die aufgeführten Nutzer diese Zellen bearbeiten. Für diese Anfrage werden die NAMED_RANGE_ID und PROTECTED_RANGE_ID aus vorherigen API-Aufrufen verwendet.

Das Anfrageprotokoll ist unten dargestellt.

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