Funkcja metadanych umożliwia powiązanie metadanych z różnymi encjami i lokalizacjami w arkuszu kalkulacyjnym. Następnie możesz wysyłać zapytania dotyczące tych metadanych i używać ich do znajdowania obiektów, z którymi są powiązane.
Metadane możesz powiązać z wierszami, kolumnami, arkuszami lub arkuszem kalkulacyjnym.
Informacje o metadanych
Poniżej znajdziesz opis najważniejszych aspektów metadanych, które warto wziąć pod uwagę podczas korzystania z interfejsu Google Sheets API:
Metadane jako tagi: jednym z zastosowań metadanych dewelopera jest tag, który określa lokalizację w arkuszu kalkulacyjnym za pomocą klucza i lokalizacji. Możesz na przykład powiązać
headerRowz konkretnym wierszem lubtotalsz konkretną kolumną w arkuszu. Tagi mogą być używane do semantycznego wiązania części arkusza kalkulacyjnego z polami w narzędziu lub bazie danych innej firmy, dzięki czemu zmiany w arkuszu nie spowodują awarii aplikacji.Metadane jako właściwości: metadane utworzone przez określenie klucza, lokalizacji i wartości działają jako para klucz-wartość powiązana z tą lokalizacją w arkuszu. Możesz na przykład powiązać:
formResponseId = resp123z wierszemlastUpdated = 1477369882z kolumną
Umożliwia to przechowywanie niestandardowych właściwości nazwanych powiązanych z określonymi obszarami lub danymi w arkuszu kalkulacyjnym oraz uzyskiwanie do nich dostępu.
Metadane widoczne w projekcie a metadane widoczne w dokumencie: aby zapobiec zakłócaniu metadanych jednego projektu deweloperskiego przez metadane innego projektu, dostępne są 2 ustawienia metadanych:
visibilityprojectidocument. W przypadku interfejsu Sheets APIprojectmetadane są widoczne i dostępne tylko w projekcie Google Cloud, w którym zostały utworzone.documentmetadane są dostępne z każdego projektu Google Cloud, który ma dostęp do dokumentu.Zapytania, które nie określają wyraźnie
visibility, zwracają pasującedocumentmetadane i pasująceprojectmetadane projektu Google Clouddocument, który wysyła żądanie.Unikalność: klucze metadanych nie muszą być unikalne, ale
metadataIdmuszą się od siebie różnić. Jeśli utworzysz metadane i nie określisz ich identyfikatora, interfejs API przypisze go automatycznie. Ten identyfikator może służyć do identyfikowania metadanych, a klucze i inne atrybuty mogą służyć do identyfikowania zestawów metadanych.Zwracanie metadanych za pomocą żądań interfejsu API: obiekt A
DataFilterjest częścią wywołania interfejsu API, które opisuje dane do wybrania lub zwrócenia w ramach żądania interfejsu API.Pojedynczy obiekt
DataFiltermoże określać tylko jeden typ kryteriów filtrowania do lokalizowania danych:developerMetadataLookup: wybiera dane powiązane z określonymi metadanymi dewelopera, które spełniają kryteria.a1Range: wybiera dane, które pasują do określonego zakresu notacji A1. Na przykład:Sheet1!A1:B10.gridRange: wybiera dane, które pasują do określonego zakresu siatki, używając indeksów opartych na zerze. Na przykład:Sheet1!A3:B4 == sheetId: 123456, startRowIndex: 2, endRowIndex: 4, startColumnIndex: 0, endColumnIndex: 2.
Aby filtrować dane według wielu lokalizacji lub kryteriów, możesz użyć wielu obiektów
DataFilterw jednym żądaniu interfejsu API. W przypadku żądania zbiorczego, takiego jak metodaspreadsheets.values.batchGetByDataFilter, podaj tablicę lub listę obiektówDataFilter. Każdy zakres, który pasuje do dowolnego filtra danych w żądaniu, zostanie zwrócony lub zmodyfikowany.Więcej informacji znajdziesz w artykule Odczytywanie i zapisywanie wartości powiązanych z metadanymi.
Przypadki użycia
Oto kilka przykładowych zastosowań zarządzania metadanymi:
Powiązywanie dowolnych danych z różnymi podmiotami i lokalizacjami w arkuszu kalkulacyjnym: np. powiąż
totalsz kolumną D lubresponseId = 1234z wierszem 7.Znajdź wszystkie lokalizacje i dane powiązane z określonym kluczem metadanych lub atrybutem: na przykład dla klucza
totalspowiązanego z kolumną D lub dlaresponseIdzwróć wszystkie wiersze z metadanymiresponseIdi powiązaną z nimi wartością metadanych.Znajdź wszystkie dane powiązane z konkretnym elementem lub lokalizacją: na przykład w kolumnie D zwróć wszystkie metadane powiązane z tą lokalizacją.
Pobieranie wartości w lokalizacji przez określenie powiązanych metadanych: na przykład w przypadku
totalszwracana jest reprezentacja wartości zawartych w powiązanej kolumnie lub wierszu, a w przypadkusummaryzwracana jest reprezentacja powiązanego zasobu arkusza.Aktualizowanie wartości w lokalizacji przez podanie powiązanych metadanych: na przykład zamiast aktualizować wartości w wierszu za pomocą notacji A1, możesz to zrobić, podając identyfikator metadanych.
Odczytywanie i zapisywanie metadanych
Zasób
spreadsheets.developerMetadata
zapewnia dostęp do metadanych powiązanych z lokalizacją lub obiektem w arkuszu kalkulacyjnym. Metadane dewelopera umożliwiają powiązanie dowolnych danych z różnymi częściami arkusza kalkulacyjnego. Metadane pozostają powiązane z tymi lokalizacjami podczas edytowania arkusza kalkulacyjnego.
Tworzenie metadanych
Aby utworzyć metadane, użyj metody
batchUpdate
w zasobie
spreadsheets i podaj
CreateDeveloperMetadataRequest
z wartościami metadataKey, location i visibility z zasobu
spreadsheets.developerMetadata. Możesz opcjonalnie podać znak metadataValue lub jawny znak metadataId.
Jeśli określisz identyfikator, który jest już używany, żądanie się nie powiedzie. Jeśli nie podasz identyfikatora, interfejs API przypisze go automatycznie.
W tym przykładzie w żądaniu podajemy klucz, wartość i wiersz. Odpowiedź zawiera te wartości metadanych dewelopera oraz przypisany identyfikator metadanych.
Żądanie
{
"requests": [
{
"createDeveloperMetadata": {
"developerMetadata": {
"location": {
"dimensionRange": {
"sheetId": SHEET_ID,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT",
"metadataKey": "Sales",
"metadataValue": "2022"
}
}
}
]
}Odpowiedź
{
"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"
}
}
}
]
}Odczytywanie pojedynczego elementu metadanych
Aby pobrać pojedyncze, odrębne metadane dewelopera, użyj metody spreadsheets.developerMetadata.get, podając spreadsheetId zawierający metadane i unikalny metadataId metadanych dewelopera.
Żądanie
W tym przykładzie w żądaniu podajemy identyfikator arkusza kalkulacyjnego i identyfikator metadanych. Odpowiedź zwraca wartości metadanych dewelopera dla identyfikatora metadanych.
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/developerMetadata/METADATA_ID
Odpowiedź
{
"metadataId": METADATA_ID,
"metadataKey": "Sales",
"metadataValue": "2022",
"location": {
"locationType": "ROW",
"dimensionRange": {
"sheetId": SHEET_ID,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT"
}Odczytywanie wielu elementów metadanych
Aby pobrać wiele elementów metadanych dewelopera, użyj metody
spreadsheets.developerMetadata.search. Musisz określić DataFilter, które pasuje do istniejących metadanych w dowolnej kombinacji właściwości, takich jak klucz, wartość, lokalizacja lub widoczność.
W tym przykładzie w żądaniu podajemy kilka identyfikatorów metadanych. Odpowiedź zawiera wartości metadanych dewelopera dla każdego identyfikatora metadanych.
Żądanie
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
},
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
]
}Odpowiedź
{
"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
}
}
]
}
]
}Zaktualizuj metadane
Aby zaktualizować metadane dewelopera, użyj metody
spreadsheets.batchUpdate
i podaj
UpdateDeveloperMetadataRequest.
Musisz podać DataFilter, który kieruje na metadane do zaktualizowania, zasób spreadsheets.developerMetadata z nowymi wartościami oraz maskę pola opisującą pola do zaktualizowania.
W tym przykładzie w żądaniu podajemy identyfikator metadanych, identyfikator arkusza i nowy klucz metadanych. Odpowiedź zawiera te wartości metadanych dewelopera oraz zaktualizowany klucz metadanych.
Żądanie
{
"requests": [
{
"updateDeveloperMetadata": {
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
],
"developerMetadata": {
"location": {
"sheetId": SHEET_ID
},
"metadataKey": "SalesUpdated"
},
"fields": "location,metadataKey"
}
}
]
}Odpowiedź
{
"spreadsheetId": SPREADSHEET_ID,
"replies": [
{
"updateDeveloperMetadata": {
"developerMetadata": [
{
"metadataId": METADATA_ID,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": SHEET_ID
},
"visibility": "DOCUMENT"
}
]
}
}
]
}Usuwanie metadanych
Aby usunąć metadane dewelopera, użyj metody
batchUpdate
i podaj wartość
DeleteDeveloperMetadataRequest.
Musisz podać DataFilter, aby wybrać metadane, które chcesz usunąć.
W tym przykładzie podajemy w żądaniu identyfikator metadanych. Odpowiedź zwraca wartości metadanych dewelopera dla identyfikatora metadanych.
Aby potwierdzić usunięcie metadanych dewelopera, użyj metody spreadsheets.developerMetadata.get, podając identyfikator usuniętych metadanych. Powinna zostać zwrócona odpowiedź z kodem stanu HTTP 404: Not Found i komunikatem „Nie ma metadanych dewelopera o identyfikatorze METADATA_ID”.
Żądanie
{
"requests": [
{
"deleteDeveloperMetadata": {
"dataFilter": {
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
}
}
]
}Odpowiedź
{
"spreadsheetId": SPREADSHEET_ID,
"replies": [
{
"deleteDeveloperMetadata": {
"deletedDeveloperMetadata": [
{
"metadataId": METADATA_ID,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": SHEET_ID
},
"visibility": "DOCUMENT"
}
]
}
}
]
}Odczytywanie i zapisywanie wartości powiązanych z metadanymi
Możesz też pobierać i aktualizować wartości komórek w wierszach i kolumnach, podając powiązane metadane dewelopera i wartości, które chcesz zaktualizować. Aby to zrobić, użyj jednej z tych metod z pasującym DataFilter.
Pobieranie wartości komórek według metadanych
Aby uzyskać wartości komórek według metadanych, użyj metody
spreadsheets.values.batchGetByDataFilter. Musisz podać identyfikator arkusza kalkulacyjnego i co najmniej 1 filtr danych, który pasuje do metadanych.
W tym przykładzie podajemy w żądaniu identyfikator metadanych. Odpowiedź zwraca wartości komórek wiersza (numer modelu, miesięczna sprzedaż) dla identyfikatora metadanych.
Żądanie
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
],
"majorDimension": "ROWS"
}Odpowiedź
{
"spreadsheetId": SPREADSHEET_ID,
"valueRanges": [
{
"valueRange": {
"range": "Sheet7!A7:Z7",
"majorDimension": "ROWS",
"values": [
[
"W-24",
"74"
]
]
},
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
]
}
]
}Pobieranie arkusza kalkulacyjnego według metadanych
Podczas pobierania arkusza kalkulacyjnego możesz zwrócić podzbiór danych za pomocą metody spreadsheets.getByDataFilter. Musisz podać identyfikator arkusza kalkulacyjnego i co najmniej 1 filtr danych, który pasuje do metadanych.
To żądanie działa jak zwykłe żądanie „GET arkusza kalkulacyjnego”, z tym że lista metadanych pasujących do określonych filtrów danych określa, które arkusze, dane siatki i inne zasoby obiektów z metadanymi są zwracane. Jeśli parametr includeGridData ma wartość true, zwracane są też dane siatki przecinające określone zakresy siatki. Pole includeGridData jest ignorowane, jeśli w żądaniu jest ustawiona maska pola.
W tym przykładzie podajemy identyfikator metadanych i ustawiamy w żądaniu wartość includeGridData na false. Odpowiedź zawiera zarówno właściwości arkusza kalkulacyjnego, jak i arkusza.
Żądanie
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
],
"includeGridData": false
}Odpowiedź
{ "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 }
Aktualizowanie wartości według metadanych
Aby zaktualizować wartości komórek pasujące do określonych metadanych, użyj metody
spreadsheets.values.batchUpdateByDataFilter. Musisz podać identyfikator arkusza kalkulacyjnego,
valueInputOption i co najmniej 1 wartość
DataFilterValueRange, która pasuje do metadanych.
W tym przykładzie w żądaniu podajemy identyfikator metadanych i zaktualizowane wartości wierszy. Odpowiedź zawiera zarówno zaktualizowane właściwości, jak i dane identyfikatora metadanych.
Żądanie
{
"data": [
{
"dataFilter": {
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
},
"majorDimension": "ROWS",
"values": [
[
"W-24",
"84"
]
]
}
],
"includeValuesInResponse": true,
"valueInputOption": "USER_ENTERED"
}Odpowiedź
{
"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"
]
]
}
}
]
}Czyszczenie wartości według metadanych
Aby wyczyścić wartości komórek pasujące do określonych metadanych, użyj metody
spreadsheets.values.batchClearByDataFilter. Aby wybrać metadane, które chcesz wyczyścić, musisz określić filtr danych.
Żądanie
W tym przykładzie podajemy w żądaniu identyfikator metadanych. Odpowiedź zawiera identyfikator arkusza kalkulacyjnego i wyczyszczone zakresy.
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": METADATA_ID
}
}
]
}Odpowiedź
{
"spreadsheetId": SPREADSHEET_ID,
"clearedRanges": [
"Sheet7!A7:Z7"
]
}Limity miejsca na metadane
Istnieje limit łącznej ilości metadanych, które można przechowywać w arkuszu kalkulacyjnym. Limit ten jest mierzony w znakach i składa się z 2 elementów:
| Element | Przydział limitu miejsca na dane |
|---|---|
| Arkusz kalkulacyjny | 30 000 znaków |
| każdy arkusz w arkuszu kalkulacyjnym, | 30 000 znaków |
W arkuszu kalkulacyjnym możesz przechowywać maksymalnie 30 000 znaków. Dodatkowo możesz przechowywać 30 000 znaków w każdym arkuszu kalkulacyjnym (30 000 w arkuszu 1, 30 000 w arkuszu 2 itd.). Arkusz kalkulacyjny z 3 arkuszami może więc zawierać do 120 tys. znaków metadanych.
Każdy znak w polach metadataKey i metadataValue zasobu spreadsheets.developerMetadata wlicza się do tego limitu.
Powiązane artykuły
- Stosowanie filtrów do danych w Arkuszach Google
- Zarządzanie widocznością danych za pomocą filtrów
- Limity wykorzystania