Metadaten lesen und schreiben

Mit der Metadatenfunktion können Sie Metadaten verschiedenen Einheiten und Orten in einer Tabelle zuordnen. 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, Tabellen oder einer Tabelle verknüpfen.

Sie können Metadaten generieren, um Vorgänge wie die folgenden auszuführen:

  • Beliebige Daten mit verschiedenen Einheiten und Standorten in einer Tabelle verknüpfen: Sie können beispielsweise totals mit Spalte D oder responseId = 1234 mit Zeile 7 verknüpfen.

  • Alle Standorte und Daten, die einem bestimmten Metadatenschlüssel oder Attribut zugeordnet sind, finden: Wenn beispielsweise der Schlüssel totals der Spalte D zugeordnet ist oder die responseId angegeben ist, werden alle Zeilen mit den responseId-Metadaten und dem zugehörigen Metadatenwert zurückgegeben.

  • Alle Daten abrufen, die mit einer bestimmten Einheit oder einem bestimmten Ort verknüpft sind: Wenn beispielsweise Spalte D angegeben ist, werden alle Metadaten zurückgegeben, die mit diesem Ort verknüpft sind.

  • Werte an einem Ort abrufen, indem zugehörige Metadaten angegeben werden: Wenn Sie beispielsweise totals angeben, wird eine Darstellung der Werte in der zugehörigen Spalte oder Zeile zurückgegeben. Wenn Sie summary angeben, wird eine Darstellung der zugehörigen Tabellenblattressource zurückgegeben.

  • Werte an einem Ort aktualisieren, indem zugehörige Metadaten angegeben werden: Anstatt beispielsweise die Werte in einer Zeile über die A1-Notation zu aktualisieren, können Sie eine Metadaten-ID angeben.

Metadaten lesen und schreiben

Über die Ressource spreadsheets.developerMetadata haben Sie Zugriff auf Metadaten, die mit einem Ort oder Objekt in einer Tabelle verknüpft sind.

Metadaten

In diesem Abschnitt werden einige wichtige Aspekte von Metadaten beschrieben, die Sie bei der Arbeit mit der Sheets API berücksichtigen sollten.

  1. Metadaten als Tags: Eine Verwendung von Entwicklermetadaten ist ein Tag, mit dem ein Ort in der Tabelle nur mit einem Schlüssel und einem Ort benannt wird. Sie können beispielsweise headerRow einer bestimmten Zeile oder totals einer bestimmten Spalte in einem Tabellenblatt zuordnen. Mit Tags können Sie Teile einer Tabelle semantisch an Felder in einem Drittanbietertool oder einer Datenbank binden, sodass Änderungen an der Tabelle Ihre App nicht beeinträchtigen.

  2. Metadaten als Eigenschaften: Metadaten, die durch Angabe eines Schlüssels, eines Standorts und eines Werts erstellt werden, fungieren als Schlüssel/Wert-Paar, das mit diesem Standort in einem Tabellenblatt verknüpft ist. Sie können beispielsweise Folgendes verknüpfen:

    • formResponseId = resp123 mit einer Zeile
    • lastUpdated = 1477369882 mit einer Spalte

    So können Sie benutzerdefinierte benannte Eigenschaften speichern und darauf zugreifen, die mit bestimmten Bereichen oder Daten in einer Tabelle verknüpft sind.

  3. Sichtbare Metadaten für Projekte und Dokumente: Damit die Metadaten eines Entwicklerprojekts nicht mit denen eines anderen Projekts in Konflikt geraten, gibt es zwei Metadateneinstellungen visibility: project und document. Bei Verwendung der Sheets API sind Projektmetadaten nur im Google Cloud-Projekt sichtbar und zugänglich, in dem sie erstellt wurden. Auf Dokumentmetadaten kann von jedem Google Cloud-Projekt aus zugegriffen werden, das Zugriff auf das Dokument hat.

    Bei Anfragen, in denen keine Sichtbarkeit angegeben ist, werden übereinstimmende Dokumentmetadaten und übereinstimmende Projektmetadaten für das Google Cloud-Projekt zurückgegeben, aus dem die Anfrage stammt.

  4. Eindeutigkeit: Metadatenschlüssel müssen nicht eindeutig sein, aber die metadataId muss eindeutig sein. Wenn Sie Metadaten erstellen und das ID-Feld nicht angeben, wird eine ID von der API zugewiesen. Mit dieser ID können die Metadaten identifiziert werden. Mit Schlüsseln und anderen Attributen lassen sich Metadatensätze identifizieren.

Metadaten erstellen

Verwenden Sie zum Erstellen von Metadaten die Methode batchUpdate für die Ressource spreadsheets und geben Sie ein CreateDeveloperMetadataRequest mit den Werten metadataKey, location und visibility aus der Ressource spreadsheets.developerMetadata an. Optional können Sie 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, wird eine von der API zugewiesen.

In diesem Beispiel geben wir einen Schlüssel, einen Wert und eine Zeile in der Anfrage an. Die Antwort gibt diese Entwicklermetadatenwerte sowie die zugewiesene Metadaten-ID zurück.

Ersuchen

