La funzionalità dei metadati dello sviluppatore ti consente di associare i metadati a varie entità e località 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.
I metadati dello sviluppatore ti consentono di eseguire operazioni quali:
Associa dati arbitrari a varie entità e posizioni 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 o attributo dei metadati: ad esempio, data la chiave
totalsassociata alla colonna D o datoresponseId, restituisce tutte le righe con i metadatiresponseIde il valore dei metadati associati.Trova tutti i dati associati a una determinata entità o località: ad esempio, data la colonna D, restituisce tutti i metadati associati a quella località.
Recupero dei valori in una posizione specificando i metadati associati: ad esempio, dato
totals, restituisce una rappresentazione dei valori contenuti nella riga o nella colonna associata oppure, datosummary, restituisce una rappresentazione della risorsa del foglio 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 dello sviluppatore associati a una posizione o a un oggetto in un foglio di lavoro.
Informazioni sui metadati dello sviluppatore
Questa sezione descrive alcuni aspetti chiave dei metadati dello sviluppatore da tenere presenti quando si utilizza l'API Fogli.
Metadati come tag
Un utilizzo dei metadati dello sviluppatore è un tag che assegna un nome a una posizione nel
foglio di lavoro utilizzando solo una chiave e una posizione. Ad esempio, puoi associare headerRow a una riga specifica o totals a una colonna specifica all'interno di un foglio. I tag possono essere utilizzati per associare semanticamente parti di un
spreadsheet ai campi di uno strumento o di un database di terze parti, in modo che le modifiche al
spreadsheet non causino l'interruzione dell'app.
Metadati come proprietà
I metadati creati specificando una chiave, una posizione e un valore fungono da una 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 archiviare e accedere a proprietà personalizzate con nome associate a aree o dati specifici in un foglio di lavoro.
Metadati visibili del progetto e del documento
Per impedire a un progetto dello sviluppatore di interferire con i metadati di un altro, esistono due impostazioni visibility dei metadati: project e document. Con l'API Fogli,
i metadati del progetto sono visibili e accessibili solo dal progetto sviluppatore che
li ha creati. I metadati dei documenti sono accessibili da qualsiasi progetto per sviluppatori con accesso al documento.
Le query che non specificano esplicitamente una visibilità restituiscono i metadati dei documenti e i metadati del progetto corrispondenti per il progetto sviluppatore che effettua la richiesta.
Unicità
Le chiavi dei metadati non devono essere univoche, ma metadataId deve essere distinta. 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 insiemi di metadati.
Crea metadati
Per creare metadati, utilizza il metodo
batchUpdate
e fornisci un
createDeveloperMetadataRequest con metadataKey, location e visibility. Se vuoi, puoi specificare 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.
Mostra un esempio
In questo esempio, forniamo una chiave, un valore e una riga nella richiesta. La risposta restituisce questi valori dei metadati dello sviluppatore, oltre all'ID metadati assegnato.
Richiedi
{
"requests": [
{
"createDeveloperMetadata": {
"developerMetadata": {
"location": {
"dimensionRange": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT",
"metadataKey": "Sales",
"metadataValue": "2022"
}
}
}
]
}Risposta
{
"spreadsheetId": spreadsheetId,
"replies": [
{
"createDeveloperMetadata": {
"developerMetadata": {
"metadataId": metadataId,
"metadataKey": "Sales",
"metadataValue": "2022",
"location": {
"locationType": "ROW",
"dimensionRange": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT"
}
}
}
]
}Leggere un singolo elemento dei metadati
Per recuperare un singolo metadato dello sviluppatore distinto, utilizza il metodo
spreadsheets.developerMetadata.get
specificando il spreadsheetId contenente i metadati e il metadataId univoco dei metadati dello sviluppatore.
Mostra un esempio
Richiedi
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/spreadsheetId/developerMetadata/metadataId
Risposta
{
"metadataId": metadataId,
"metadataKey": "Sales",
"metadataValue": "2022",
"location": {
"locationType": "ROW",
"dimensionRange": {
"sheetId": sheetId,
"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à.
Mostra un esempio
In questo esempio, forniamo più ID metadati nella richiesta. La risposta restituisce i valori dei metadati dello sviluppatore per ogni ID metadati.
Richiedi
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
},
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}Risposta
{
"matchedDeveloperMetadata": [
{
"developerMetadata": {
"metadataId": metadataId,
"metadataKey": "Revenue",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": sheetId
},
"visibility": "DOCUMENT"
},
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
},
{
"developerMetadata": {
"metadataId": metadataId,
"metadataKey": "Sales",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": sheetId
},
"visibility": "DOCUMENT"
},
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}
]
}Aggiorna metadati
Per aggiornare i metadati dello sviluppatore, utilizza il metodo
spreadsheets.batchUpdate
e fornisci un
UpdateDeveloperMetadataRequest.
Devi specificare un
DataFilter
che abbia come target i metadati da aggiornare, un
DeveloperMetadata
oggetto con i nuovi valori e una maschera di campo
che descriva i campi da aggiornare.
Mostra un esempio
In questo esempio, nella richiesta forniamo l'ID dei metadati, l'ID del foglio e una nuova chiave dei metadati. La risposta restituisce questi valori dei metadati dello sviluppatore, oltre alla chiave dei metadati aggiornata.
Richiedi
{
"requests": [
{
"updateDeveloperMetadata": {
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"developerMetadata": {
"location": {
"sheetId": sheetId
},
"metadataKey": "SalesUpdated"
},
"fields": "location,metadataKey"
}
}
]
}Risposta
{
"spreadsheetId": spreadsheetId,
"replies": [
{
"updateDeveloperMetadata": {
"developerMetadata": [
{
"metadataId": metadataId,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": sheetId
},
"visibility": "DOCUMENT"
}
]
}
}
]
}Eliminare i 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.
Mostra un esempio
In questo esempio, forniamo l'ID dei 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 il messaggio "Nessun metadato dello sviluppatore con ID metadataId".
Richiedi
{
"requests": [
{
"deleteDeveloperMetadata": {
"dataFilter": {
"developerMetadataLookup": {
"metadataId": metadataId
}
}
}
}
]
}Risposta
{
"spreadsheetId": spreadsheetId,
"replies": [
{
"deleteDeveloperMetadata": {
"deletedDeveloperMetadata": [
{
"metadataId": metadataId,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": sheetId
},
"visibility": "DOCUMENT"
}
]
}
}
]
}Leggere e scrivere i valori associati ai metadati
Puoi anche recuperare e aggiornare i valori delle celle nelle righe e nelle colonne specificando i metadati sviluppatore associati e i valori da aggiornare. Per farlo, utilizza il metodo appropriato riportato di seguito con un DataFilter corrispondente.
Recuperare i valori delle celle in base ai metadati
Per ottenere i valori delle celle in base ai metadati, utilizza il metodo spreadsheets.values.batchGetByDataFilter. Dovrai specificare l'ID del foglio di lavoro e uno o più filtri dati corrispondenti ai metadati.
Mostra un esempio
In questo esempio, forniamo l'ID dei metadati nella richiesta. La risposta restituisce i valori delle celle di riga (numero modello, vendite mensili) per l'ID dei metadati.
Richiedi
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"majorDimension": "ROWS"
}Risposta
{
"spreadsheetId": spreadsheetId,
"valueRanges": [
{
"valueRange": {
"range": "Sheet7!A7:Z7",
"majorDimension": "ROWS",
"values": [
[
"W-24",
"74"
]
]
},
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}
]
}Recuperare il foglio di lavoro in base ai metadati
Quando recuperi un foglio di lavoro, puoi restituire un sottoinsieme di dati utilizzando il metodo spreadsheets.getByDataFilter. Dovrai specificare l'ID del foglio di lavoro e uno o più filtri dati corrispondenti 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 dati specificati determina quali fogli, dati della griglia e altre risorse oggetto con metadati vengono restituiti. Se
includeGridData è impostato su true, vengono restituiti anche i dati della griglia che intersecano gli intervalli di riga specificati per il foglio.
Mostra un esempio
In questo esempio, forniamo l'ID dei metadati e impostiamo includeGridData su false nella richiesta. La risposta restituisce sia le proprietà del foglio di lavoro sia quelle del foglio.
Richiedi
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"includeGridData": false
}Risposta
{ "spreadsheetId": spreadsheetId, "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": sheetId, "title": "Sheet7", "index": 7, "sheetType": "GRID", "gridProperties": { "rowCount": 1000, "columnCount": 26 } } } ], "spreadsheetUrl": spreadsheetUrl }
Aggiornare i valori in base ai metadati
Per aggiornare i valori delle celle corrispondenti a metadati specifici, utilizza il metodo
spreadsheets.values.batchUpdateByDataFilter. Dovrai specificare l'ID del foglio di lavoro, valueInputOption, e uno o più DataFilterValueRange corrispondenti ai metadati.
Mostra un esempio
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.
Richiedi
{
"data": [
{
"dataFilter": {
"developerMetadataLookup": {
"metadataId": metadataId
}
},
"majorDimension": "ROWS",
"values": [
[
"W-24",
"84"
]
]
}
],
"includeValuesInResponse": true,
"valueInputOption": "USER_ENTERED"
}Risposta
{
"spreadsheetId": spreadsheetId,
"totalUpdatedRows": 1,
"totalUpdatedColumns": 2,
"totalUpdatedCells": 2,
"totalUpdatedSheets": 1,
"responses": [
{
"updatedRange": "Sheet7!A7:B7",
"updatedRows": 1,
"updatedColumns": 2,
"updatedCells": 2,
"dataFilter": {
"developerMetadataLookup": {
"metadataId": metadataId
}
},
"updatedData": {
"range": "Sheet7!A7:Z7",
"majorDimension": "ROWS",
"values": [
[
"W-24",
"84"
]
]
}
}
]
}Cancellare i valori in base ai metadati
Per cancellare i valori delle celle corrispondenti a metadati specifici, utilizza il metodo spreadsheets.values.batchClearByDataFilter. Devi specificare un filtro dati per selezionare i metadati da cancellare.
Mostra un esempio
Richiedi
In questo esempio, forniamo l'ID dei metadati nella richiesta. La risposta restituisce l'ID del foglio di lavoro e gli intervalli cancellati.
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}Risposta
{
"spreadsheetId": spreadsheetId,
"clearedRanges": [
"Sheet7!A7:Z7"
]
}Limiti di spazio 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 primo foglio, 30.000 per il secondo e così via). Pertanto,un foglio di lavoro con 3 pagine potrebbe contenere fino a 120.000 caratteri di metadati per gli sviluppatori.
Ogni carattere degli attributi chiave e valore di un oggetto developerMetadata viene conteggiato ai fini di questo limite.