Mit der Funktion für Entwicklermetadaten können Sie Metadaten mit verschiedenen Entitäten und Orten in einer Tabelle verknüpfen. Anschließend können Sie diese Metadaten abfragen und damit die Objekte ermitteln, mit denen sie verknüpft sind.
Sie können Metadaten mit Zeilen, Spalten, Tabellenblättern oder einer Tabelle verknüpfen.
Mit Entwicklermetadaten können Sie beispielsweise folgende Vorgänge ausführen:
Beliebige Daten mit verschiedenen Entitäten und Orten in einer Tabelle verknüpfen: Verknüpfen Sie beispielsweise
totalsmit Spalte D oderresponseId = 1234mit Zeile 7.Alle Standorte und Daten suchen, die mit einem bestimmten Metadatenschlüssel oder Attribut verknüpft sind: Wenn beispielsweise der Schlüssel
totalsder Spalte D oder derresponseIdzugeordnet ist, werden alle Zeilen mit den MetadatenresponseIdund dem zugehörigen Metadatenwert zurückgegeben.Alle Daten suchen, die mit einer bestimmten Entität oder einem bestimmten Standort verknüpft sind: In Spalte D werden beispielsweise alle Metadaten zurückgegeben, die mit diesem Standort verknüpft sind.
Werte an einem Ort durch Angabe verknüpfter Metadaten abrufen: Wenn
totalsbeispielsweise eine Darstellung der Werte in der zugehörigen Spalte oder Zeile odersummaryeine Darstellung der verknüpften Tabellenressource zurückgibt.Werte an einem Standort durch Angabe zugehöriger Metadaten aktualisieren: Anstatt die Werte in einer Zeile mithilfe der A1-Notation in einer Zeile zu aktualisieren, werden die Werte beispielsweise durch Angabe einer Metadaten-ID aktualisiert.
Metadaten lesen und 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 bei der Arbeit mit der Sheets API berücksichtigen sollten.
Metadaten als Tags
Entwicklermetadaten werden zum Beispiel mit einem Tag verwendet, das einen Speicherort in der Tabelle nur mit einem Schlüssel und einem Standort benennt. So können Sie beispielsweise headerRow mit einer bestimmten Zeile oder totals mit einer bestimmten Spalte in einem Tabellenblatt verknüpfen. Tags können verwendet werden, um Teile einer Tabelle semantisch an Felder in einem Drittanbietertool oder einer Datenbank zu binden, sodass Änderungen an der Tabelle Ihre Anwendung nicht beeinträchtigen.
Metadaten als Properties
Metadaten, die durch die Angabe eines Schlüssels, eines Speicherorts und eines Werts erstellt werden, fungieren als Schlüssel/Wert-Paar, das mit diesem Speicherort in einem Tabellenblatt verknüpft ist. Sie können beispielsweise Folgendes verknüpfen:
formResponseId = resp123mit einer ZeilelastUpdated = 1477369882durch eine Spalte.
So können Sie benutzerdefinierte benannte Eigenschaften, die mit bestimmten Bereichen oder Daten verknüpft sind, in einer Tabelle speichern und darauf zugreifen.
Sichtbare Metadaten für Projekt oder Dokument
Um zu verhindern, dass ein Entwicklerprojekt die Metadaten eines anderen Projekts beeinträchtigt, gibt es zwei visibility-Metadateneinstellungen: project und document. Mit der Sheets API sind Projektmetadaten nur in dem Entwicklerprojekt sichtbar und zugänglich, in dem sie erstellt wurden. Auf die Metadaten von Dokumenten kann von jedem Entwicklerprojekt aus zugegriffen werden, das Zugriff auf das Dokument hat.
Bei Abfragen, für die keine Sichtbarkeit angegeben wird, werden übereinstimmende Dokumentmetadaten und Projektmetadaten des Entwicklerprojekts zurückgegeben, von dem die Anfrage stammt.
Eindeutigkeit
Metadatenschlüssel müssen nicht eindeutig sein, aber der metadataId muss eindeutig sein. Wenn Sie Metadaten erstellen und das ID-Feld nicht angegeben ist, weist die API eine solche zu. Diese ID kann verwendet werden, um die Metadaten zu identifizieren, während Schlüssel und andere Attribute zum Identifizieren von Metadatensätzen verwendet werden können.
Metadaten erstellen
Verwenden Sie zum Erstellen von Metadaten die Methode batchUpdate und geben Sie eine createDeveloperMetadataRequest mit einem metadataKey, location und einem visibility an. Sie können optional eine metadataValue oder eine explizite metadataId angeben.
Wenn Sie eine ID angeben, die bereits verwendet wird, schlägt die Anfrage fehl. Wenn Sie keine ID angeben, weist die API eine zu.
Beispiel ansehen
In diesem Beispiel geben wir einen Schlüssel, einen Wert und eine Zeile in der Anfrage an. In der Antwort werden diese Entwicklermetadatenwerte und 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
Wenn Sie einzelne, unterschiedliche Entwicklermetadaten abrufen möchten, verwenden Sie die Methode spreadsheets.developerMetadata.get und geben dabei die spreadsheetId mit den Metadaten und den eindeutigen metadataId der Entwicklermetadaten an.
Beispiel ansehen
Anfrage
In diesem Beispiel geben wir die Tabellen-ID und die Metadaten-ID in der Anfrage an. In der Antwort werden die Werte der Entwicklermetadaten für die Metadaten-ID zurückgegeben.
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
Mit der Methode spreadsheets.developerMetadata.search können Sie mehrere Elemente mit Entwicklermetadaten abrufen. Sie müssen einen DataFilter angeben, der mit allen vorhandenen Metadaten einer Kombination von Attributen wie Schlüssel, Wert, Standort oder Sichtbarkeit übereinstimmt.
Beispiel ansehen
In diesem Beispiel werden in der Anfrage mehrere Metadaten-IDs angegeben. In der Antwort werden für jede Metadaten-ID die Werte der Entwicklermetadaten 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
Verwenden Sie zum Aktualisieren der Entwicklermetadaten die Methode spreadsheets.batchUpdate und geben Sie eine UpdateDeveloperMetadataRequest an.
Sie müssen eine DataFilter für die zu aktualisierenden Metadaten, ein DeveloperMetadata-Objekt mit den neuen Werten und eine Feldmaske angeben, die die zu aktualisierenden Felder beschreibt.
Beispiel ansehen
In diesem Beispiel geben wir in der Anfrage die Metadaten-ID, die Tabellen-ID und einen neuen Metadatenschlüssel an. In der Antwort werden diese Entwicklermetadatenwerte sowie der aktualisierte 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
Verwenden Sie zum Löschen von Entwicklermetadaten die Methode batchUpdate und geben Sie eine DeleteDeveloperMetadataRequest an.
Sie müssen eine DataFilter angeben, um die Metadaten auszuwählen, die Sie löschen möchten.
Beispiel ansehen
In diesem Beispiel geben wir die Metadaten-ID in der Anfrage an. In der Antwort werden die Werte der Entwicklermetadaten für die Metadaten-ID zurückgegeben.
Wenn Sie prüfen möchten, ob die Entwicklermetadaten entfernt wurden, verwenden Sie die Methode spreadsheets.developerMetadata.get und geben die ID der gelöschten Metadaten an. 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"
}
]
}
}
]
}
Mit Metadaten verknüpfte Werte lesen und schreiben
Sie können auch Zellenwerte in Zeilen und Spalten abrufen und aktualisieren, indem Sie die zugehörigen Entwicklermetadaten und die zu aktualisierenden Werte angeben. Verwenden Sie dazu die entsprechende Methode unten mit einer übereinstimmenden DataFilter.
Zellenwerte nach Metadaten abrufen
Mit der Methode spreadsheets.values.batchGetByDataFilter können Sie Zellenwerte anhand von Metadaten abrufen. Sie müssen die Tabellen-ID und einen oder mehrere Datenfilter angeben, die mit den Metadaten übereinstimmen.
Beispiel ansehen
In diesem Beispiel geben wir die Metadaten-ID in der Anfrage an. In der Antwort werden die Zeilenzellenwerte (Modellnummer, monatliche Verkäufe) für die Metadaten-ID zurückgegeben.
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 Tabelle können Sie mit der Methode spreadsheets.getByDataFilter eine Teilmenge der Daten zurückgeben. Sie müssen die Tabellen-ID und einen oder mehrere Datenfilter angeben, die mit den Metadaten übereinstimmen.
Diese Anfrage funktioniert wie eine reguläre "Tabellen-GET"-Anfrage, mit dem Unterschied, dass durch die Liste der Metadaten, die den angegebenen Datenfiltern entsprechen, bestimmt wird, welche Tabellenblätter, Rasterdaten und anderen Objektressourcen mit Metadaten zurückgegeben werden. Wenn includeGridData auf „true“ gesetzt ist, werden für das Tabellenblatt auch Rasterdaten zurückgegeben, die sich mit den angegebenen Rasterbereichen überschneiden.
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
Mit der Methode spreadsheets.values.batchUpdateByDataFilter können Sie Zellenwerte aktualisieren, die mit bestimmten Metadaten übereinstimmen. Du musst die Tabellen-ID, valueInputOption und mindestens eine DataFilterValueRange angeben, die mit den Metadaten übereinstimmt.
Beispiel ansehen
In diesem Beispiel geben wir die Metadaten-ID und aktualisierte Zeilenwerte in der Anfrage an. In der Antwort werden sowohl die aktualisierten Attribute 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 die Methode spreadsheets.values.batchClearByDataFilter, um Zellenwerte zu löschen, die mit bestimmten Metadaten übereinstimmen. Du musst einen Datenfilter angeben, um die Metadaten auszuwählen, die du löschen möchtest.
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
Die Gesamtzahl der Metadaten, die in einer Tabelle gespeichert werden können, ist begrenzt. Diese Beschränkung wird in Zeichen angegeben und besteht aus zwei Komponenten:
| Artikel | Zuweisung von Speicherlimits |
|---|---|
| Tabelle | 30.000 Zeichen |
| Jedes Tabellenblatt in einer Tabellenkalkulation | 30.000 Zeichen |
Die Tabelle kann bis zu 30.000 Zeichen speichern. Außerdem können Sie für jedes Tabellenblatt in einer Tabelle 30.000 Zeichen speichern (30.000 für Blatt 1, 30.000 für Blatt 2 und so weiter). Eine dreiseitige Tabelle kann also bis zu 120.000 Zeichen an Entwicklermetadaten enthalten.
Auf dieses Limit wird jedes Zeichen in den Schlüssel- und Wertattributen eines developerMetadata-Objekts angerechnet.