La funzionalità dei metadati ti consente di associare i metadati a varie entità e posizioni in un foglio di lavoro. Puoi quindi eseguire query su questi metadati e utilizzarli per trovare gli oggetti a cui sono associati.
Puoi associare i metadati a righe, colonne, fogli o a un foglio di lavoro.
Puoi generare metadati per eseguire operazioni come:
Associare dati arbitrari a varie entità e località in un foglio di lavoro: ad esempio, associa
totalsalla colonna D oresponseId = 1234alla riga 7.Trova tutte le posizioni e i dati associati a una determinata chiave dei metadati o a un attributo: ad esempio, data la chiave
totalsassociata alla colonna D o datoresponseId, restituisci tutte le righe con i metadatiresponseIde il valore dei metadati associato.Trova tutti i dati associati a una determinata entità o posizione: ad esempio, data la colonna D, restituisci tutti i metadati associati a quella posizione.
Recupera i valori in una posizione specificando i metadati associati: ad esempio, dato
totals, restituisci una rappresentazione dei valori contenuti nella colonna o nella riga associata oppure, datosummary, restituisci una rappresentazione della risorsa Fogli associata.Aggiorna i valori in una posizione specificando i metadati associati: ad esempio, anziché aggiornare i valori in una riga tramite la notazione A1, aggiorna i valori indicando un ID metadati.
Leggere e scrivere metadati
La risorsa
spreadsheets.developerMetadata
fornisce l'accesso ai metadati associati a una posizione o a un oggetto in un
foglio di lavoro.
Informazioni sui metadati
Questa sezione descrive alcuni aspetti chiave dei metadati da prendere in considerazione quando utilizzi l'API Sheets.
Metadati come tag: un utilizzo dei metadati dello sviluppatore è un tag che nomina una posizione nel foglio di lavoro utilizzando solo una chiave e una posizione. Ad esempio, puoi associare
headerRowa una riga specifica ototalsa una colonna specifica all'interno di un foglio. I tag possono essere utilizzati per associare semanticamente parti di un foglio di lavoro a campi in uno strumento o un database di terze parti, in modo che le modifiche al foglio di lavoro non danneggino l'app.Metadati come proprietà: i metadati creati specificando una chiave, una posizione e un valore fungono da coppia chiave-valore associata a quella posizione in un foglio. Ad esempio, puoi associare:
formResponseId = resp123con una rigalastUpdated = 1477369882con una colonna
In questo modo puoi memorizzare e accedere a proprietà denominate personalizzate associate a aree o dati specifici in un foglio di lavoro.
Metadati visibili del progetto e del documento: per evitare che un progetto dello sviluppatore interferisca con i metadati di un altro, esistono due impostazioni dei metadati
visibility:projectedocument. Utilizzando l'API Sheets, i metadati del progetto sono visibili e accessibili solo dal progetto Google Cloud che li ha creati. I metadati del documento sono accessibili da qualsiasi progetto Google Cloud con accesso al documento.Le query che non specificano esplicitamente una visibilità restituiscono i metadati dei documenti corrispondenti e i metadati di progetto corrispondenti per il progetto Google Cloud che effettua la richiesta.
Unicità: le chiavi dei metadati non devono essere univoche, ma il
metadataIddeve essere distinto. Se crei metadati e lasci il campo ID non specificato, l'API ne assegna uno. Questo ID può essere utilizzato per identificare i metadati, mentre le chiavi e altri attributi possono essere utilizzati per identificare i set di metadati.
Crea metadati
Per creare i metadati, utilizza il
metodo
batchUpdate
nella risorsa
spreadsheets e fornisci un
CreateDeveloperMetadataRequest
con i valori metadataKey, location e visibility della risorsa
spreadsheets.developerMetadata. Puoi specificare facoltativamente un metadataValue o un metadataId esplicito.
Se specifichi un ID già in uso, la richiesta non andrà a buon fine. Se non fornisci un ID, l'API ne assegna uno.
In questo esempio, forniamo una chiave, un valore e una riga nella richiesta. La risposta restituisce questi valori dei metadati sviluppatore, oltre all'ID metadati assegnato.
Richiesta
{
"requests": [
{
"createDeveloperMetadata": {
"developerMetadata": {
"location": {
"dimensionRange": {
"sheetId": SHEET_ID,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT",
"metadataKey": "Sales",
"metadataValue": "2022"
}
}
}
]
}Risposta
{
"spreadsheetId": SPREADSHEET_ID,
"replies": [
{
"createDeveloperMetadata": {
"developerMetadata": {
"metadataId": METADATA_ID,
"metadataKey": "Sales",
"metadataValue": "2022",
"location": {
"locationType": "ROW",
"dimensionRange": {
"sheetId": SHEET_ID,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT"
}
}
}
]
}Leggere un singolo elemento di metadati
Per recuperare un singolo metadato dello sviluppatore distinto, utilizza il metodo
spreadsheets.developerMetadata.get, specificando spreadsheetId contenente i metadati e l'metadataId univoco dei metadati dello sviluppatore.
Richiesta
In questo esempio, forniamo l'ID foglio di lavoro e l'ID metadati nella richiesta. La risposta restituisce i valori dei metadati dello sviluppatore per l'ID metadati.
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/developerMetadata/METADATA_ID
Risposta
{
"metadataId": METADATA_ID,
"metadataKey": "Sales",
"metadataValue": "2022",
"location": {
"locationType": "ROW",
"dimensionRange": {
"sheetId": SHEET_ID,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT"
}Leggere più elementi di metadati
Per recuperare più elementi di metadati dello sviluppatore, utilizza il metodo
spreadsheets.developerMetadata.search. Devi specificare un
DataFilter che corrisponda
a qualsiasi metadato esistente su qualsiasi combinazione di proprietà, ad esempio chiave, valore, posizione o visibilità.
In questo esempio, forniamo più ID metadati nella richiesta. La risposta restituisce i valori dei metadati dello sviluppatore per ogni ID metadati.
Richiesta
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
},
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
]
}Risposta
{
"matchedDeveloperMetadata": [
{
"developerMetadata": {
"metadataId": METADATA_ID,
"metadataKey": "Revenue",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": SHEET_ID
},
"visibility": "DOCUMENT"
},
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
]
},
{
"developerMetadata": {
"metadataId": METADATA_ID,
"metadataKey": "Sales",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": SHEET_ID
},
"visibility": "DOCUMENT"
},
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
]
}
]
}Aggiorna metadati
Per aggiornare i metadati dello sviluppatore, utilizza il
metodo spreadsheets.batchUpdate e fornisci un
UpdateDeveloperMetadataRequest.
Devi specificare un
DataFilter che ha come target
i metadati da aggiornare, una risorsa
spreadsheets.developerMetadata
con i nuovi valori e una maschera
di campo che descrive i campi da
aggiornare.
In questo esempio, nella richiesta forniamo l'ID metadati, l'ID foglio e una nuova chiave dei metadati. La risposta restituisce questi valori dei metadati dello sviluppatore, oltre alla chiave dei metadati aggiornata.
Richiesta
{
"requests": [
{
"updateDeveloperMetadata": {
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
],
"developerMetadata": {
"location": {
"sheetId": SHEET_ID
},
"metadataKey": "SalesUpdated"
},
"fields": "location,metadataKey"
}
}
]
}Risposta
{
"spreadsheetId": SPREADSHEET_ID,
"replies": [
{
"updateDeveloperMetadata": {
"developerMetadata": [
{
"metadataId": METADATA_ID,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": SHEET_ID
},
"visibility": "DOCUMENT"
}
]
}
}
]
}Elimina metadati
Per eliminare i metadati dello sviluppatore, utilizza il metodo
batchUpdate
e fornisci un
DeleteDeveloperMetadataRequest.
Devi specificare un
DataFilter per selezionare i
metadati da eliminare.
In questo esempio, forniamo l'ID metadati nella richiesta. La risposta restituisce i valori dei metadati dello sviluppatore per l'ID metadati.
Per verificare che i metadati dello sviluppatore siano stati rimossi, utilizza il metodo spreadsheets.developerMetadata.get specificando l'ID dei metadati eliminati. Dovresti ricevere una risposta con codice di stato HTTP 404: Not Found e un messaggio che indica "Nessun metadato dello sviluppatore con ID METADATA_ID.
Richiesta
{
"requests": [
{
"deleteDeveloperMetadata": {
"dataFilter": {
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
}
}
]
}Risposta
{
"spreadsheetId": SPREADSHEET_ID,
"replies": [
{
"deleteDeveloperMetadata": {
"deletedDeveloperMetadata": [
{
"metadataId": METADATA_ID,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": SHEET_ID
},
"visibility": "DOCUMENT"
}
]
}
}
]
}Leggere e scrivere i valori associati ai metadati
Puoi anche recuperare e aggiornare i valori delle celle in righe e colonne specificando
i metadati per sviluppatori associati e i valori che vuoi aggiornare. Per farlo,
utilizza uno dei seguenti metodi con un DataFilter corrispondente.
Ottieni i valori delle celle in base ai metadati
Per ottenere i valori delle celle in base ai metadati, utilizza il
metodo
spreadsheets.values.batchGetByDataFilter. Devi specificare l'ID foglio di lavoro e uno o più filtri dei dati che
corrispondono ai metadati.
In questo esempio, forniamo l'ID metadati nella richiesta. La risposta restituisce i valori delle celle della riga (numero di modello, vendite mensili) per l'ID metadati.
Richiesta
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
],
"majorDimension": "ROWS"
}Risposta
{
"spreadsheetId": SPREADSHEET_ID,
"valueRanges": [
{
"valueRange": {
"range": "Sheet7!A7:Z7",
"majorDimension": "ROWS",
"values": [
[
"W-24",
"74"
]
]
},
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
]
}
]
}Recuperare un foglio di lavoro in base ai metadati
Quando recuperi un foglio di lavoro, puoi restituire un sottoinsieme di dati utilizzando il metodo
spreadsheets.getByDataFilter. Devi specificare l'ID foglio di lavoro e uno o più filtri dei dati che
corrispondono ai metadati.
Questa richiesta funziona come una normale richiesta "GET foglio di lavoro", tranne per il fatto che l'elenco dei
metadati corrispondenti ai filtri dei dati specificati determina quali fogli, dati
della griglia e altre risorse oggetto con metadati vengono restituiti. Se
includeGridData
è impostato su true, per il foglio vengono restituiti anche i dati della griglia che intersecano gli intervalli della griglia specificati. Il campo includeGridData viene ignorato se nella richiesta è impostata una maschera del campo.
In questo esempio, forniamo l'ID metadati e impostiamo includeGridData su false nella richiesta. La risposta restituisce sia le proprietà del foglio di lavoro che quelle del foglio.
Richiesta
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
],
"includeGridData": false
}Risposta
{ "spreadsheetId": SPREADSHEET_ID, "properties": { "title": "Sales Sheet", "locale": "en_US", "autoRecalc": "ON_CHANGE", "timeZone": "America/Los_Angeles", "defaultFormat": { "backgroundColor": { "red": 1, "green": 1, "blue": 1 }, "padding": { "top": 2, "right": 3, "bottom": 2, "left": 3 }, "verticalAlignment": "BOTTOM", "wrapStrategy": "OVERFLOW_CELL", "textFormat": { "foregroundColor": {}, "fontFamily": "arial,sans,sans-serif", "fontSize": 10, "bold": false, "italic": false, "strikethrough": false, "underline": false, "foregroundColorStyle": { "rgbColor": {} } }, "backgroundColorStyle": { "rgbColor": { "red": 1, "green": 1, "blue": 1 } } }, "spreadsheetTheme": { "primaryFontFamily": "Arial", "themeColors": [ { "colorType": "TEXT", "color": { "rgbColor": {} } }, { "colorType": "BACKGROUND", "color": { "rgbColor": { "red": 1, "green": 1, "blue": 1 } } }, { "colorType": "ACCENT1", "color": { "rgbColor": { "red": 0.25882354, "green": 0.52156866, "blue": 0.95686275 } } }, { "colorType": "ACCENT2", "color": { "rgbColor": { "red": 0.91764706, "green": 0.2627451, "blue": 0.20784314 } } }, { "colorType": "ACCENT3", "color": { "rgbColor": { "red": 0.9843137, "green": 0.7372549, "blue": 0.015686275 } } }, { "colorType": "ACCENT4", "color": { "rgbColor": { "red": 0.20392157, "green": 0.65882355, "blue": 0.3254902 } } }, { "colorType": "ACCENT5", "color": { "rgbColor": { "red": 1, "green": 0.42745098, "blue": 0.003921569 } } }, { "colorType": "ACCENT6", "color": { "rgbColor": { "red": 0.27450982, "green": 0.7411765, "blue": 0.7764706 } } }, { "colorType": "LINK", "color": { "rgbColor": { "red": 0.06666667, "green": 0.33333334, "blue": 0.8 } } } ] } }, "sheets": [ { "properties": { "sheetId": SHEET_ID, "title": "Sheet7", "index": 7, "sheetType": "GRID", "gridProperties": { "rowCount": 1000, "columnCount": 26 } } } ], "spreadsheetUrl": SPREADSHEET_URL }
Aggiornare i valori in base ai metadati
Per aggiornare i valori delle celle corrispondenti a metadati specifici, utilizza il metodo
spreadsheets.values.batchUpdateByDataFilter. Devi specificare l'ID foglio di lavoro,
valueInputOption,
e uno o più valori
DataFilterValueRange
che corrispondono ai metadati.
In questo esempio, forniamo l'ID metadati e i valori delle righe aggiornati nella richiesta. La risposta restituisce sia le proprietà aggiornate sia i dati per l'ID metadati.
Richiesta
{
"data": [
{
"dataFilter": {
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
},
"majorDimension": "ROWS",
"values": [
[
"W-24",
"84"
]
]
}
],
"includeValuesInResponse": true,
"valueInputOption": "USER_ENTERED"
}Risposta
{
"spreadsheetId": SPREADSHEET_ID,
"totalUpdatedRows": 1,
"totalUpdatedColumns": 2,
"totalUpdatedCells": 2,
"totalUpdatedSheets": 1,
"responses": [
{
"updatedRange": "Sheet7!A7:B7",
"updatedRows": 1,
"updatedColumns": 2,
"updatedCells": 2,
"dataFilter": {
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
},
"updatedData": {
"range": "Sheet7!A7:Z7",
"majorDimension": "ROWS",
"values": [
[
"W-24",
"84"
]
]
}
}
]
}Cancella valori per metadati
Per cancellare i valori delle celle che corrispondono a metadati specifici, utilizza il metodo
spreadsheets.values.batchClearByDataFilter. Devi specificare un filtro dei dati per selezionare i metadati da cancellare.
Richiesta
In questo esempio, forniamo l'ID metadati nella richiesta. La risposta restituisce l'ID del foglio di lavoro e gli intervalli cancellati.
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
]
}Risposta
{
"spreadsheetId": SPREADSHEET_ID,
"clearedRanges": [
"Sheet7!A7:Z7"
]
}Limiti di archiviazione dei metadati
Esiste un limite alla quantità totale di metadati che puoi archiviare in un foglio di lavoro. Questo limite è misurato in caratteri ed è composto da due componenti:
| Elemento | Allocazione del limite di spazio di archiviazione |
|---|---|
| Foglio di lavoro | 30.000 caratteri |
| Ogni foglio all'interno di un foglio di lavoro | 30.000 caratteri |
Puoi memorizzare fino a 30.000 caratteri per il foglio di lavoro. Inoltre, puoi memorizzare 30.000 caratteri per ogni foglio all'interno di un foglio di lavoro (30.000 per il foglio uno, 30.000 per il foglio due e così via). Pertanto,un foglio di lavoro con tre fogli potrebbe contenere fino a 120.000 caratteri di metadati.
Ogni carattere nei campi metadataKey e metadataValue della risorsa
spreadsheets.developerMetadata
viene conteggiato ai fini di questo limite.