Mit der Funktion für Entwicklermetadaten können Sie Metadaten mit verschiedenen Entitäten und Standorten in einer Tabelle verknüpfen. Sie können diese Metadaten dann abfragen und anhand der Ergebnisse die zugehörigen Objekte ermitteln.
Sie können Metadaten mit Zeilen, Spalten, Blättern oder einer Tabelle verknüpfen.
Mit Entwicklermetadaten können Sie unter anderem folgende Vorgänge ausführen:
Beliebige Daten mit verschiedenen Entitäten und Speicherorten in einer Tabelle verknüpfen, z. B.
totalsmit Spalte D oderresponseId = 1234mit Zeile 7.Alle Speicherorte und Daten finden, die mit einem bestimmten Metadatenschlüssel oder ‑attribut verknüpft sind: Wenn Sie beispielsweise den Schlüssel
totalsangeben, der mit Spalte D verknüpft ist, oderresponseId, werden alle Zeilen mit den MetadatenresponseIdund dem zugehörigen Metadatenwert zurückgegeben.Alle Daten zu einer bestimmten Entität oder einem bestimmten Standort finden: Beispiel: In Spalte D werden alle Metadaten zurückgegeben, die mit diesem Standort verknüpft sind.
Werte an einem Speicherort abrufen, indem zugehörige Metadaten angegeben werden: Wenn Sie beispielsweise
totalsangeben, wird eine Darstellung der Werte in der zugehörigen Spalte oder Zeile zurückgegeben. Wenn Siesummaryangeben, wird eine Darstellung der zugehörigen Tabellenressource zurückgegeben.Werte an einem Speicherort durch Angabe der zugehörigen Metadaten aktualisieren: Anstatt die Werte in einer Zeile über die A1-Notation zu aktualisieren, können Sie sie auch durch Angabe einer Metadaten-ID aktualisieren.
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 Google Tabellen API berücksichtigen sollten.
Metadaten als Tags
Eine Verwendung von Entwicklermetadaten ist ein Tag, das einen Standort in der Tabelle nur mit einem Schlüssel und einem Standort benennt. Sie können beispielsweise headerRow mit einer bestimmten Zeile oder totals mit einer bestimmten Spalte in einem Tabellenblatt verknüpfen. Mithilfe von Tags können Sie Teile einer Tabelle semantisch mit Feldern in einem Drittanbietertool oder einer Drittanbieterdatenbank verknüpfen, sodass Änderungen an der Tabelle Ihre App nicht beeinträchtigen.
Metadaten als Properties
Metadaten, die durch Angabe eines Schlüssels, eines Speicherorts und eines Werts erstellt werden, dienen als Schlüssel/Wert-Paar, das diesem Speicherort in einem Tabellenblatt zugeordnet ist. Sie können beispielsweise Folgendes verknüpfen:
formResponseId = resp123mit einer ZeilelastUpdated = 1477369882mit einer Spalte.
So können Sie benutzerdefinierte benannte Properties speichern und auf diese zugreifen, die mit bestimmten Bereichen oder Daten in einer Tabelle verknüpft sind.
Sichtbare Metadaten für Projekte und Dokumente
Damit ein Entwicklerprojekt nicht die Metadaten eines anderen Projekts beeinträchtigt, gibt es zwei visibility-Metadateneinstellungen: project und document. Mit der Google Tabellen API sind Projektmetadaten nur im Entwicklerprojekt sichtbar und zugänglich, in dem sie erstellt wurden. Auf Dokumentmetadaten kann über jedes Entwicklerprojekt zugegriffen werden, das Zugriff auf das Dokument hat.
Bei Abfragen, für die keine Sichtbarkeit explizit angegeben ist, werden übereinstimmende Dokument- und Projektmetadaten für das Entwicklerprojekt zurückgegeben, das die Anfrage stellt.
Eindeutigkeit
Metadatenschlüssel müssen nicht eindeutig sein, aber die metadataId müssen unterschiedlich sein. Wenn Sie Metadaten erstellen und das ID-Feld leer lassen, wird es von der API zugewiesen. Mit dieser ID können die Metadaten identifiziert werden, 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 metadataKey, location und visibility an. Optional können Sie 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, wird eine von der API zugewiesen.
Beispiel ansehen
In diesem Beispiel geben wir in der Anfrage einen Schlüssel, einen Wert und eine Zeile an. Die Antwort enthält diese Entwicklermetadatenwerte sowie die zugewiesene Metadaten-ID.
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 Entwicklermetadaten abrufen möchten, verwenden Sie die Methode spreadsheets.developerMetadata.get und geben Sie die spreadsheetId mit den Metadaten und die eindeutige metadataId der Entwicklermetadaten an.
Beispiel ansehen
Anfrage
In diesem Beispiel geben wir die Tabellen-ID und die Metadaten-ID in der Anfrage an. Die Antwort gibt die Entwicklermetadatenwerte 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
Wenn Sie mehrere Entwicklermetadatenelemente abrufen möchten, verwenden Sie die Methode spreadsheets.developerMetadata.search. Sie müssen einen DataFilter angeben, der mit allen vorhandenen Metadaten für eine beliebige Kombination von Eigenschaften wie Schlüssel, Wert, Standort oder Sichtbarkeit übereinstimmt.
Beispiel ansehen
In diesem Beispiel geben wir mehrere Metadaten-IDs in der Anfrage an. Die Antwort enthält die Entwicklermetadatenwerte für jede Metadaten-ID.
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 von Entwicklermetadaten die Methode spreadsheets.batchUpdate und geben Sie UpdateDeveloperMetadataRequest an.
Sie müssen ein DataFilter angeben, das auf die zu aktualisierenden Metadaten ausgerichtet ist, ein DeveloperMetadata-Objekt mit den neuen Werten und eine Feldmaske, 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. Die Antwort enthält diese Entwicklermetadatenwerte sowie den aktualisierten Metadatenschlüssel.
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 die Methode batchUpdate und geben Sie eine DeleteDeveloperMetadataRequest an, um Entwicklermetadaten zu löschen.
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. Die Antwort gibt die Entwicklermetadatenwerte für die Metadaten-ID zurück.
Verwenden Sie die Methode spreadsheets.developerMetadata.get, um zu prüfen, ob die Entwicklermetadaten entfernt wurden. Geben Sie dabei die gelöschte Metadaten-ID an. Sie sollten eine Antwort mit dem HTTP-Statuscode 404: Not Found und der Meldung „Keine Entwicklermetadaten mit der ID metadataId“ erhalten.
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 Werte angeben, die Sie aktualisieren möchten. Verwenden Sie dazu eine der folgenden Methoden mit einer passenden DataFilter.
Zellenwerte anhand von Metadaten abrufen
Wenn Sie Zellenwerte nach Metadaten abrufen möchten, verwenden Sie die Methode spreadsheets.values.batchGetByDataFilter. 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. Die Antwort gibt die Werte der Zeilenzellen (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 anhand von Metadaten abrufen
Wenn Sie eine Tabelle abrufen, können Sie mit der Methode spreadsheets.getByDataFilter einen Teil 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 normale GET-Anfrage für Tabellenblätter, mit der Ausnahme, dass anhand der Liste der Metadaten, die mit den angegebenen Datenfiltern übereinstimmen, bestimmt wird, welche Tabellen, Tabellendaten und anderen Objektressourcen mit Metadaten zurückgegeben werden. Wenn includeGridData auf „wahr“ gesetzt ist, werden auch Rasterdaten zurückgegeben, die sich mit den angegebenen Rasterbereichen überschneiden.
Beispiel ansehen
In diesem Beispiel geben wir die Metadaten-ID an und legen in der Anfrage fest, dass „includeGridData“ auf „false“ gesetzt werden soll. Die Antwort enthält sowohl die Tabellen- als auch die Tabelleneigenschaften.
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 anhand von Metadaten aktualisieren
Wenn Sie Zellenwerte aktualisieren möchten, die bestimmten Metadaten entsprechen, verwenden Sie die Methode spreadsheets.values.batchUpdateByDataFilter. Sie müssen die Tabellen-ID, valueInputOption, und eine oder mehrere DataFilterValueRange angeben, die mit den Metadaten übereinstimmen.
Beispiel ansehen
In diesem Beispiel geben wir die Metadaten-ID und die aktualisierten Zeilenwerte in der Anfrage an. Die Antwort enthält sowohl die aktualisierten Properties als auch die Daten für die Metadaten-ID.
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
Wenn Sie Zellenwerte löschen möchten, die bestimmten Metadaten entsprechen, verwenden Sie die Methode spreadsheets.values.batchClearByDataFilter. Sie müssen einen Datenfilter angeben, um die Metadaten auszuwählen, die Sie löschen möchten.
Beispiel ansehen
Anfrage
In diesem Beispiel geben wir die Metadaten-ID in der Anfrage an. Die Antwort enthält die Tabellen-ID und die gelöschten Bereiche.
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}Antwort
{
"spreadsheetId": spreadsheetId ,
"clearedRanges": [
"Sheet7!A7:Z7"
]
}Limits für den Metadatenspeicher
Die Gesamtmenge der Metadaten, die Sie in einer Tabelle speichern können, ist begrenzt. Diese Grenze wird in Zeichen gemessen und besteht aus zwei Komponenten:
| Element | Zuweisung des Speicherlimits |
|---|---|
| Tabelle | 30.000 Zeichen |
| Jedes Tabellenblatt in einer Tabelle | 30.000 Zeichen |
Sie können bis zu 30.000 Zeichen in der Tabelle speichern. Außerdem können Sie in jeder Tabelle einer Tabelle 30.000 Zeichen speichern (30.000 für Tabelle 1, 30.000 für Tabelle 2 usw.). Eine Tabelle mit drei Seiten kann also bis zu 120.000 Zeichen an Entwicklermetadaten enthalten.
Jedes Zeichen in den Schlüssel- und Wertattributen eines developerMetadata-Objekts wird auf dieses Limit angerechnet.