Interfejs API Arkuszy Google pozwala tworzyć, czyścić, kopiować i usuwać arkusze, a także kontrolować ich właściwości. Przykłady na tej stronie pokazują, jak można wykonywać typowe operacje w Arkuszach za pomocą interfejsu Sheets API.
Mają one postać żądań HTTP, które mają być neutralne pod względem języka. Aby dowiedzieć się, jak wdrożyć aktualizację zbiorczą w różnych językach przy użyciu bibliotek klienta interfejsu API Google, przeczytaj artykuł Aktualizowanie arkuszy kalkulacyjnych.
W tych przykładach obiekty zastępcze SPREADSHEET_ID i SHEET_ID wskazują, gdzie należy je umieścić. Identyfikator arkusza kalkulacyjnego znajdziesz w adresie URL arkusza kalkulacyjnego. Identyfikator arkusza możesz uzyskać, korzystając z metody spreadsheets.get. Zakresy są określane w notacji A1. Przykładowy zakres to Arkusz1!A1:D5.
Dodaj arkusz
Poniższy przykładowy kod spreadsheets.batchUpdate pokazuje, jak za pomocą AddSheetRequest dodać arkusz do arkusza kalkulacyjnego, a jednocześnie 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 (takimi jak SHEET_ID).
Protokół żądania jest pokazany 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 wszystkimi wartościami przy zachowaniu formatów
Poniższy przykładowy kod spreadsheets.batchUpdate pokazuje, jak za pomocą UpdateCellsRequest usunąć wszystkie wartości z arkusza i pozostawić formatowanie bez zmian.
Określenie pola userEnteredValue bez powiązanej wartości jest interpretowane jako instrukcja wyczyszczenia wartości z zakresu. Tego ustawienia można też używać w przypadku innych pól. Na przykład zmiana wartości fields na userEnteredFormat powoduje usunięcie z arkusza całego formatowania obsługiwanego przez interfejs API Arkuszy, ale wartości w komórkach pozostają niezmienione.
Protokół żądania jest pokazany 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 innego
Poniższy przykładowy kod spreadsheet.sheets.copyTo pokazuje, jak skopiować pojedynczy arkusz określony w SHEET_ID z jednego arkusza kalkulacyjnego do innego.
Zmienna TARGET_SPREADSHEET_ID w treści żądania określa docelowy arkusz kalkulacyjny. Kopia zachowuje wszystkie wartości, formatowanie, formuły i inne właściwości oryginału. Tytuł skopiowanego arkusza to „Kopia [oryginalny tytuł 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żyć DeleteSheetRequest do usunięcia arkusza określonego przez SHEET_ID.
Protokół żądania jest pokazany poniżej.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
"requests": [
{
"deleteSheet": {
"sheetId": SHEET_ID
}
}
]
}
Odczytywanie danych arkusza
Poniższy przykładowy kod spreadsheets.get pokazuje, jak uzyskać informacje o właściwości arkusza z arkusza kalkulacyjnego, które są oznaczone parametrami SHEET_ID i SPREADSHEET_ID. Ta metoda jest często używana do określania metadanych arkuszy w obrębie określonego arkusza kalkulacyjnego, dzięki czemu można wykonywać dodatkowe operacje na arkuszach. Parametr zapytania fields określa, że zwracane powinny być tylko dane właściwości arkusza (w odróżnieniu od wartości komórki czy danych z całego arkusza kalkulacyjnego).
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 ono 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
}
},
...
],
}