La funzionalità dei metadati dello sviluppatore consente di associare i metadati a varie entità e le posizioni in un foglio di lavoro. Puoi quindi eseguire query su questi metadati e utilizzarli per per trovare gli oggetti a cui è associato.
Puoi associare i metadati a righe, colonne, fogli o fogli di lavoro.
I metadati dello sviluppatore ti consentono di eseguire operazioni quali:
Associare dati arbitrari a varie entità e posizioni in un foglio di lavoro: ad esempio, associa
totalsalla colonna D oppureresponseId = 1234con riga 7.Trovare tutte le posizioni e tutti i dati associati a una determinata chiave di metadati o : ad esempio, data la chiave
totalsassociata con la colonna D o conresponseId, restituisce tutte le righe conresponseIde il relativo valore associato.Trovare tutti i dati associati a una determinata entità o località: ad esempio, una determinata colonna D restituisce tutti i metadati associati. in ogni località.
Recuperare i valori in una località specificando i metadati associati: ad esempio, se
totalsrestituisce una rappresentazione dei valori contenuto nella colonna o nella riga associata o in un valoresummaryrestituisce un della risorsa Fogli associata.Aggiornare i valori in una posizione specificando i metadati associati. Ad esempio, invece di aggiornare i valori in una riga tramite la notazione A1, aggiorna i valori indicando un ID metadati.
Leggi e scrittura metadati
La risorsa spreadsheets.developerMetadata fornisce 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 quando si utilizza l'API Fogli.
Metadati come tag
Un utilizzo dei metadati dello sviluppatore è un tag che indica una posizione nella
utilizzando solo una chiave e una posizione. Per
Ad esempio, puoi associare headerRow a una determinata riga o totals a
a una determinata colonna all'interno di un foglio. I tag possono essere usati per associare semanticamente parti di un
ai campi di uno strumento o di un database di terze parti, pertanto le modifiche
un foglio di lavoro non comprometterà la tua app.
Metadati come proprietà
I metadati creati specificando una chiave, una posizione e un valore funzionano come una coppia chiave-valore associata a quella posizione in un foglio. Ad esempio, puoi associare:
formResponseId = resp123con una rigalastUpdated = 1477369882con una colonna.
Questo ti consente di archiviare e accedere a nomi personalizzati proprietà associate ad aree o dati specifici in un foglio di lavoro.
Metadati visibili di progetto o documenti
Per evitare che un progetto sviluppatore interferisca con i metadati di un altro, è necessario
sono disponibili due impostazioni di visibility dei metadati: project e document. Con l'API Fogli,
I metadati di progetto sono visibili e accessibili solo dal progetto sviluppatore che
l'ha creato. I metadati dei documenti sono accessibili da qualsiasi progetto di sviluppatori con
per accedere al documento.
Le query che non specificano in modo esplicito una visibilità restituiscono metadati dei documenti corrispondenti e metadati di progetto corrispondenti per dal progetto dello sviluppatore che esegue la richiesta.
Unicità
Le chiavi dei metadati non devono essere univoche, ma il valore metadataId deve essere
distinti. Se crei metadati e non specifichi il relativo campo ID, il valore
L'API ne assegna uno. Questo ID può essere utilizzato per identificare
mentre le chiavi e altri attributi consentono di identificare
metadati.
Crea metadati
Per creare i metadati, utilizza
batchUpdate
e fornisce un
createDeveloperMetadataRequest con metadataKey, location e visibility. In via facoltativa,
specificare un metadataValue o un metadataId esplicito.
Se specifichi un ID già in uso, la richiesta non andrà a buon fine. In caso contrario fornisce 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 di metadati
Per recuperare singoli metadati dello sviluppatore, 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, nella richiesta forniamo l'ID foglio di lavoro e l'ID metadati. 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"
}
Leggi più elementi di metadati
Per recuperare più elementi dei metadati dello sviluppatore, utilizza il metodo
spreadsheets.developerMetadata.search
. Devi specificare un elemento DataFilter che corrisponda a tutti i metadati esistenti su qualsiasi
combinazione di proprietà come chiave, valore, posizione o visibilità.
Mostra un esempio
In questo esempio, forniamo nella richiesta più ID metadati. 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 fornisce un
UpdateDeveloperMetadataRequest.
Dovrai specificare
DataFilter
che ha come target i metadati da aggiornare, una
DeveloperMetadata
con i nuovi valori e una maschera del campo
che descrive i campi da aggiornare.
Mostra un esempio
In questo esempio, vengono forniti l'ID metadati, l'ID foglio e una nuova chiave di metadati nella richiesta. 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"
}
]
}
}
]
}
Elimina metadati
Per eliminare i metadati dello sviluppatore, utilizza la proprietà
batchUpdate
e fornisce un
DeleteDeveloperMetadataRequest.
Dovrai specificare un DataFilter per selezionare i metadati che vuoi
eliminare.
Mostra un esempio
In questo esempio, nella richiesta viene fornito l'ID metadati. 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 comando spreadsheets.developerMetadata.get
che specifica l'ID dei metadati eliminati. Dovresti ricevere una risposta del codice di stato HTTP 404: Not Found, con 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"
}
]
}
}
]
}
Leggi e scrivere valori associati ai metadati
Puoi anche recuperare e aggiornare i valori delle celle nelle righe e nelle colonne specificando lo sviluppatore associato
metadati e i valori che vuoi aggiornare. Per farlo, utilizza il metodo appropriato di seguito con un
corrispondenza di DataFilter.
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 del foglio di lavoro e uno o più filtri dati che corrispondano ai metadati.
Mostra un esempio
In questo esempio, nella richiesta viene fornito l'ID metadati. La risposta restituisce i valori delle celle della riga (numero di 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 il foglio di lavoro in base ai metadati
Durante il recupero di 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 corrispondano ai metadati.
Questa richiesta funziona come un normale "GET foglio di lavoro" ad eccezione di
dei metadati corrispondenti ai filtri dati specificati determina quali fogli,
vengono restituiti i dati della griglia e altre risorse dell'oggetto con metadati. Se
includeGridData è impostato su true, i dati della griglia si intersecano negli intervalli della griglia specificati
viene restituito anche per il foglio.
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 corrispondano 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 spreadsheets.values.batchClearByDataFilter . Per selezionare i metadati da cancellare, devi specificare un filtro dati.
Mostra un esempio
Richiedi
In questo esempio, nella richiesta viene fornito l'ID metadati. 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 archiviare in un foglio di lavoro. Questo limite viene misurato in caratteri ed è composto da due componenti:
| Elemento | Allocazione dei limiti 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 di un foglio di lavoro (30.000 per il foglio uno, 30.000 per il foglio 2 e così via). Quindi un foglio di lavoro con 3 le pagine possono contenere fino a 120.000 caratteri di metadati dello sviluppatore.
Ogni carattere negli attributi chiave e valore di un oggetto developerMetadata.
vengono conteggiate ai fini di questo limite.