Mit der Metadatenfunktion für Entwickler können Sie Metadaten mit verschiedenen Entitäten verknüpfen. und Standorte in einer Tabelle. Sie können diese Metadaten dann abfragen die damit verbundenen Objekte zu finden.
Sie können Metadaten mit Zeilen, Spalten, Tabellenblättern oder einer Tabelle verknüpfen.
Mit Entwicklermetadaten können Sie u. a. folgende Vorgänge ausführen:
Verknüpfung beliebiger Daten mit verschiedenen Entitäten und Orten in einem Tabelle: Verknüpfen Sie
totalsmit Spalte D oderresponseId = 1234durch Zeile 7.Sie können nach allen Standorten und Daten suchen, die mit einem bestimmten Metadatenschlüssel oder Attribut – z. B. angesichts des Schlüssels
totals, der mit mit Spalte D oder bei Angabe derresponseIdwerden alle Zeilen zurückgegeben, dieresponseId-Metadaten und der zugehörige Metadatenwert.Alle Daten suchen, die mit einer bestimmten Entität oder einem bestimmten Standort verknüpft sind: So werden bei Spalte D z. B. alle Metadaten zurückgegeben, die dieser Entität Standort.
Werte an einem Standort durch Angabe zugehöriger Metadaten abrufen: Wenn z. B.
totalseine Darstellung der Werte zurückgibt die in der verknüpften Spalte oder Zeile enthalten sind oder bei denensummaryzurückgegeben wird, Darstellung der zugehörigen Tabellenressource.Werte an einem Standort durch Angabe zugehöriger Metadaten aktualisieren: Anstatt die Werte in einer Zeile in A1-Notation zu aktualisieren, aktualisieren Sie Werte, indem Sie eine Metadaten-ID angeben.
Lesen und Metadaten schreiben
Die Ressource spreadsheets.developerMetadata bietet Zugriff auf Entwicklermetadaten, die mit einem Standort oder Objekt in einer Tabelle verknüpft sind.
Entwicklermetadaten
In diesem Abschnitt werden einige wichtige Aspekte von Entwicklermetadaten beschrieben, die Sie die Sie bei der Arbeit mit der Sheets API berücksichtigen sollten.
Metadaten als Tags
Entwicklermetadaten können beispielsweise ein Tag verwenden, das einen Standort im
Tabelle mit nur einem Schlüssel
und einem Ort verwenden. Für
Sie können beispielsweise headerRow mit einer bestimmten Zeile oder totals mit
Spalte in einem Tabellenblatt. Mithilfe von Tags können Teile einer
Tabelle in Feldern in einem Tool oder einer Datenbank
eines Drittanbieters an, sodass Änderungen an der
Tabelle wird Ihre App nicht beschädigt.
Metadaten als Attribute
Metadaten, die durch die Angabe eines Schlüssels, eines Speicherorts und eines Werts erstellt werden, fungieren als Schlüssel/Wert-Paar, das dieser Position in einer Tabelle zugeordnet ist. Sie können beispielsweise Folgendes verknüpfen:
formResponseId = resp123mit einer ZeilelastUpdated = 1477369882durch eine Spalte.
So können Sie benutzerdefinierte Eigenschaften, die mit bestimmten Gebieten oder Daten in einer Tabelle verknüpft sind.
Sichtbare Metadaten von Projekten und Dokumenten
Um zu verhindern, dass Metadaten eines Entwicklerprojekts
bei einem anderen Projekt gestört werden,
sind zwei Metadaten-visibility-Einstellungen: project und document. Mit der Sheets API
Projektmetadaten nur über das Entwicklerprojekt sichtbar und zugänglich sind,
haben sie erstellt. Dokumentmetadaten sind in jedem Entwicklerprojekt mit
auf das Dokument zugreifen können.
Bei Abfragen, bei denen nicht explizit eine Sichtbarkeit angegeben wird, werden übereinstimmende Dokumentmetadaten und übereinstimmende Projektmetadaten für den Entwicklerprojekt, von dem die Anfrage stammt.
Eindeutigkeit
Metadatenschlüssel müssen nicht eindeutig sein, metadataId aber schon.
unterschiedlich sein. Wenn Sie Metadaten erstellen und das ID-Feld nicht angeben, wird der
API eine. Anhand dieser ID kann das
Metadaten, während mit Schlüsseln und anderen Attributen Gruppen von
Metadaten.
Metadaten erstellen
Verwenden Sie zum Erstellen von Metadaten die Methode
batchUpdate
und geben eine
createDeveloperMetadataRequest mit metadataKey, location und visibility. Sie können optional
einen metadataValue oder einen expliziten metadataId angeben.
Wenn Sie eine ID angeben, die bereits verwendet wird, schlägt die Anfrage fehl. Wenn Sie keine eine ID angeben, weist das API eine zu.
Beispiel ansehen
In diesem Beispiel geben wir in der Anfrage einen Schlüssel, einen Wert und eine Zeile an. In der Antwort werden diese Entwicklermetadatenwerte plus die zugewiesene Metadaten-ID zurückgegeben.
Anfrage
{
"requests": [
{
"createDeveloperMetadata": {
"developerMetadata": {
"location": {
"dimensionRange": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT",
"metadataKey": "Sales",
"metadataValue": "2022"
}
}
}
]
}
Antwort
{
"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"
}
}
}
]
}
Einzelnes Metadatenelement lesen
Um einzelne, eindeutige Entwicklermetadaten abzurufen, verwenden Sie die Methode
spreadsheets.developerMetadata.get
und geben die spreadsheetId an, die die Metadaten enthält, und die eindeutige metadataId der Entwicklermetadaten.
Beispiel ansehen
Anfrage
In diesem Beispiel geben wir die Tabellen-ID und die Metadaten-ID in der Anfrage an. Die Antwort gibt die Werte der Entwicklermetadaten für die Metadaten-ID zurück.
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/developerMetadata/metadataId
Antwort
{
"metadataId": metadataId,
"metadataKey": "Sales",
"metadataValue": "2022",
"location": {
"locationType": "ROW",
"dimensionRange": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT"
}
Mehrere Metadatenelemente lesen
Verwenden Sie zum Abrufen mehrerer Elemente der Entwicklermetadaten die Methode
spreadsheets.developerMetadata.search
. Sie müssen einen DataFilter angeben, der mit vorhandenen Metadaten auf einer
Kombination von Eigenschaften wie Schlüssel, Wert, Standort oder Sichtbarkeit.
Beispiel ansehen
In diesem Beispiel geben wir in der Anfrage mehrere Metadaten-IDs an. In der Antwort werden die Werte der Entwicklermetadaten für jede Metadaten-ID zurückgegeben.
Anfrage
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
},
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}
Antwort
{
"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
}
}
]
}
]
}
Metadaten aktualisieren
Entwicklermetadaten kannst du mit dem
spreadsheets.batchUpdate
und geben eine
UpdateDeveloperMetadataRequest
Sie müssen eine
DataFilter
das auf die zu aktualisierenden Metadaten abzielt,
DeveloperMetadata
-Objekt mit den neuen Werten und einer Feldmaske
mit der Beschreibung der zu aktualisierenden Felder.
Beispiel ansehen
In diesem Beispiel geben wir die Metadaten-ID, die Tabellenblatt-ID und einen neuen Metadatenschlüssel in der Anfrage an. In der Antwort werden diese Entwicklermetadatenwerte plus den aktualisierten Metadatenschlüssel zurückgegeben.
Anfrage
{
"requests": [
{
"updateDeveloperMetadata": {
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"developerMetadata": {
"location": {
"sheetId": sheetId
},
"metadataKey": "SalesUpdated"
},
"fields": "location,metadataKey"
}
}
]
}
Antwort
{
"spreadsheetId": spreadsheetId,
"replies": [
{
"updateDeveloperMetadata": {
"developerMetadata": [
{
"metadataId": metadataId,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": sheetId
},
"visibility": "DOCUMENT"
}
]
}
}
]
}
Metadaten löschen
Entwicklermetadaten kannst du mit dem
batchUpdate
und geben eine
DeleteDeveloperMetadataRequest.
Sie müssen einen DataFilter angeben, um die Metadaten auszuwählen, die Sie
Löschen.
Beispiel ansehen
In diesem Beispiel geben wir die Metadaten-ID in der Anfrage an. Die Antwort gibt die Werte der Entwicklermetadaten für die Metadaten-ID zurück.
Mit spreadsheets.developerMetadata.get kannst du prüfen, ob die Entwicklermetadaten entfernt wurden.
unter Angabe der gelöschten Metadaten-ID. Du solltest eine Antwort mit dem HTTP-Statuscode 404: Not Found mit der Meldung "Keine Entwicklermetadaten mit der ID metadataId.
Anfrage
{
"requests": [
{
"deleteDeveloperMetadata": {
"dataFilter": {
"developerMetadataLookup": {
"metadataId": metadataId
}
}
}
}
]
}
Antwort
{
"spreadsheetId": spreadsheetId,
"replies": [
{
"deleteDeveloperMetadata": {
"deletedDeveloperMetadata": [
{
"metadataId": metadataId,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": sheetId
},
"visibility": "DOCUMENT"
}
]
}
}
]
}
Lesen und Werte schreiben, die mit Metadaten verknüpft sind
Sie können Zellenwerte in Zeilen und Spalten auch abrufen und aktualisieren, indem Sie den zugehörigen Entwickler
Metadaten und die Werte, die Sie aktualisieren möchten. Verwenden Sie dazu die entsprechende Methode unten mit einem
Übereinstimmung mit DataFilter.
Zellenwerte nach Metadaten abrufen
Verwenden Sie zum Abrufen von Zellenwerten nach Metadaten die Methode spreadsheets.values.batchGetByDataFilter . Sie müssen die Tabellen-ID und einen oder mehrere Datenfilter angeben, die den Metadaten entsprechen.
Beispiel ansehen
In diesem Beispiel geben wir die Metadaten-ID in der Anfrage an. Die Antwort gibt die Zeilenzellenwerte (Modellnummer, monatliche Verkäufe) für die Metadaten-ID zurück.
Anfrage
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"majorDimension": "ROWS"
}
Antwort
{
"spreadsheetId": spreadsheetId,
"valueRanges": [
{
"valueRange": {
"range": "Sheet7!A7:Z7",
"majorDimension": "ROWS",
"values": [
[
"W-24",
"74"
]
]
},
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}
]
}
Tabelle nach Metadaten abrufen
Beim Abrufen einer Tabellenkalkulation können Sie eine Teilmenge von Daten zurückgeben, indem Sie die Methode spreadsheets.getByDataFilter . Sie müssen die Tabellen-ID und einen oder mehrere Datenfilter angeben, die den Metadaten entsprechen.
Diese Anforderung funktioniert wie eine reguläre GET-Anfrage für die Tabelle. mit Ausnahme der Anfrage
Mit einer Liste der Metadaten, die den
angegebenen Datenfiltern entsprechen, wird festgelegt,
Rasterdaten und andere Objektressourcen mit Metadaten zurückgegeben. Wenn
includeGridData ist auf „true“ gesetzt und Rasterdaten überschneiden sich mit den angegebenen Rasterbereichen.
für das Tabellenblatt zurückgegeben.
Beispiel ansehen
In diesem Beispiel geben wir die Metadaten-ID an und setzen includeGridData in der Anfrage auf false. Die Antwort gibt sowohl die Tabellen- als auch die Tabellenblatteigenschaften zurück.
Anfrage
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"includeGridData": false
}
Antwort
{
"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
}
Werte nach Metadaten aktualisieren
Verwenden Sie zum Aktualisieren von Zellenwerten, die bestimmten Metadaten entsprechen, die Methode
spreadsheets.values.batchUpdateByDataFilter
. Gib die Tabellen-ID, valueInputOption und mindestens einen DataFilterValueRange-Wert an, der mit den Metadaten übereinstimmt.
Beispiel ansehen
In diesem Beispiel geben wir die Metadaten-ID und die aktualisierten Zeilenwerte in der Anfrage an. In der Antwort werden sowohl die aktualisierten Eigenschaften als auch die Daten für die Metadaten-ID zurückgegeben.
Anfrage
{
"data": [
{
"dataFilter": {
"developerMetadataLookup": {
"metadataId": metadataId
}
},
"majorDimension": "ROWS",
"values": [
[
"W-24",
"84"
]
]
}
],
"includeValuesInResponse": true,
"valueInputOption": "USER_ENTERED"
}
Antwort
{
"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"
]
]
}
}
]
}
Werte nach Metadaten löschen
Verwenden Sie den Filter spreadsheets.values.batchClearByDataFilter, um Zellenwerte zu löschen, die mit bestimmten Metadaten übereinstimmen . Zur Auswahl der zu löschenden Metadaten müssen Sie einen Datenfilter angeben.
Beispiel ansehen
Anfrage
In diesem Beispiel geben wir die Metadaten-ID in der Anfrage an. In der Antwort werden die Tabellen-ID und die gelöschten Bereiche zurückgegeben.
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}
Antwort
{
"spreadsheetId": spreadsheetId,
"clearedRanges": [
"Sheet7!A7:Z7"
]
}
Speicherlimits für Metadaten
Es gibt eine Beschränkung für die Gesamtmenge der Metadaten, die in einer Tabelle gespeichert werden können. Dieses Limit wird in Zeichen gemessen und setzt sich aus zwei Komponenten zusammen:
| Element | Speicherlimit zuweisen |
|---|---|
| Tabelle | 30.000 Zeichen |
| Jedes Tabellenblatt innerhalb einer Tabellenkalkulation | 30.000 Zeichen |
Sie können bis zu 30.000 Zeichen für die Tabelle speichern. Außerdem können Sie 30.000 Zeichen pro Blatt in einer Tabelle speichern (30.000 Zeichen für Blatt eins, 30.000 für Blatt2 usw.). Eine Tabellenkalkulation mit 3 -Seiten können bis zu 120.000 Zeichen an Entwicklermetadaten enthalten.
Jedes Zeichen in den Schlüssel- und Wertattributen eines developerMetadata-Objekts
werden auf dieses Limit angerechnet.