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 przez aplikacje 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 w zasobie files. Aby dodać właściwości ograniczone do aplikacji, użyj pola appProperties zasobu files.

Usług 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.

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 i wyświetlanie niestandardowych właściwości pliku

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 niestandardowych właściwości 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 przypadku właściwości o kluczu składającym się z 10 znaków wartość może mieć maksymalnie 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 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żna używać klucza interfejsu API do pobierania usług prywatnych.