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

Niestandardowe właściwości pliku to pary klucz-wartość służące do przechowywania niestandardowych metadanych pliku na Dysku Google (np. tagów), identyfikatorów z innych repozytoriów danych, informacji udostępnianych między aplikacjami przepływu pracy itp. 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 w zasobie files. Aby dodać właściwości ograniczone do Twojej aplikacji, użyj pola appProperties w zasobie files.

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

Oto struktura typowej właściwości, która może być używana do przechowywania identyfikatora bazy danych pliku Dysku w pliku.

Drive API v3

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

Drive API w wersji 2

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

Praca z niestandardowymi właściwościami plików

W tej sekcji znajdziesz informacje o tym, jak wykonywać niektóre zadania związane z niestandardowymi właściwościami plików, 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, aby ustawić pole 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ć do pliku niestandardową właściwość, korzystając z zaawansowanej usługi Dysku w Google Apps Script. Więcej informacji znajdziesz w artykule Dodawanie właściwości niestandardowych.

Pobieranie lub wyświetlanie właściwości niestandardowych plików

Aby wyświetlić właściwości widoczne dla wszystkich aplikacji, użyj metody files.get, aby pobrać właściwości niestandardowe pliku.

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

Odpowiedź zawiera obiekt properties z kolekcją par klucz-wartość.

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

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

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

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

Aby wyświetlić zmianę, wywołaj metodę files.get, aby pobrać obiekt properties dla pliku.

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

Ograniczenia dotyczące niestandardowych właściwości plików

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

  • Maksymalnie 100 właściwości niestandardowych na plik, z uwzględnieniem wszystkich źródeł.
  • Maksymalnie 30 publicznych usług na plik, z uwzględnieniem wszystkich źródeł.
  • Maksymalnie 30 właściwości prywatnych na plik z dowolnej aplikacji.
  • Maksymalnie 124 bajty na ciąg znaków właściwości (w tym klucz i wartość) w kodowaniu UTF-8. Na przykład właściwościa z kluczem o długości 10 znaków może mieć w wartości tylko 114 znaków. Podobnie, jeśli właściwości wymagają 100 znaków, klucz może zawierać maksymalnie 24 znaki.

Więcej informacji znajdziesz w dokumentacji files. W przypadku interfejsu Drive API v2 zapoznaj się z dokumentacją properties.

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

Właściwości prywatne można pobierać tylko za pomocą pola appProperties w ramach uwierzytelnionego żądania, które używa tokena dostępu uzyskanego za pomocą identyfikatora klienta OAuth 2.0. Nie możesz używać klucza interfejsu API do pobierania właściwości prywatnych.