Metadaten lesen, schreiben und durchsuchen

Mit der Metadatenfunktion können Sie Metadaten verschiedenen Entitäten und Speicherorten in einer Tabelle zuordnen. Anschließend können Sie diese Metadaten 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:

  1. 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 headerRow einer bestimmten Zeile oder totals einer bestimmten Spalte in einem Tabellenblatt zuordnen. 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.

  2. 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. Beispiel:

    • formResponseId = resp123 mit einer Zeile verknüpfen
    • lastUpdated = 1477369882 mit 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.

  3. Metadaten auf Projekt- und Dokumentebene: Damit ein Entwickler projekt die Metadaten eines anderen Projekts nicht beeinträchtigt, gibt es zwei Metadaten visibility Einstellungen: project und document. Mit der Sheets API sind project-Metadaten nur im Google Cloud-Projekt sichtbar und zugänglich, in dem sie erstellt wurden. Auf die document-Metadaten kann von jedem Google Cloud-Projekt aus zugegriffen werden, das Zugriff auf das Dokument hat.

    Abfragen, in denen keine visibility angegeben ist, geben übereinstimmende document-Metadaten und übereinstimmende project-Metadaten für das Google Cloud-Projekt zurück, das die Anfrage stellt.

  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 von der API eine ID zugewiesen. Mit dieser ID können die Metadaten identifiziert werden, während Schlüssel und andere Attribute verwendet werden können, um Metadatensätze zu identifizieren.

  5. 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 A1 Bereich übereinstimmen. Beispiel: Sheet1!A1:B10.

    • gridRange: Wählt Daten aus, die mit dem angegebenen Rasterbereich ü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 DataFilter Objekte verwenden. Geben Sie ein Array oder eine Liste von DataFilter Objekten für eine Batchanfrage wie die spreadsheets.values.batchGetByDataFilter Methode 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 Anwendungsbeispiele 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 totals mit Spalte D oder responseId = 1234 mit Zeile 7.

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

  • Alle Daten finden, die mit einer bestimmten Entität oder einem bestimmten Speicherort verknüpft sind: Wenn beispielsweise Spalte D angegeben ist, werden alle Metadaten zurückgegeben, die mit diesem Speicherort verknüpft sind.

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

  • Werte an einem Speicherort aktualisieren, indem Sie zugehörige Metadaten angeben: 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 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.

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

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.

Ersuchen

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.

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

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

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 Statuscode 404: Not Found und der Meldung „No developer metadata with ID METADATA_ID“ 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 zu aktualisierenden Werte angeben. 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 Zeilenzellwerte (Modellnummer, monatlicher Umsatz) für die Metadaten-ID.

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

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.

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 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 aktualisierte Zeilenwerte 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

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.

Ersuchen

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 für jedes Tabellenblatt in 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 metadataKey und metadataValue Feldern der spreadsheets.developerMetadata Ressource wird auf dieses Limit angerechnet.