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 magazynó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 i 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 na wartość, klucz może zawierać maksymalnie 24 znaki.

Więcej informacji znajdziesz w dokumentacji files. W przypadku interfejsu Drive API w wersji 2 zapoznaj się z zasobem 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.