Lettura e scrittura dei metadati dello sviluppatore

La funzionalità dei metadati dello sviluppatore 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.

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 totals alla colonna D o responseId = 1234 alla 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 totals associata alla colonna D o dato responseId, restituisci tutte le righe con i metadati responseId e 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.

• Recuperare i valori in una posizione specificando i metadati associati: ad esempio, dato totals, restituisce una rappresentazione dei valori contenuti nella colonna o nella riga associata oppure, dato summary, restituisce una rappresentazione della risorsa Foglio associata.

• Aggiorna 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.

Lettura e scrittura dei 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 considerare quando si utilizza l'API Sheets.

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 foglio di lavoro a campi in uno strumento o database di terze parti, in modo che le modifiche al foglio di lavoro non interrompano la tua 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 = resp123 con una riga
• lastUpdated = 1477369882 con una colonna.

In questo modo puoi memorizzare e accedere a proprietà denominate personalizzate associate a particolari aree o dati 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: project e document. Utilizzando l'API Sheets, i metadati del progetto sono visibili e accessibili solo dal progetto sviluppatore che li ha creati. I metadati del documento sono accessibili da qualsiasi progetto sviluppatore con accesso al documento.

Le query che non specificano esplicitamente una visibilità restituiscono i metadati del documento corrispondenti e i metadati del progetto corrispondenti per il progetto dello sviluppatore che effettua la richiesta.

Non utilizzare i metadati dello sviluppatore visibili al progetto come meccanismo di sicurezza o per archiviare i secret. I metadati potrebbero essere esposti agli utenti con accesso in visualizzazione al documento.

Unicità

Le chiavi dei metadati non devono essere univoche, ma il metadataId deve 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 chiavi e altri attributi possono essere utilizzati per identificare i set di metadati.

Anche se puoi specificare un `metadataId` personalizzato durante la creazione dei metadati, ti consigliamo di consentire al servizio Fogli di assegnarne uno per te.

Crea metadati

Per creare metadati, utilizza il metodo batchUpdate e fornisci un createDeveloperMetadataRequest con metadataKey, location e visibility. 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": 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 un singolo metadato dello sviluppatore distinto, utilizza il metodo spreadsheets.developerMetadata.get, specificando il 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/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 eventuali metadati esistenti 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": 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. Dovrai specificare un DataFilter che ha come target i metadati da aggiornare, un oggetto DeveloperMetadata con i nuovi valori e una maschera del 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": 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 il metodo batchUpdate e fornisci un DeleteDeveloperMetadataRequest. Devi specificare un DataFilter per selezionare i metadati che vuoi 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 metadataId.

Richiesta

{
  "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 in righe e colonne specificando i metadati dello sviluppatore associati e i valori che vuoi aggiornare. Per farlo, utilizza il metodo appropriato riportato di seguito 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. Dovrai 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": metadataId
      }
    }
  ],
  "majorDimension": "ROWS"
}

Risposta

{
  "spreadsheetId": spreadsheetId,
  "valueRanges": [
    {
      "valueRange": {
        "range": "Sheet7!A7:Z7",
        "majorDimension": "ROWS",
        "values": [
          [
            "W-24",
            "74"
          ]
        ]
      },
      "dataFilters": [
        {
          "developerMetadataLookup": {
            "metadataId": metadataId
          }
        }
      ]
    }
  ]
}

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. Dovrai 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.

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": 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 foglio di lavoro, valueInputOption, e uno o più 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": 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 per metadati

Per cancellare i valori delle celle corrispondenti 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 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 è 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 1, 30.000 per il foglio 2 e così via). Pertanto,un foglio di lavoro con tre pagine può contenere fino a 120.000 caratteri di metadati dello sviluppatore.

Ogni carattere negli attributi chiave e valore di un oggetto developerMetadata viene conteggiato ai fini di questo limite.

Questi limiti potrebbero cambiare in futuro.