Le maschere di campo sono un modo per i chiamanti dell'API di elencare i campi che una richiesta deve restituire o aggiornare. L'utilizzo di un FieldMask consente all'API di evitare il lavoro non necessario e migliora le prestazioni. Maschera dei campi viene utilizzato sia per il metodo di lettura sia per quello di aggiornamento nell'API Fogli Google.
Lettura con una maschera dei campi
I fogli di lavoro possono essere grandi e spesso non sono necessarie tutte le parti
Spreadsheet
risorsa restituita da una richiesta di lettura. Puoi limitare ciò che viene restituito in
Risposta dell'API Fogli, utilizzando il parametro URL fields. Per il meglio
delle prestazioni,
indicare esplicitamente solo i campi di cui hai bisogno
nella risposta.
Il formato del parametro field è identico a quello del parametro Codifica JSON di una FieldMask. In breve, più campi diversi sono separati da virgole, mentre i campi secondari separati da punti. I nomi dei campi possono essere specificati in camelCase o separated_by_underscores. Per praticità, sono presenti vari campi secondari può essere elencato tra parentesi.
Le seguenti
Richiesta spreadsheets.get
un esempio utilizza una maschera dei campi sheets.properties(sheetId,title,sheetType,gridProperties)
recuperare solo l'ID, il titolo
SheetType e
GridProperties
di
SheetProperties
in tutti i fogli di un foglio di lavoro:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties(sheetId,title,sheetType,gridProperties)
La risposta a questa chiamata al metodo è
Spreadsheet
contenente i componenti richiesti nella maschera dei campi. Tieni presente che
sheetType=OBJECT non contiene gridProperties:
{
"sheets": [
{
"properties": {
"sheetId": SHEET_ID,
"title": "TITLE",
"sheetType": "GRID",
"gridProperties": {
"rowCount": 1000,
"columnCount": 25
}
}
},
{
"properties": {
"sheetId": SHEET_ID,
"title": "TITLE",
"sheetType": "OBJECT"
}
}
]
}
Aggiornamento con una maschera dei campi
A volte è necessario aggiornare solo alcuni campi di un oggetto senza uscire dal
gli altri campi non sono stati modificati. Richieste di aggiornamento all'interno di un
spreadsheets.batchUpdate
utilizza le maschere dei campi per indicare all'API i campi che vengono modificati. La
la richiesta di aggiornamento ignora i campi non specificati nella maschera del campo,
lasciando i valori attuali.
Puoi anche annullare l'impostazione di un campo non specificandolo nel messaggio aggiornato, ma aggiungendo il campo alla maschera. In questo modo viene cancellato qualsiasi valore precedente al campo che ha avuto.
La sintassi per le maschere dei campi di aggiornamento è la stessa delle maschere dei campi di lettura.
L'esempio seguente utilizza il metodo
AddSheetRequest
per aggiungere un nuovo foglio di tipo Grid, bloccare la prima riga e colorare il nuovo
scheda rossa del foglio:
POST https://sheets.googleapis.com/v1/spreadsheets/spreadsheetId:batchUpdate
{
"spreadsheetId": "SPREADSHEET_ID",
"replies": [
{
"addSheet": {
"properties": {
"sheetId": SHEET_ID,
"title": "TITLE",
"index": 6,
"sheetType": "GRID",
"gridProperties": {
"rowCount": 1000,
"columnCount": 26,
"frozenRowCount": 1
},
"tabColor": {
"red": 0.003921569
},
"tabColorStyle": {
"rgbColor": {
"red": 0.003921569
}
}
}
}
}
]
}