Funkcja metadanych dewelopera umożliwia powiązanie metadanych z różnymi elementami i lokalizacjami w arkuszu kalkulacyjnym. Następnie możesz wysłać zapytanie o te metadane i użyć ich do znalezienia obiektów, z którymi są powiązane.
Metadane możesz powiązać z wierszami, kolumnami, kartami lub arkuszem kalkulacyjnym.
Metadane dewelopera umożliwiają wykonywanie takich operacji jak:
Połącz dowolne dane z różnymi elementami i lokalizacjami w arkuszu kalkulacyjnym – na przykład powiązać
totalsz kolumną D lubresponseId = 1234z wierszem 7.Znajdowanie wszystkich lokalizacji i danych powiązanych z określonym kluczem lub atrybutem metadanych – na przykład przy użyciu klucza
totalspowiązanego z kolumną D lubresponseIdzwracaj wszystkie wiersze z metadanymiresponseIdi powiązanymi z nimi wartościami metadanych.Znajdowanie wszystkich danych powiązanych z konkretną lokalizacją lub lokalizacją – na przykład w kolumnie D można zwrócić wszystkie metadane powiązane z tą lokalizacją.
Pobieranie wartości w lokalizacji przez podanie powiązanych metadanych – na przykład zwracanie wartości zawartych w powiązanej kolumnie lub wierszu w przypadku funkcji
totalslub zwracanie wartości powiązanego zasobu Arkusza w przypadku funkcjisummary.Aktualizowanie wartości w lokalizacji przez podanie powiązanych metadanych – zamiast aktualizowania wartości w wierszu za pomocą notacji A1 możesz zaktualizować wartości, podając identyfikator metadanych.
Odczytywanie i zapisywanie metadanych
Zasób spreadsheets.developerMetadata zapewnia dostęp do metadanych dewelopera powiązanych z lokalizacją lub obiektem w arkuszu kalkulacyjnym.
Metadane dewelopera
W tej sekcji opisujemy najważniejsze aspekty metadanych dewelopera, które należy wziąć pod uwagę podczas pracy z interfejsem Sheets API.
Metadane jako tagi
Jednym z zadań metadanych dewelopera jest tag, który w arkuszu kalkulacyjnym nazywa lokalizację, używając tylko klucza i lokalizacji. Możesz na przykład powiązać headerRow z konkretnym wierszem lub totals z konkretną kolumną w arkuszu. Tagów można używać do semantycznego łączenia części arkusza kalkulacyjnego z polami w narzędziu lub bazie danych innej firmy, dzięki czemu zmiany w arkuszu kalkulacyjnym 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 w arkuszu kalkulacyjnym właściwości o niestandardowych nazwach powiązanych z określonymi obszarami lub danymi oraz uzyskiwanie do nich dostępu.
Metadane widoczne w projekcie a w dokumencie
Aby uniemożliwić jednemu projektowi dewelopera zakłócanie metadanych innego projektu, dostępne są 2 ustawienia metadanych visibility: project i document. Za pomocą interfejsu Sheets API metadane projektu są widoczne i dostępne tylko w projekcie dewelopera, który go utworzył. Metadane dokumentu są dostępne z poziomu dowolnego projektu dewelopera, który ma dostęp do dokumentu.
Zapytania, które nie określają wprost widoczności, zwracają metadane dokumentu i metadane projektu pasujące do projektu dewelopera przesyłającego żądanie.
Unikalność
Klucze metadanych nie muszą być unikalne, ale metadataId musi być różne. Jeśli utworzysz metadane i pozostawisz w nich puste pole identyfikatora, interfejs API przypisze identyfikator. Ten identyfikator może służyć do identyfikowania metadanych, a klucze i inne atrybuty mogą służyć do identyfikowania zbiorów metadanych.
Tworzenie metadanych
Aby utworzyć metadane, użyj metody batchUpdate, podając żądanie createDeveloperMetadataRequest z parametrami metadataKey, location i visibility. Opcjonalnie możesz podać metadataValue lub jawny metadataId.
Jeśli podasz identyfikator, który jest już używany, żądanie się nie powiedzie. Jeśli nie podasz identyfikatora, interfejs API przypisze go automatycznie.
Pokaż przykład
W tym przykładzie podajemy klucz, wartość i wiersz w żądaniu. Odpowiedź zwraca te wartości metadanych dewelopera oraz przypisany identyfikator metadanych.
Wyślij prośbę
{
"requests": [
{
"createDeveloperMetadata": {
"developerMetadata": {
"location": {
"dimensionRange": {
"sheetId": sheetId ,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT",
"metadataKey": "Sales",
"metadataValue": "2022"
}
}
}
]
}Odpowiedź
{
"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"
}
}
}
]
}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 identyfikator metadataId metadanych dewelopera.
Pokaż przykład
Wyślij prośbę
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/spreadsheetId /developerMetadata/metadataId
Odpowiedź
{
"metadataId": metadataId ,
"metadataKey": "Sales",
"metadataValue": "2022",
"location": {
"locationType": "ROW",
"dimensionRange": {
"sheetId": sheetId ,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT"
}Odczytywanie wielu elementów metadanych
Aby pobrać wiele elementów metadanych dla deweloperów, użyj metody spreadsheets.developerMetadata.search. Musisz podać parametr DataFilter, który pasuje do dowolnych istniejących metadanych dla dowolnej kombinacji właściwości, takich jak klucz, wartość, lokalizacja lub widoczność.
Pokaż przykład
W tym przykładzie w żądaniu podajemy wiele identyfikatorów metadanych. Odpowiedź zwraca wartości metadanych dewelopera dla każdego identyfikatora metadanych.
Wyślij prośbę
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
},
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}Odpowiedź
{
"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
}
}
]
}
]
}Zaktualizuj metadane
Aby zaktualizować metadane dewelopera, użyj metody spreadsheets.batchUpdate i podaj UpdateDeveloperMetadataRequest.
Musisz podać obiekt DataFilter, który kieruje na metadanych, które mają zostać zaktualizowane, obiekt DeveloperMetadata z nowymi wartościami oraz maskę pola opisującą pola, które mają zostać zaktualizowane.
Pokaż przykład
W tym przykładzie w żądaniu podajemy identyfikator metadanych, identyfikator arkusza i nowy klucz metadanych. Odpowiedź zwraca te wartości metadanych dewelopera oraz zaktualizowany klucz metadanych.
Wyślij prośbę
{
"requests": [
{
"updateDeveloperMetadata": {
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"developerMetadata": {
"location": {
"sheetId": sheetId
},
"metadataKey": "SalesUpdated"
},
"fields": "location,metadataKey"
}
}
]
}Odpowiedź
{
"spreadsheetId": spreadsheetId ,
"replies": [
{
"updateDeveloperMetadata": {
"developerMetadata": [
{
"metadataId": metadataId ,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": sheetId
},
"visibility": "DOCUMENT"
}
]
}
}
]
}Usuwanie metadanych
Aby usunąć metadane dewelopera, użyj metody batchUpdate i prześlij żądanie DeleteDeveloperMetadataRequest.
Musisz określić DataFilter, aby wybrać metadane, które chcesz usunąć.
Pokaż przykład
W tym przykładzie podajemy identyfikator metadanych w żądaniu. Odpowiedź zwraca wartości metadanych dewelopera dla identyfikatora metadanych.
Aby sprawdzić, czy metadane dewelopera zostały usunięte, użyj metody spreadsheets.developerMetadata.get, podając identyfikator usuniętych metadanych. Otrzymasz odpowiedź z kodem stanu HTTP 404: Not Found i komunikatem „Brak metadanych dewelopera o identyfikatorze metadataId”.
Wyślij prośbę
{
"requests": [
{
"deleteDeveloperMetadata": {
"dataFilter": {
"developerMetadataLookup": {
"metadataId": metadataId
}
}
}
}
]
}Odpowiedź
{
"spreadsheetId": spreadsheetId ,
"replies": [
{
"deleteDeveloperMetadata": {
"deletedDeveloperMetadata": [
{
"metadataId": metadataId ,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": sheetId
},
"visibility": "DOCUMENT"
}
]
}
}
]
}Odczytywanie i zapisywanie wartości powiązanych z metadanymi
Wartości komórek w wierszach i kolumnach możesz też pobierać i aktualizować, podając powiązane metadane dewelopera i wartości, które chcesz zaktualizować. Aby to zrobić, użyj odpowiedniej metody poniżej z odpowiednim parametrem DataFilter.
Pobieranie wartości komórek według metadanych
Aby pobrać 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.
Pokaż przykład
W tym przykładzie podajemy identyfikator metadanych w żądaniu. Odpowiedź zwraca wartości komórek wiersza (numer modelu, sprzedaż miesięczna) dla identyfikatora metadanych.
Wyślij prośbę
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"majorDimension": "ROWS"
}Odpowiedź
{
"spreadsheetId": spreadsheetId ,
"valueRanges": [
{
"valueRange": {
"range": "Sheet7!A7:Z7",
"majorDimension": "ROWS",
"values": [
[
"W-24",
"74"
]
]
},
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}
]
}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 „spreadsheet GET”, z tą różnicą, że lista metadanych dopasowanych przez określone filtry danych określa, które arkusze, dane siatki i inne zasoby obiektów z metadanymi zostaną zwrócone. Jeśli parametr includeGridData ma wartość Prawda, dane siatki przecinające określone zakresy siatki są również zwracane w arkuszu.
Pokaż przykład
W tym przykładzie podajemy identyfikator metadanych i ustawiamy wartość includeGridData na „false” (fałsz) w żądaniu. Odpowiedź zawiera właściwości arkusza kalkulacyjnego i arkusza.
Wyślij prośbę
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"includeGridData": false
}Odpowiedź
{ "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 }
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,
oraz co najmniej 1 DataFilterValueRange, który pasuje do metadanych.
Pokaż przykład
W tym przykładzie w żądaniu podajemy identyfikator metadanych i zaktualizowane wartości wierszy. Odpowiedź zwraca zaktualizowane właściwości i dane dla identyfikatora metadanych.
Wyślij prośbę
{
"data": [
{
"dataFilter": {
"developerMetadataLookup": {
"metadataId": metadataId
}
},
"majorDimension": "ROWS",
"values": [
[
"W-24",
"84"
]
]
}
],
"includeValuesInResponse": true,
"valueInputOption": "USER_ENTERED"
}Odpowiedź
{
"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"
]
]
}
}
]
}Wyczyść 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 usunąć, musisz określić filtr danych.
Pokaż przykład
Wyślij prośbę
W tym przykładzie podajemy identyfikator metadanych w żądaniu. Odpowiedź zwraca identyfikator arkusza kalkulacyjnego i oczyszczone zakresy.
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}Odpowiedź
{
"spreadsheetId": spreadsheetId ,
"clearedRanges": [
"Sheet7!A7:Z7"
]
}Limity miejsca na dane dotyczące metadanych
Łączna ilość metadanych, które możesz przechowywać w arkuszu kalkulacyjnym, jest ograniczona. Ten limit jest wyrażony w znakach i składa się z 2 komponentów:
| Element | Przydział limitu miejsca na dane |
|---|---|
| Arkusz kalkulacyjny | 30 tys. znaków |
| każdy arkusz w arkuszu kalkulacyjnym, | 30 tys. znaków |
W arkuszu kalkulacyjnym możesz przechowywać maksymalnie 30 tys. znaków. Dodatkowo możesz przechowywać 30 tys. znaków na każdym arkuszu w arkuszu kalkulacyjnym (30 tys. znaków na pierwszy arkusz, 30 tys. znaków na drugi itd.). Oznacza to,że arkusz kalkulacyjny z 3 stronami może zawierać do 120 tys. znaków metadanych dla deweloperów.
Do tego limitu wlicza się każdy znak w atrybutach klucza i wartości obiektu developerMetadata.