La funzionalità dei metadati dello sviluppatore 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 un foglio di lavoro.
I metadati dello sviluppatore ti consentono di eseguire operazioni come:
Associa 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 tutti i dati associati a una determinata chiave o attributo dei metadati: ad esempio, se viene data la chiave
totalsassociata alla colonna D o la colonnaresponseId, restituisce tutte le righe con i metadatiresponseIde il valore dei metadati associato.Trovare tutti i dati associati a una determinata entità o località: ad esempio, in base alla colonna D, vengono restituiti tutti i metadati associati alla località.
Recuperare i valori in una posizione specificando i metadati associati: ad esempio, se
totalsrestituisce una rappresentazione dei valori contenuti nella colonna o nella riga associata o sesummaryrestituisce una rappresentazione della risorsa Fogli associata.Aggiornare i valori in una posizione specificando i metadati associati. Ad esempio, invece di aggiornare i valori di una riga tramite la notazione A1, aggiorna i valori indicando un ID metadati.
Leggi e scrivi 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 che dovresti prendere in considerazione quando lavori con 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 determinata riga o totals a
una determinata colonna all'interno di un foglio. I tag possono essere utilizzati per associare semanticamente parti di un foglio di lavoro ai campi di uno strumento o database di terze parti, in modo che le modifiche al foglio di lavoro non danneggino la tua app.
Metadati come proprietà
I metadati creati specificando una chiave, una località 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 archiviare e accedere alle proprietà con nome personalizzato associate ad aree o dati specifici in un foglio di lavoro.
Metadati visibili del progetto e dei documenti
Per evitare che un progetto sviluppatore interferisca con i metadati di un altro, sono disponibili due impostazioni visibility per i metadati: project e document. Utilizzando l'API Fogli, i metadati del progetto sono visibili e accessibili solo dal progetto dello sviluppatore che li ha creati. I metadati del documento sono accessibili da qualsiasi progetto
degli sviluppatori che ha accesso al documento.
Le query che non specificano in modo esplicito una visibilità restituiscono metadati del documento corrispondenti e metadati di progetto corrispondenti per il progetto sviluppatore che effettua la richiesta.
Unicità
Le chiavi dei metadati non devono essere univoche, ma metadataId deve essere distinto. Se crei metadati e non specifichi il relativo campo ID, 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 gli insiemi di metadati.
Creare metadati
Per creare i metadati, usa il metodo
batchUpdate
e fornisci una
createDeveloperMetadataRequest con metadataKey, location e visibility. Facoltativamente, 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 di metadati dello sviluppatore, più l'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"
}
}
}
]
}
Lettura di un singolo elemento di metadati
Per recuperare un singolo metadati dello sviluppatore distinti, usa il metodo spreadsheets.developerMetadata.get, specificando il valore spreadsheetId contenente i metadati e il valore 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"
}
Lettura di più elementi di metadati
Per recuperare più elementi dei metadati dello sviluppatore, usa il metodo spreadsheets.developerMetadata.search. Devi specificare un elemento DataFilter che corrisponda a tutti i metadati esistenti in qualsiasi combinazione di proprietà come 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, usa il metodo spreadsheets.batchUpdate e fornisci un UpdateDeveloperMetadataRequest.
Dovrai specificare un elemento DataFilter che abbia come target i metadati da aggiornare, un oggetto DeveloperMetadata con i nuovi valori e una maschera di campo che descriva i campi da aggiornare.
Mostra un esempio
In questo esempio, forniamo l'ID metadati, l'ID foglio e una nuova chiave di metadati nella richiesta. La risposta restituisce questi valori di metadati dello sviluppatore, oltre alla chiave di 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"
}
]
}
}
]
}
Elimina metadati
Per eliminare i metadati dello sviluppatore, usa 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 metadati nella richiesta. La risposta restituisce i valori dei metadati dello sviluppatore per l'ID metadati.
Per verificare che i metadati dello sviluppatore vengano 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, con il messaggio "Nessun metadati 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"
}
]
}
}
]
}
Valori di lettura e scrittura 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 che vuoi aggiornare. A questo scopo, utilizza il metodo appropriato di seguito con un valore DataFilter corrispondente.
Ottenere 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 del foglio di lavoro e uno o più filtri dati che corrispondono ai metadati.
Mostra un esempio
In questo esempio, forniamo l'ID metadati nella richiesta. La risposta restituisce i valori delle celle di riga (numero modello, vendite mensili) per l'ID 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
}
}
]
}
]
}
Ottieni 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 del foglio di lavoro e uno o più filtri dati che corrispondono ai metadati.
Questa richiesta funziona come una normale richiesta "GET fogli di lavoro", ad eccezione del fatto che l'elenco di metadati corrispondenti ai filtri dati specificati determina quali fogli, dati di griglia e altre risorse degli oggetti con metadati vengono restituiti. Se includeGridData è impostato su true, per il foglio vengono restituiti anche i dati della griglia che si intersecano gli intervalli della griglia specificati.
Mostra un esempio
In questo esempio, forniamo l'ID 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
}
Aggiorna i valori in base ai metadati
Per aggiornare i valori delle celle che corrispondono a metadati specifici, utilizza il metodo spreadsheets.values.batchUpdateByDataFilter. Devi specificare l'ID del foglio di lavoro, valueInputOption e uno o più DataFilterValueRange che corrispondono ai metadati.
Mostra un esempio
In questo esempio, forniamo l'ID metadati e i valori di riga 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"
]
]
}
}
]
}
Cancella valori in base ai metadati
Per cancellare i valori delle celle che corrispondono a metadati specifici, utilizza il metodo spreadsheets.values.batchClearByDataFilter. Dovrai specificare un filtro dati per selezionare i metadati da cancellare.
Mostra un esempio
Richiedi
In questo esempio, forniamo l'ID metadati nella richiesta. La risposta restituisce l'ID foglio di lavoro e gli intervalli cancellati.
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}
Risposta
{
"spreadsheetId": spreadsheetId,
"clearedRanges": [
"Sheet7!A7:Z7"
]
}
Limiti di archiviazione dei metadati
Esiste un limite alla quantità totale di metadati che puoi memorizzare in un foglio di lavoro. Questo limite viene misurato in caratteri ed è costituito 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 2 e così via). Un foglio di lavoro con 3 pagine potrebbe contenere fino a 120.000 caratteri di metadati dello sviluppatore.
Ciascun carattere negli attributi chiave e valore di un oggetto developerMetadata viene conteggiato ai fini di questo limite.