Dodawanie niestandardowych właściwości plików

Niestandardowe właściwości plików to pary klucz-wartość używane do przechowywania niestandardowych metadanych pliku na Dysku Google (np. tagów), identyfikatorów z innych magazynów danych, informacji udostępnianych między aplikacjami przepływu pracy itd. Możesz na przykład dodać właściwości pliku do wszystkich dokumentów wygenerowanych przez dział sprzedaży w I kwartale.

Aby dodać właściwości widoczne dla wszystkich aplikacji, użyj pola properties zasobu files. Aby dodać usługi ograniczone do aplikacji, użyj pola appProperties zasobu files.

Właściwości można też używać w wyrażeniach wyszukiwania.

To jest struktura typowej właściwości, która może służyć do przechowywania w pliku identyfikatora bazy danych pliku z Dysku.

Interfejs API Dysku w wersji 3

"appProperties": {
  "additionalID": "ID",
}

Interfejs API Dysku w wersji 2

{
  'key':        'additionalID',
  'value':      'ID',
  'visibility': 'PRIVATE'
}

Praca z niestandardowymi właściwościami pliku

W tej sekcji wyjaśniamy, jak wykonywać zadania związane z niestandardowymi właściwościami pliku, które mają wpływ na wszystkie aplikacje.

Dodawanie lub aktualizowanie niestandardowych właściwości pliku

Aby dodać lub zaktualizować właściwości widoczne dla wszystkich aplikacji, użyj metody files.update do ustawienia pola properties zasobu files.

PATCH https://www.googleapis.com/drive/v3/files/FILE_ID
{
  "properties": {
    "name": "wrench",
    "mass": "1.3kg",
    "count": "3"
  }
}

Możesz też dodać niestandardową właściwość do pliku przy użyciu zaawansowanej usługi Dysku w Google Apps Script. Więcej informacji znajdziesz w artykule Dodawanie właściwości niestandardowych.

Pobieranie lub wyświetlanie listy niestandardowych właściwości pliku

Aby wyświetlić właściwości widoczne dla wszystkich aplikacji, użyj metody files.get do pobrania niestandardowych właściwości pliku.

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=properties

Odpowiedź składa się z obiektu properties zawierającego zbiór par klucz-wartość.

{
  "properties": {
    "name": "wrench",
    "mass": "1.3kg",
    "count": "3"
  }
}

Usuń niestandardowe właściwości pliku

Aby usunąć wartości właściwości widoczne dla wszystkich aplikacji, użyj metody files.update, aby w polu properties zasobu files ustawić wartość null.

PATCH https://www.googleapis.com/drive/v3/files/FILE_ID
{
  "name": null
}

Aby wyświetlić zmianę, wywołaj metodę files.get w celu pobrania obiektu properties dla pliku.

{
  "properties": {
    "mass": "1.3kg",
    "count": "3"
  }
}

Ograniczenia niestandardowych właściwości pliku

Właściwości niestandardowe mają te limity:

  • Maksymalnie 100 właściwości niestandardowych na plik łącznie ze wszystkich źródeł.
  • Maksymalnie 30 właściwości publicznych na plik łącznie ze wszystkich źródeł.
  • Maksymalnie 30 właściwości prywatnych na plik z dowolnej aplikacji.
  • Maksymalnie 124 bajty na ciąg właściwości (w tym klucz i wartość) w kodowaniu UTF-8. Na przykład właściwość z kluczem 10-znakowym może mieć w wartości tylko 114 znaków. Podobnie właściwość, która wymaga 100 znaków jako wartości, może używać do 24 znaków na klucz.

Więcej informacji znajdziesz w zasobie files. W przypadku interfejsu Drive API w wersji 2 zapoznaj się z zasobem properties.

Dostęp do prywatnych niestandardowych właściwości plików

Właściwości prywatne można pobierać tylko za pomocą pola appProperties za pomocą uwierzytelnionego żądania, które korzysta z tokena dostępu uzyskanego z identyfikatorem klienta OAuth 2.0. Nie można pobierać właściwości prywatnych za pomocą klucza interfejsu API.