Operacje arkusza

Interfejs Google Sheets API umożliwia tworzenie, czyszczenie, kopiowanie i usuwanie arkuszy, a także kontrolowanie ich właściwości. Przykłady na tej stronie pokazują, jak za pomocą interfejsu Arkuszy Google 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.

Dodawanie arkusza

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

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

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

Usuwanie wszystkich wartości z arkusza przy zachowaniu formatów

Poniższy spreadsheets.batchUpdate przykładowy kod pokazuje, jak za pomocą UpdateCellsRequest usunąć wszystkie wartości z arkusza, nie zmieniając formatowania.

Określenie pola userEnteredValue bez odpowiedniej wartości jest interpretowane jako instrukcja wyczyszczenia wartości w zakresie. Tego ustawienia możesz używać też z innymi polami. Na przykład zmiana wartości fields na userEnteredFormat usuwa z arkusza całe formatowanie obsługiwane przez interfejs Sheets API, ale pozostawia wartości komórek bez zmian.

Protokół żądania jest widoczny 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 kodspreadsheet.sheets.copyTo pokazuje, jak skopiować pojedynczy arkusz określony przez SHEET_ID z jednego arkusza kalkulacyjnego do innego.

Zmienna TARGET_SPREADSHEET_ID w treści żądania określa arkusz kalkulacyjny docelowy. Kopia zachowuje wszystkie wartości, formatowanie, formuły i inne właściwości oryginału. Tytuł skopiowanego arkusza to „Kopia [tytuł oryginalnego arkusza]”.

Odpowiedź składa się z obiektu SheetProperties opisującego 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żywać metody DeleteSheetRequest do usuwania arkusza określonego przez SHEET_ID.

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

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

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

Odczytywanie danych z arkusza

Poniższy przykładowy kodspreadsheets.get pokazuje, jak uzyskać informacje o właściwości arkusza z arkusza kalkulacyjnego określonego przez SHEET_ID i SPREADSHEET_ID. Ta metoda jest często używana do określania metadanych arkuszy w konkretnym arkuszu kalkulacyjnym, dzięki czemu dodatkowe operacje mogą być kierowane na te arkusze. Parametr zapytania fields określa, że mają być zwracane tylko dane właściwości arkusza (w przeciwieństwie do danych wartości komórek lub danych związanych z całym arkuszem kalkulacyjnym).

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

Odpowiedź składa się z zasobu Spreadsheet, który zawiera obiekt Sheet z elementami SheetProperties. Jeśli dane pole odpowiedzi ma 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
        }
      },
      ...
  ],
}