Mit der Metadatenfunktion können Sie Metadaten mit verschiedenen Entitäten und Speicherorten in einer Tabelle verknüpfen. Sie können diese Metadaten dann abfragen und damit die Objekte finden, mit denen sie verknüpft sind.
Sie können Metadaten mit Zeilen, Spalten, Tabellenblättern oder einer Tabelle verknüpfen.
Metadaten
Im Folgenden werden einige wichtige Aspekte von Metadaten beschrieben, die Sie bei der Arbeit mit der Sheets API berücksichtigen sollten:
Metadaten als Tags: Eine Verwendung von Entwicklermetadaten ist ein Tag, mit dem ein Speicherort in der Tabelle nur mit einem Schlüssel und einem Speicherort benannt wird. Sie können beispielsweise
headerRowmit einer bestimmten Zeile odertotalsmit 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 App nicht beeinträchtigen.Metadaten als Attribute: Metadaten, die durch 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. Beispiele:
formResponseId = resp123mit einer Zeile verknüpfenlastUpdated = 1477369882mit einer Spalte verknüpfen
So können Sie benutzerdefinierte benannte Attribute speichern und darauf zugreifen, die mit bestimmten Bereichen oder Daten in einer Tabelle verknüpft sind.
Metadaten auf Projekt- und Dokumentebene: Damit ein Entwickler projekt die Metadaten eines anderen Projekts nicht beeinträchtigt, gibt es zwei Metadaten
visibilityEinstellungen:projectunddocument. Mit der Sheets API sindproject-Metadaten nur im Google Cloud-Projekt sichtbar und zugänglich, in dem sie erstellt wurden. Aufdocument-Metadaten kann von jedem Google Cloud-Projekt aus zugegriffen werden, das Zugriff auf das Dokument hat.Bei Abfragen, in denen keine
visibilityangegeben ist, werden übereinstimmendedocument-Metadaten und übereinstimmendeproject-Metadaten für das Google Cloud-Projekt zurückgegeben, das die Anfrage stellt.Eindeutigkeit: Metadatenschlüssel müssen nicht eindeutig sein, aber die
metadataIdmuss eindeutig sein. Wenn Sie Metadaten erstellen und das Feld für die ID nicht angeben, wird von der API eine ID zugewiesen. Diese ID kann verwendet werden, um die Metadaten zu identifizieren. Schlüssel und andere Attribute können verwendet werden, um Metadatensätze zu identifizieren.Metadaten über API-Anfragen zurückgeben: Ein
DataFilter-Objekt ist Teil eines API-Aufrufs, der die Daten beschreibt, die in einer API-Anfrage ausgewählt oder zurückgegeben werden sollen.Ein einzelnes
DataFilter-Objekt kann nur einen Typ von Filterkriterien angeben, um Daten zu finden:developerMetadataLookup: Wählt Daten aus, die mit den angegebenen Entwicklermetadaten übereinstimmen.a1Range: Wählt Daten aus, die mit dem angegebenen Bereich in A1 Notation übereinstimmen. Beispiel:Sheet1!A1:B10.gridRange: Wählt Daten aus, die mit dem angegebenen Bereich im Raster übereinstimmen. Dabei werden nullbasierte Indizes verwendet. Beispiel:Sheet1!A3:B4 == sheetId: 123456, startRowIndex: 2, endRowIndex: 4, startColumnIndex: 0, endColumnIndex: 2.
Wenn Sie nach mehreren Speicherorten oder Kriterien filtern möchten, können Sie in einer einzelnen API-Anfrage mehrere
DataFilterObjekte verwenden. Geben Sie ein Array oder eine Liste vonDataFilterObjekten für eine Batchanfrage wie diespreadsheets.values.batchGetByDataFilterMethode an. Alle Bereiche, die mit einem der Datenfilter in der Anfrage übereinstimmen, werden zurückgegeben oder geändert.Weitere Informationen finden Sie unter Werte lesen und schreiben, die mit Metadaten verknüpft sind.
Anwendungsfälle
Im Folgenden sind einige Anwendungsfälle für die Verwaltung von Metadaten aufgeführt:
Beliebige Daten mit verschiedenen Entitäten und Speicherorten in einer Tabelle verknüpfen: Verknüpfen Sie beispielsweise
totalsmit Spalte D oderresponseId = 1234mit Zeile 7.Alle Speicherorte und Daten finden, die mit einem bestimmten Metadatenschlüssel oder Attribut verknüpft sind: Wenn beispielsweise der Schlüssel
totalsmit Spalte D verknüpft ist oder dieresponseIdangegeben ist, geben Sie alle Zeilen mit denresponseId-Metadaten und dem zugehörigen Metadatenwert zurück.Alle Daten finden, die mit einer bestimmten Entität oder einem bestimmten Speicherort verknüpft sind: Wenn beispielsweise Spalte D angegeben ist, geben Sie alle Metadaten zurück, die mit diesem Speicherort verknüpft sind.
Werte an einem Speicherort abrufen, indem Sie die zugehörigen Metadaten angeben: Wenn beispielsweise
totalsangegeben ist, geben Sie eine Darstellung der Werte in der zugehörigen Spalte oder Zeile zurück. Wennsummaryangegeben ist, geben Sie eine Darstellung der zugehörigen Tabellenblattressource zurück.Werte an einem Speicherort aktualisieren, indem Sie die zugehörigen Metadaten angeben: Aktualisieren Sie beispielsweise die Werte in einer Zeile nicht über die A1 Notation, sondern über eine Metadaten-ID.
Metadaten lesen und schreiben
Die
spreadsheets.developerMetadata
Ressource bietet Zugriff auf Metadaten, die mit einem Speicherort oder Objekt in einer
Tabelle verknüpft sind. Mit Entwicklermetadaten können beliebige Daten mit verschiedenen Teilen einer Tabelle verknüpft werden. Die Metadaten bleiben an diesen Speicherorten verknüpft, wenn die Tabelle bearbeitet wird.
Metadaten erstellen
Verwenden Sie zum Erstellen von Metadaten die
batchUpdate
Methode für die
spreadsheets Ressource
und geben Sie eine
CreateDeveloperMetadataRequest
mit metadataKey, location und visibility Werten aus der
spreadsheets.developerMetadata Ressource an. Optional können Sie eine metadataValue oder eine explizite metadataId angeben.
Wenn Sie eine bereits verwendete ID angeben, schlägt die Anfrage fehl. Wenn Sie keine ID angeben, wird von der API eine ID zugewiesen.
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": SHEET_ID,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT",
"metadataKey": "Sales",
"metadataValue": "2022"
}
}
}
]
}Antwort
{
"spreadsheetId": SPREADSHEET_ID,
"replies": [
{
"createDeveloperMetadata": {
"developerMetadata": {
"metadataId": METADATA_ID,
"metadataKey": "Sales",
"metadataValue": "2022",
"location": {
"locationType": "ROW",
"dimensionRange": {
"sheetId": SHEET_ID,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT"
}
}
}
]
}Einzelnes Metadatenelement lesen
Verwenden Sie die
spreadsheets.developerMetadata.get
Methode, um einzelne, eindeutige Entwicklermetadaten abzurufen. Geben Sie dazu die spreadsheetId mit den Metadaten und die eindeutige metadataId der Entwickler
metadaten an.
Anfrage
In diesem Beispiel geben wir in der Anfrage die Tabellen-ID und die Metadaten-ID an. Die Antwort enthält die Entwicklermetadatenwerte für die Metadaten-ID.
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/developerMetadata/METADATA_ID
Antwort
{
"metadataId": METADATA_ID,
"metadataKey": "Sales",
"metadataValue": "2022",
"location": {
"locationType": "ROW",
"dimensionRange": {
"sheetId": SHEET_ID,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT"
}Mehrere Metadatenelemente lesen
Verwenden Sie die
spreadsheets.developerMetadata.search
Methode, um mehrere Elemente von Entwicklermetadaten abzurufen. Sie müssen ein
DataFilter angeben, das mit
vorhandenen Metadaten für eine beliebige Kombination von Attributen wie Schlüssel, Wert, Speicherort oder Sichtbarkeit übereinstimmt.
In diesem Beispiel geben wir in der Anfrage mehrere Metadaten-IDs an. Die Antwort enthält die Entwicklermetadatenwerte für jede Metadaten-ID.
Anfrage
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
},
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
]
}Antwort
{
"matchedDeveloperMetadata": [
{
"developerMetadata": {
"metadataId": METADATA_ID,
"metadataKey": "Revenue",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": SHEET_ID
},
"visibility": "DOCUMENT"
},
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
]
},
{
"developerMetadata": {
"metadataId": METADATA_ID,
"metadataKey": "Sales",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": SHEET_ID
},
"visibility": "DOCUMENT"
},
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
]
}
]
}Metadaten aktualisieren
Verwenden Sie die
spreadsheets.batchUpdate
Methode und geben Sie eine
UpdateDeveloperMetadataRequestan, um Entwicklermetadaten zu aktualisieren.
Sie müssen ein
DataFilter angeben, das auf
die zu aktualisierenden Metadaten ausgerichtet ist, eine
spreadsheets.developerMetadata
Ressource mit den neuen Werten und eine Feld
maske, die die zu
aktualisierenden Felder beschreibt.
In diesem Beispiel geben wir in der Anfrage die Metadaten-ID, die Tabellenblatt-ID und einen neuen Metadatenschlüssel an. Die Antwort enthält diese Entwicklermetadatenwerte sowie den aktualisierten Metadatenschlüssel.
Anfrage
{
"requests": [
{
"updateDeveloperMetadata": {
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
],
"developerMetadata": {
"location": {
"sheetId": SHEET_ID
},
"metadataKey": "SalesUpdated"
},
"fields": "location,metadataKey"
}
}
]
}Antwort
{
"spreadsheetId": SPREADSHEET_ID,
"replies": [
{
"updateDeveloperMetadata": {
"developerMetadata": [
{
"metadataId": METADATA_ID,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": SHEET_ID
},
"visibility": "DOCUMENT"
}
]
}
}
]
}Metadaten löschen
Verwenden Sie die
batchUpdate
Methode und geben Sie eine
DeleteDeveloperMetadataRequestan, um Entwicklermetadaten zu löschen.
Sie müssen einen
DataFilter angeben, um die
zu löschenden Metadaten auszuwählen.
In diesem Beispiel geben wir in der Anfrage die Metadaten-ID an. Die Antwort enthält die Entwicklermetadatenwerte für die Metadaten-ID.
Verwenden Sie die spreadsheets.developerMetadata.get
Methode und geben Sie die gelöschte Metadaten-ID an, um zu bestätigen, dass die Entwicklermetadaten entfernt wurden. Sie sollten eine HTTP-Antwort mit dem HTTP-Statuscode 404: Not Found und der Meldung „No developer metadata with ID METADATA_ID“ erhalten.
Anfrage
{
"requests": [
{
"deleteDeveloperMetadata": {
"dataFilter": {
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
}
}
]
}Antwort
{
"spreadsheetId": SPREADSHEET_ID,
"replies": [
{
"deleteDeveloperMetadata": {
"deletedDeveloperMetadata": [
{
"metadataId": METADATA_ID,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": SHEET_ID
},
"visibility": "DOCUMENT"
}
]
}
}
]
}Werte lesen und schreiben, die mit Metadaten verknüpft sind
Sie können auch Zellwerte 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 einem passenden
DataFilter.
Zellwerte nach Metadaten abrufen
Verwenden Sie die
spreadsheets.values.batchGetByDataFilter
Methode, um Zellwerte nach Metadaten abzurufen. Sie müssen die Tabellen-ID und einen oder mehrere Datenfilter angeben, die mit den Metadaten übereinstimmen.
In diesem Beispiel geben wir in der Anfrage die Metadaten-ID an. Die Antwort enthält die Zellwerte der Zeile (Modellnummer, monatlicher Umsatz) für die Metadaten-ID.
Anfrage
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
],
"majorDimension": "ROWS"
}Antwort
{
"spreadsheetId": SPREADSHEET_ID,
"valueRanges": [
{
"valueRange": {
"range": "Sheet7!A7:Z7",
"majorDimension": "ROWS",
"values": [
[
"W-24",
"74"
]
]
},
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
]
}
]
}Tabelle nach Metadaten abrufen
Wenn Sie eine Tabelle abrufen, können Sie mit der
spreadsheets.getByDataFilter
Methode 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 normale „spreadsheet GET“-Anfrage. Die Liste der Metadaten, die mit den angegebenen Datenfiltern übereinstimmen, bestimmt jedoch, welche Tabellenblätter, Rasterdaten und andere Objektdaten mit Metadaten zurückgegeben werden. Wenn
includeGridData
auf true gesetzt ist, werden auch Rasterdaten zurückgegeben, die sich mit den angegebenen Rasterbereichen überschneiden. Das Feld includeGridData wird ignoriert, wenn in der Anfrage eine Feld
maske festgelegt ist.
In diesem Beispiel geben wir in der Anfrage die Metadaten-ID an und setzen includeGridData auf false. Die Antwort enthält sowohl die Tabellen- als auch die Tabellenblattattribute.
Anfrage
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
],
"includeGridData": false
}Antwort
{ "spreadsheetId": SPREADSHEET_ID, "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": SHEET_ID, "title": "Sheet7", "index": 7, "sheetType": "GRID", "gridProperties": { "rowCount": 1000, "columnCount": 26 } } } ], "spreadsheetUrl": SPREADSHEET_URL }
Werte nach Metadaten aktualisieren
Verwenden Sie die
spreadsheets.values.batchUpdateByDataFilter
Methode, um Zellwerte zu aktualisieren, die mit bestimmten Metadaten übereinstimmen. Sie müssen die Tabellen-ID angeben,
valueInputOption,
und einen oder mehrere
DataFilterValueRange
Werte, die mit den Metadaten übereinstimmen.
In diesem Beispiel geben wir in der Anfrage die Metadaten-ID und die aktualisierten Zeilenwerte an. Die Antwort enthält sowohl die aktualisierten Attribute als auch die Daten für die Metadaten-ID.
Anfrage
{
"data": [
{
"dataFilter": {
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
},
"majorDimension": "ROWS",
"values": [
[
"W-24",
"84"
]
]
}
],
"includeValuesInResponse": true,
"valueInputOption": "USER_ENTERED"
}Antwort
{
"spreadsheetId": SPREADSHEET_ID,
"totalUpdatedRows": 1,
"totalUpdatedColumns": 2,
"totalUpdatedCells": 2,
"totalUpdatedSheets": 1,
"responses": [
{
"updatedRange": "Sheet7!A7:B7",
"updatedRows": 1,
"updatedColumns": 2,
"updatedCells": 2,
"dataFilter": {
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
},
"updatedData": {
"range": "Sheet7!A7:Z7",
"majorDimension": "ROWS",
"values": [
[
"W-24",
"84"
]
]
}
}
]
}Werte nach Metadaten löschen
Verwenden Sie die
spreadsheets.values.batchClearByDataFilter
Methode, um Zellwerte zu löschen, die mit bestimmten Metadaten übereinstimmen. Sie müssen einen Datenfilter angeben, um die zu löschenden Metadaten auszuwählen.
Anfrage
In diesem Beispiel geben wir in der Anfrage die Metadaten-ID an. Die Antwort enthält die Tabellen-ID und die gelöschten Bereiche.
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
]
}Antwort
{
"spreadsheetId": SPREADSHEET_ID,
"clearedRanges": [
"Sheet7!A7:Z7"
]
}Speicherlimits für Metadaten
Es gibt ein Limit für die Gesamtmenge an Metadaten, die Sie in einer Tabelle speichern können. Dieses Limit wird in Zeichen gemessen und besteht aus zwei Komponenten:
| Element | Speicherlimit |
|---|---|
| Tabelle | 30.000 Zeichen |
| Jedes Tabellenblatt in einer Tabelle | 30.000 Zeichen |
Sie können bis zu 30.000 Zeichen für die Tabelle speichern. Außerdem können Sie 30.000 Zeichen für jedes Tabellenblatt in einer Tabelle speichern (30.000 für Tabellenblatt 1, 30.000 für Tabellenblatt 2 usw.). Eine Tabelle mit drei Tabellenblättern kann also bis zu 120.000 Zeichen an Metadaten enthalten.
Jedes Zeichen in den metadataKey und metadataValue Feldern der
spreadsheets.developerMetadata
Ressource wird auf dieses Limit angerechnet.