Funkcja metadanych umożliwia powiązanie metadanych z różnymi encjami i lokalizacjami w arkuszu kalkulacyjnym. Możesz następnie 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.
Możesz generować metadane, aby wykonywać takie operacje jak:
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 podmiotem lub lokalizacją: na przykład w przypadku kolumny 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
totalszwracanie reprezentacji wartości zawartych w powiązanej kolumnie lub wierszu, a w przypadkusummaryzwracanie reprezentacji 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 aktualizować wartości, 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.
Informacje o metadanych
W tej sekcji opisujemy niektóre kluczowe aspekty metadanych, które należy wziąć pod uwagę podczas pracy z interfejsem 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ą służyć do semantycznego wiązania fragmentów arkusza 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 dewelopera przez metadane innego projektu, dostępne są 2 ustawienia metadanych:
visibilityprojectidocument. W przypadku interfejsu Sheets API metadane projektu są widoczne i dostępne tylko w projekcie Google Cloud, w którym zostały utworzone. Metadane dokumentu są dostępne z każdego projektu Google Cloud, który ma dostęp do dokumentu.Zapytania, które nie określają jawnie widoczności, zwracają pasujące metadane dokumentu i pasujące metadane projektu dla projektu Google Cloud, 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.
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ź zawiera 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ź zawiera 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 symbolem 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, korzystając z 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ść Prawda, zwracane są też dane siatki przecinające określone zakresy siatki. Pole includeGridData jest ignorowane, jeśli w żądaniu ustawiona jest 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 jedną 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.