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 encją – 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
totalslub zwracanie powiązanego zasobu Arkusza w przypadkusummary.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.
Informacje o metadanych dewelopera
W tej sekcji opisujemy niektóre kluczowe 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 wiązania części arkusza kalkulacyjnego z pola 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 je utworzył. Metadane dokumentu są dostępne w ramach każdego 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 oraz 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ć wartość DataFilter, która pasuje do istniejących metadanych w 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 DeveloperMetadataz nowymi wartościami oraz maskę polaopisują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. Powinieneś otrzymać 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 pasujący 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 pasujący 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 dla arkusza.
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 i co najmniej 1 DataFilterValueRange pasujący 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"
]
]
}
}
]
}
Wyczyszczenie 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.