Interfejs API Arkuszy Google umożliwia tworzenie, modyfikowanie i usuwanie zakresów nazwanych lub chronionych. Przykłady na tej stronie pokazują, jak za pomocą interfejsu Sheets API wykonać niektóre typowe operacje w Arkuszach.
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.
Dodatkowo obiekty zastępcze NAMED_RANGE_ID i PROTECTED_RANGE_ID dostarczają identyfikatory nazwanych i chronionych zakresów. namedRangeId i protectedRangeId są używane podczas wysyłania żądań aktualizacji lub usuwania powiązanych zakresów. Identyfikator jest zwracany w odpowiedzi na żądanie do interfejsu API Arkuszy Google, które tworzy nazwany lub chroniony zakres. Identyfikatory istniejących zakresów możesz znaleźć w treści odpowiedzi Spreadsheet za pomocą metody spreadsheets.get.
Dodaj zakresy nazwane lub chronione
Poniższy przykładowy kod spreadsheets.batchUpdate pokazuje, jak użyć 2 obiektów żądań. Pierwszy z nich korzysta z funkcji AddNamedRangeRequest, aby przypisać zakresowi A1:E3 nazwę „Liczby”. Drugie wykorzystuje AddProtectedRangeRequest, aby dołączyć ochronę na poziomie ostrzeżenia do zakresu A4:E4. Ten poziom ochrony pozwala edytować komórki w zakresie, ale przed wprowadzeniem zmiany wyświetla się ostrzeżenie.
Te żądania zwracają wartości AddNamedRangeResponse i AddProtectedRangeResponse, które zawierają identyfikatory zakresów i właściwości.
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
}
}
}
]
}
Usuń zakresy nazwane lub chronione
Poniższy przykładowy kod spreadsheets.batchUpdate pokazuje, jak użyć 2 obiektów żądań. W pierwszym z nich używana jest funkcja DeleteNamedRangeRequest, która pozwala usunąć istniejący zakres nazwany przy użyciu funkcji NAMED_RANGE_ID z poprzedniego wywołania interfejsu API. W drugim znajduje się użycie DeleteProtectedRangeRequest do usunięcia istniejącego zakresu ochrony zakresu przy użyciu metody 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,
}
}
]
}
Zaktualizuj zakresy nazwane lub chronione
Poniższy przykładowy kod spreadsheets.batchUpdate pokazuje, jak użyć 2 obiektów żądań. W pierwszym z nich używana jest funkcja UpdateNamedRangeRequest, która aktualizuje nazwę istniejącego zakresu nazwanego na „InitialCounts” przy użyciu NAMED_RANGE_ID z poprzedniego wywołania interfejsu API. Drugie wykorzystuje zakres UpdateProtectedRangeRequest do zaktualizowania istniejącego zakresu chronionego i teraz chroni ten sam zakres nazwany. Metoda Editors umożliwia edytowanie tych komórek tylko użytkownikom z listy. W tym żądaniu używane są 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"
}
}
]
}