Funkcja metadanych dewelopera umożliwia powiązanie metadanych z różnymi elementami i lokalizacjami w arkuszu kalkulacyjnym. Możesz przesłać zapytanie o te metadane i użyć ich do odnalezienia powiązanych obiektów.
Metadane możesz powiązać z wierszami, kolumnami, arkuszami lub arkuszem kalkulacyjnym.
Metadane dewelopera pozwalają na takie działania jak:
Powiąż dowolne dane z różnymi elementami i lokalizacjami w arkuszu kalkulacyjnym – na przykład powiąż
totalsz kolumną D lubresponseId = 1234z wierszem 7.Znajdowanie wszystkich lokalizacji i danych powiązanych z określonym kluczem lub atrybutem metadanych – np. w przypadku klucza
totalspowiązanego z kolumną D lub podanym w poluresponseIdzwracanie wszystkich wierszy zawierających metadaneresponseIdi powiązaną z nimi wartość metadanych.Znajdź wszystkie dane powiązane z konkretną jednostką lub lokalizacją – na przykład w przypadku danej kolumny D zwracane są wszystkie metadane powiązane z tą lokalizacją.
Pobieranie wartości w lokalizacji przez określenie powiązanych metadanych – na przykład
totalszwraca reprezentację wartości zawartych w powiązanej kolumnie lub wierszu albosummaryzwraca reprezentację powiązanego zasobu arkusza.Aktualizuj wartości w lokalizacji przez określenie powiązanych metadanych – na przykład zamiast aktualizować wartości w wierszu za pomocą notacji A1, możesz zaktualizować wartości, podając identyfikator metadanych.
Odczyt i zapis metadanych
Zasób spreadsheets.developerMetadata umożliwia dostęp do metadanych programisty powiązanych z lokalizacją lub obiektem w arkuszu kalkulacyjnym.
Informacje o metadanych dewelopera
W tej sekcji opisujemy kilka kluczowych aspektów metadanych programistów, o których warto pamiętać, pracując z interfejsem Arkuszy API.
Metadane jako tagi
Jednym z zastosowań metadanych dewelopera jest tag, który nadaje nazwę lokalizacji w arkuszu kalkulacyjnym, używając tylko klucza i lokalizacji. Możesz na przykład powiązać element headerRow z konkretnym wierszem lub totals z konkretną kolumną w arkuszu. Tagi mogą służyć do semantycznego wiązania części arkusza z polami w narzędziu lub bazie danych innych firm, dzięki czemu zmiany w arkuszu nie spowodują uszkodzenia aplikacji.
Metadane jako właściwości
Metadane tworzone 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ą.
Dzięki temu możesz przechowywać niestandardowe nazwane właściwości powiązane z określonymi obszarami lub danymi w arkuszu kalkulacyjnym i uzyskać do nich dostęp.
Metadane dotyczące projektu a dokumenty
Aby zapobiec zakłócaniu działania metadanych innego projektu przez jeden projekt, w metadanych visibility są 2 ustawienia: project i document. Za pomocą interfejsu Sheets API metadane projektu są widoczne i dostępne tylko w projekcie programistycznym, w którym został on utworzony. Metadane dokumentu są dostępne we wszystkich projektach programistycznych
z dostępem do dokumentu.
Zapytania, które nie mają wyraźnie określonej widoczności, zwracają pasujące metadane dokumentów i metadane projektu dla projektu programisty, który wysyła żądanie.
Unikalność
Klucze metadanych nie muszą być unikalne, ale metadataId musi się różnić. Jeśli utworzysz metadane i pozostawisz pole identyfikatora nieokreślone, interfejs API przypisze je. Ten identyfikator może służyć do identyfikowania metadanych, natomiast klucze i inne atrybuty mogą służyć do identyfikowania zestawów metadanych.
Tworzenie metadanych
Aby utworzyć metadane, użyj metody batchUpdate i podaj żądanie createDeveloperMetadataRequest z wywołaniem metadataKey, location i visibility. Opcjonalnie możesz określić metadataValue lub jawną właściwość metadataId.
Jeśli podasz identyfikator, który jest już używany, żądanie nie powiedzie się. Jeśli nie podasz identyfikatora, zostanie on przypisany przez interfejs API.
Pokaż przykład
W tym przykładzie podajemy w żądaniu klucz, wartość i wiersz. Odpowiedź zwraca te wartości metadanych dewelopera i 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, który będzie zawierał parametr spreadsheetId zawierający metadane i unikalny parametr 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 dewelopera, użyj metody spreadsheets.developerMetadata.search. Musisz określić element DataFilter, który pasuje do dotychczasowych metadanych w dowolnej kombinacji właściwości, takich jak klucz, wartość, lokalizacja czy 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 wartość UpdateDeveloperMetadataRequest.
Musisz określić obiekt DataFilter kierowany na aktualizowane metadane, obiekt DeveloperMetadata z nowymi wartościami oraz maską pola opisującą pola do aktualizacji.
Pokaż przykład
W tym przykładzie podajemy w żądaniu identyfikator metadanych, identyfikator arkusza i nowy klucz metadanych. Odpowiedź zwraca te wartości metadanych dewelopera i 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"
}
]
}
}
]
}
Usuń metadane
Aby usunąć metadane dewelopera, użyj metody batchUpdate i podaj żądanie DeleteDeveloperMetadataRequest.
Musisz określić DataFilter, aby wybrać metadane, które chcesz usunąć.
Pokaż przykład
W tym przykładzie podajemy w żądaniu identyfikator metadanych. Odpowiedź zwraca wartości metadanych dewelopera dla identyfikatora metadanych.
Aby potwierdzić, że 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 z 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"
}
]
}
}
]
}
Odczyt i zapis wartości powiązanych z metadanymi
Możesz też pobierać i aktualizować wartości komórek w wierszach i kolumnach, określając powiązane metadane dewelopera oraz wartości, które chcesz zaktualizować. Aby to zrobić, użyj odpowiedniej metody poniżej z pasującym elementem 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 jeden filtr danych pasujący do metadanych.
Pokaż przykład
W tym przykładzie podajemy w żądaniu identyfikator metadanych. Odpowiedź zwraca wartości komórek wiersza (numer modelu, miesięczna sprzedaż) odpowiadającego identyfikatorowi 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
}
}
]
}
]
}
Pobierz arkusz kalkulacyjny według metadanych
Pobierając arkusz kalkulacyjny, możesz zwrócić podzbiór danych przy użyciu metody spreadsheets.getByDataFilter. Musisz podać identyfikator arkusza kalkulacyjnego i co najmniej jeden filtr danych pasujący do metadanych.
To żądanie działa jak zwykłe żądanie „GET arkusza kalkulacyjnego”, z wyjątkiem listy 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 argument includeGridData ma wartość Prawda, dane siatki przecinające określone zakresy siatki są też zwracane do arkusza.
Pokaż przykład
W tym przykładzie podajemy identyfikator metadanych i w żądaniu ustawiamy wartość includeGridData na false. Odpowiedź zwraca zarówno właściwości arkusza kalkulacyjnego, jak 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 jeden element DataFilterValueRange, który pasuje do metadanych.
Pokaż przykład
W tym przykładzie podajemy w żądaniu identyfikator metadanych i zaktualizowane wartości wierszy. Odpowiedź zwraca zarówno zaktualizowane właściwości, jak i dane 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 do wyczyszczenia, musisz określić filtr danych.
Pokaż przykład
Wyślij prośbę
W tym przykładzie podajemy w żądaniu identyfikator metadanych. Odpowiedź zawiera identyfikator arkusza kalkulacyjnego i wyczyszczone zakresy.
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}
Odpowiedź
{
"spreadsheetId": spreadsheetId,
"clearedRanges": [
"Sheet7!A7:Z7"
]
}
Limity miejsca na metadane
Istnieje limit łącznej liczby metadanych, które można przechowywać w arkuszu kalkulacyjnym. Limit jest mierzony w znakach i składa się z 2 komponentó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 zapisać do 30 000 znaków. Poza tym możesz przechowywać 30 000 znaków na każdy arkusz w arkuszu kalkulacyjnym (30 000 w arkuszu 1, 30 000 w arkuszu 2 itd.). Arkusz kalkulacyjny z 3 stronami może więc zawierać do 120 tys. znaków metadanych dewelopera.
Do tego limitu wlicza się każdy znak w atrybutach klucza i wartości obiektu developerMetadata.