{
  "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

Wenn Sie einzelne, eindeutige Entwicklermetadaten abrufen möchten, verwenden Sie die Methode spreadsheets.developerMetadata.get. Geben Sie dabei den spreadsheetId mit den Metadaten und die eindeutige metadataId der Entwicklermetadaten an.

Ersuchen

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/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

Wenn Sie mehrere Elemente von Entwicklermetadaten abrufen möchten, verwenden Sie die Methode spreadsheets.developerMetadata.search. Sie müssen ein DataFilter angeben, das mit vorhandenen Metadaten für eine beliebige Kombination von Attributen wie Schlüssel, Wert, Ort oder Sichtbarkeit übereinstimmt.

In diesem Beispiel werden mehrere Metadaten-IDs in der Anfrage angegeben. In der Antwort werden die Entwicklermetadatenwerte für jede Metadaten-ID zurückgegeben.

Ersuchen

{
  "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 zum Aktualisieren von Entwicklermetadaten die Methode spreadsheets.batchUpdate und geben Sie ein UpdateDeveloperMetadataRequest an. Sie müssen ein DataFilter angeben, das auf die zu aktualisierenden Metadaten ausgerichtet ist, eine spreadsheets.developerMetadata-Ressource mit den neuen Werten und eine Feldmaske, in der die zu aktualisierenden Felder beschrieben werden.

In diesem Beispiel geben wir die Metadaten-ID, die Tabellenblatt-ID und einen neuen Metadatenschlüssel in der Anfrage an. Die Antwort enthält diese Entwicklermetadatenwerte sowie den aktualisierten Metadatenschlüssel.

Ersuchen

{
  "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

Wenn Sie Entwicklermetadaten löschen möchten, verwenden Sie die Methode batchUpdate und geben Sie ein DeleteDeveloperMetadataRequest an. Sie müssen ein DataFilter angeben, um die zu löschenden Metadaten auszuwählen.

In diesem Beispiel geben wir die Metadaten-ID in der Anfrage an. Die Antwort gibt die Entwicklermetadatenwerte für die Metadaten-ID zurück.

Wenn Sie bestätigen möchten, dass die Entwicklermetadaten entfernt wurden, verwenden Sie die Methode spreadsheets.developerMetadata.get und geben Sie die ID der gelöschten Metadaten an. Sie sollten eine Antwort mit dem HTTP-Statuscode 404: Not Found und der Meldung „Es sind keine Entwicklermetadaten mit der ID METADATA_ID vorhanden“ erhalten.

Ersuchen

{
  "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.

Zellenwerte nach Metadaten abrufen

Verwenden Sie die Methode spreadsheets.values.batchGetByDataFilter, um Zellwerte anhand von Metadaten abzurufen. Sie müssen die Tabellen-ID und einen oder mehrere Datenfilter angeben, die den Metadaten entsprechen.

In diesem Beispiel geben wir die Metadaten-ID in der Anfrage an. Die Antwort gibt die Zeilenzellenwerte (Modellnummer, monatlicher Umsatz) für die Metadaten-ID zurück.

Ersuchen

{
  "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
          }
        }
      ]
    }
  ]
}

Tabellen anhand von Metadaten abrufen

Wenn Sie eine Tabelle abrufen, 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 den Metadaten entsprechen.

Diese Anfrage funktioniert wie eine reguläre „Tabellenblatt-GET“-Anfrage. Die Liste der Metadaten, die mit den angegebenen Datenfiltern übereinstimmen, bestimmt jedoch, welche Tabellenblätter, Rasterdaten und anderen Objektdaten mit Metadaten zurückgegeben werden. Wenn includeGridData auf „true“ gesetzt ist, werden auch Rasterdaten zurückgegeben, die die angegebenen Rasterbereiche für das Tabellenblatt schneiden. Das Feld includeGridData wird ignoriert, wenn in der Anfrage eine Feldmaske festgelegt ist.

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.

Ersuchen

{
  "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 anhand von Metadaten aktualisieren

Verwenden Sie die Methode spreadsheets.values.batchUpdateByDataFilter, um Zellwerte zu aktualisieren, die bestimmten Metadaten entsprechen. Sie müssen die Tabellen-ID valueInputOption und einen oder mehrere DataFilterValueRange-Werte angeben, die den Metadaten entsprechen.

In diesem Beispiel geben wir die Metadaten-ID und die aktualisierten Zeilenwerte in der Anfrage an. Die Antwort enthält sowohl die aktualisierten Attribute als auch die Daten für die Metadaten-ID.

Ersuchen

{
  "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

Wenn Sie Zellwerte 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.

Ersuchen

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": METADATA_ID
      }
    }
  ]
}

Antwort

{
  "spreadsheetId": SPREADSHEET_ID,
  "clearedRanges": [
    "Sheet7!A7:Z7"
  ]
}

Limits für die Speicherung von Metadaten

Die Gesamtmenge der Metadaten, die Sie in einer Tabelle speichern können, ist begrenzt. Dieses Limit 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 für die Tabelle speichern. Außerdem können Sie in jedem Tabellenblatt einer Tabelle 30.000 Zeichen 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 Feldern metadataKey und metadataValue der Ressource spreadsheets.developerMetadata wird auf dieses Limit angerechnet.