Odczytywanie i zapisywanie metadanych dewelopera

Funkcja metadanych dewelopera umożliwia powiązanie metadanych z różnymi elementami 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.

Metadane dewelopera umożliwiają wykonywanie takich operacji jak:

  • Powiązywanie dowolnych danych z różnymi elementami i lokalizacjami w arkuszu kalkulacyjnym – możesz na przykład powiązać totals z kolumną D lub responseId = 1234 z wierszem 7.

  • Znajdź wszystkie lokalizacje i dane powiązane z określonym kluczem metadanych lub atrybutem – na przykład dla klucza totals powiązanego z kolumną D lub dla atrybutu responseId zwróć wszystkie wiersze z metadanymi responseId i powiązaną z nimi wartością metadanych.

  • Znajdź wszystkie dane powiązane z określonym 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 na podstawie totals zwraca reprezentację wartości zawartych w powiązanej kolumnie lub wierszu, a na podstawie summary zwraca reprezentację 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, aktualizuj 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 zastosowań metadanych dewelopera jest tag, który określa lokalizację w arkuszu kalkulacyjnym, 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. Tagi mogą służyć do semantycznego wiązania części arkusza kalkulacyjnego z polami w narzędziu lub bazie danych firmy zewnętrznej, dzięki czemu zmiany w arkuszu kalkulacyjnym nie spowodują awarii aplikacji.

Metadane jako właściwości

Metadane utworzone przez podanie klucza, lokalizacji i wartości działają jak para klucz-wartość powiązana z tą lokalizacją w arkuszu. Możesz na przykład powiązać:

  • formResponseId = resp123 z wierszem
  • lastUpdated = 1477369882 z kolumną.

Umożliwia to przechowywanie niestandardowych nazwanych właściwości powiązanych z określonymi obszarami lub danymi w arkuszu kalkulacyjnym i uzyskiwanie do nich dostępu.

Metadane widoczne w projekcie a metadane widoczne w dokumencie

Aby zapobiec zakłócaniu metadanych jednego projektu deweloperskiego przez inny, istnieją 2 ustawienia metadanych: visibility i project oraz document. W przypadku interfejsu Sheets API metadane projektu są widoczne i dostępne tylko w projekcie dewelopera, który je utworzył. Metadane dokumentu są dostępne z każdego projektu deweloperskiego, który ma dostęp do dokumentu.

Zapytania, które nie określają wyraźnie widoczności, zwracają pasujące metadane dokumentu i pasujące metadane projektu dla projektu dewelopera, który wysyła żądanie.

Unikalność

Klucze metadanych nie muszą być unikalne, ale metadataId musi być odrębny. Jeśli utworzysz metadane i nie określisz ich identyfikatora, 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 i podaj createDeveloperMetadataRequest z wartościami metadataKey, location i visibility. Opcjonalnie możesz podać metadataValue lub 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.

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 metadataId metadanych dewelopera.

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ć 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.

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ć DataFilter, który kieruje na metadane do zaktualizowania, obiekt 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.

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 podaj 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 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

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 odpowiedniej metody poniżej z pasującym atrybutem 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.

W tym przykładzie podajemy w żądaniu identyfikator metadanych. Odpowiedź zwraca wartości komórek wiersza (numer modelu, miesięczna sprzedaż) 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, korzystając z 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 „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.

W tym przykładzie podajemy identyfikator metadanych i ustawiamy w żądaniu wartość false dla parametru includeGridData. Odpowiedź zawiera 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 kalkulacyjnegovalueInputOption i co najmniej jeden warunekDataFilterValueRange, który 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.

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"
          ]
        ]
      }
    }
  ]
}

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 usunąć, musisz określić filtr danych.

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 ilości metadanych, które można przechowywać w arkuszu kalkulacyjnym. Limit ten 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 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 stronami może zawierać do 120 tys. znaków metadanych dewelopera.

Każdy znak w atrybutach klucza i wartości obiektu developerMetadata wlicza się do tego limitu.