Operacje arkusza

Interfejs Sheets API umożliwia tworzenie, czyszczenie, kopiowanie i usuwanie arkuszy oraz kontrolowanie ich właściwości. Przykłady na tej stronie pokazują, jak wykonywać typowe operacje w Arkuszach za pomocą interfejsu Sheets API.

Przykłady te są przedstawione w formie żądań HTTP, aby były neutralne językowo. Aby dowiedzieć się, jak za pomocą bibliotek klienta interfejsu API Google wdrożyć zbiorcze aktualizowanie w różnych językach, przeczytaj artykuł Aktualizowanie arkuszy kalkulacyjnych.

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

Dodawanie arkusza

Poniższy przykładowy kod spreadsheets.batchUpdate pokazuje, jak za pomocą funkcji AddSheetRequest dodać arkusz do arkusza kalkulacyjnego, a także ustawić tytuł, rozmiar siatki i kolor karty.

Odpowiedź składa się z AddSheetResponse, który zawiera obiekt z właściwościami utworzonego arkusza (np. SHEET_ID).

Protokół żądania przedstawiono poniżej.

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

{
  "requests": [
    {
      "addSheet": {
        "properties": {
          "title": "Deposits",
          "gridProperties": {
            "rowCount": 20,
            "columnCount": 12
          },
          "tabColor": {
            "red": 1.0,
            "green": 0.3,
            "blue": 0.4
          }
        }
      }
    }
  ]
}

Czyszczenie arkusza ze wszystkich wartości przy zachowaniu formatów

Ten przykładowy kod spreadsheets.batchUpdate pokazuje, jak za pomocą funkcji UpdateCellsRequest usunąć wszystkie wartości z arkusza, pozostawiając formatowanie bez zmian.

Podanie pola userEnteredValue bez odpowiedniej wartości jest interpretowane jako instrukcja wyczyszczenia wartości w zakresie. Tego ustawienia możesz też używać w innych polach. Na przykład zmiana wartości fields na userEnteredFormat powoduje usunięcie z arkusza wszystkich formatów obsługiwanych przez interfejs Sheets API, ale nie zmienia wartości komórek.

Protokół żądania przedstawiono poniżej.

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

{
  "requests": [
    {
      "updateCells": {
        "range": {
          "sheetId": SHEET_ID
        },
        "fields": "userEnteredValue"
      }
    }
  ]
}

Kopiowanie arkusza z jednego arkusza kalkulacyjnego do drugiego

Poniższy przykładowy kod spreadsheet.sheets.copyTo pokazuje, jak skopiować z jednego arkusza kalkulacyjnego do drugiego pojedynczy arkusz określony przez zmienną SHEET_ID.

Zmienna TARGET_SPREADSHEET_ID w treści żądania określa arkusz docelowy. Kopie zachowują wszystkie wartości, formatowanie, formuły i inne właściwości oryginału. Tytuł skopiowanej karty to „Kopia karty [nazwa oryginalnej karty]”.

Odpowiedź zawiera obiekt SheetProperties opisujący właściwości utworzonego arkusza.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/sheets/SHEET_ID:copyTo

{
  "destinationSpreadsheetId": "TARGET_SPREADSHEET_ID"
}

Usuwanie arkusza

Poniższy przykładowy kod spreadsheets.batchUpdate pokazuje, jak użyć metody DeleteSheetRequest, aby usunąć arkusz określony przez parametr SHEET_ID.

Protokół żądania przedstawiono poniżej.

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

{
  "requests": [
    {
      "deleteSheet": {
        "sheetId": SHEET_ID
      }
    }
  ]
}

Czytanie danych arkusza

Poniższy przykładowy kod spreadsheets.get pokazuje, jak uzyskać informacje o właściwości arkusz z arkusza kalkulacyjnego, określonego przez SHEET_ID i SPREADSHEET_ID. Ta metoda jest często używana do określania metadanych arkuszy w określonym arkuszu kalkulacyjnym, aby można było wykonywać dodatkowe operacje na tych arkuszach. Parametr zapytania fields określa, że zwracane mają być tylko dane właściwości arkusza (a nie dane wartości komórki ani dane dotyczące całego arkusza kalkulacyjnego).

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID?&fields=sheets.properties

Odpowiedź zawiera zasób Spreadsheet, który zawiera obiekt Sheet z elementami SheetProperties. Jeśli dane pole odpowiedzi ma ustawioną wartość domyślną, jest pomijane w odpowiedzi.

{
  "sheets": [
    {
      "properties": {
        "sheetId": SHEET_ID,
        "title": "Sheet1",
        "index": 0,
        "sheetType": "GRID",
        "gridProperties": {
          "rowCount": 100,
          "columnCount": 20,
          "frozenRowCount": 1
        }
        "tabColor": {
          "blue": 1.0
        }
      },
      ...
  ],
}