Entwicklermetadaten lesen und schreiben

Mit der Funktion für Entwicklermetadaten können Sie Metadaten verschiedenen Einheiten und Standorten 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.

Mit Entwicklermetadaten können Sie unter anderem folgende Vorgänge ausfü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 finden, die einem bestimmten Metadatenschlüssel oder Attribut zugeordnet sind: Wenn beispielsweise der Schlüssel totals für Spalte D oder responseId angegeben ist, werden alle Zeilen mit den responseId-Metadaten und dem zugehörigen Metadatenwert zurückgegeben.

  • Alle Daten für eine bestimmte Einheit oder einen bestimmten Ort finden: Wenn beispielsweise Spalte D angegeben ist, werden alle Metadaten für diesen Ort zurückgegeben.

  • 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 die Werte aktualisieren, indem Sie eine Metadaten-ID angeben.

Metadaten lesen und schreiben

Die Ressource spreadsheets.developerMetadata bietet Zugriff auf Entwicklermetadaten, die mit einem Ort 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

Eine Verwendung von Entwicklermetadaten ist ein Tag, mit dem ein Ort in der Tabelle nur mit einem Schlüssel und einem Ort angegeben 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 Drittanbieterdatenbank binden, sodass Änderungen an der Tabelle Ihre App nicht beeinträchtigen.

Metadaten als Attribute

Metadaten, die durch Angabe eines Schlüssels, eines Standorts und eines Werts erstellt werden, fungieren als Schlüssel/Wert-Paar, das diesem Standort in einem Tabellenblatt zugeordnet 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 einem Tabellenblatt verknüpft sind.

Sichtbare Metadaten für Projekte und Dokumente

Damit sich die Metadaten eines Entwicklerprojekts nicht auf die Metadaten eines anderen Projekts auswirken, gibt es zwei visibility-Metadateneinstellungen: project und document. Bei Verwendung der Sheets API sind Projektmetadaten nur im Entwicklerprojekt sichtbar und zugänglich, in dem sie erstellt wurden. Dokumentmetadaten sind über jedes Entwicklerprojekt mit Zugriff auf das Dokument zugänglich.

Bei Anfragen, in denen die Sichtbarkeit nicht explizit angegeben ist, werden übereinstimmende Dokumentmetadaten und übereinstimmende Projektmetadaten für das Entwicklerprojekt zurückgegeben, mit dem die Anfrage gestellt wird.

Eindeutigkeit

Metadatenschlüssel müssen nicht eindeutig sein, aber die metadataId müssen 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 können Metadatensätze identifiziert werden.

Metadaten erstellen

Verwenden Sie zum Erstellen von Metadaten die Methode batchUpdate und geben Sie eine createDeveloperMetadataRequest mit einem metadataKey, location und visibility an. Optional können Sie ein metadataValue oder ein explizites 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": 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, eindeutige Entwicklermetadaten abrufen möchten, verwenden Sie die Methode spreadsheets.developerMetadata.get und geben Sie das 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/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 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, Standort 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": 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 ein 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, 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 gibt diese Entwicklermetadatenwerte sowie den aktualisierten Metadatenschlüssel zurück.

Ersuchen

{
  "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, um Entwicklermetadaten zu löschen, und geben Sie eine DeleteDeveloperMetadataRequest an. Sie müssen einen DataFilter angeben, um die Metadaten auszuwählen, die Sie löschen möchten.

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 und geben Sie die ID der gelöschten Metadaten an, um zu bestätigen, dass die Entwicklermetadaten entfernt wurden. Sie sollten eine Antwort mit dem HTTP-Statuscode 404: Not Found und der Meldung „Es sind keine Entwicklermetadaten mit der ID metadataId vorhanden“ erhalten.

Ersuchen

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

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 die entsprechende Methode unten mit einem passenden DataFilter.

Zellenwerte anhand von Metadaten abrufen

Wenn Sie Zellwerte anhand von Metadaten abrufen möchten, verwenden Sie die Methode spreadsheets.values.batchGetByDataFilter. 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": metadataId
      }
    }
  ],
  "majorDimension": "ROWS"
}

Antwort

{
  "spreadsheetId": spreadsheetId,
  "valueRanges": [
    {
      "valueRange": {
        "range": "Sheet7!A7:Z7",
        "majorDimension": "ROWS",
        "values": [
          [
            "W-24",
            "74"
          ]
        ]
      },
      "dataFilters": [
        {
          "developerMetadataLookup": {
            "metadataId": metadataId
          }
        }
      ]
    }
  ]
}

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 Objektressourcen 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.

In diesem Beispiel geben wir die Metadaten-ID an und setzen „includeGridData“ in der Anfrage auf „false“. Die Antwort gibt sowohl die Tabellenkalkulation als auch die Tabelleneigenschaften zurück.

Ersuchen

{
  "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 Zellwerte aktualisieren möchten, die bestimmten Metadaten entsprechen, verwenden Sie die Methode spreadsheets.values.batchUpdateByDataFilter. Sie müssen die Tabellen-ID valueInputOption und einen oder mehrere DataFilterValueRange angeben, die mit den Metadaten übereinstimmen.

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

Antwort

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

Limits für die Metadatenspeicherung

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 Seiten kann also bis zu 120.000 Zeichen an Entwicklermetadaten enthalten.

Jedes Zeichen in den Attributen „key“ und „value“ eines developerMetadata-Objekts wird auf dieses Limit angerechnet.