Omówienie interfejsu Drive Labels API

Etykiety to metadane, które definiujesz, aby ułatwić użytkownikom porządkowanie i znajdowanie plików oraz stosowanie do nich zasad na Dysku Google. Drive Labels API to interfejs RESTowy API, który obsługuje procesy biznesowe przez dołączanie metadanych do plików na Dysku. Typowe zastosowania tego interfejsu API:

• Klasyfikowanie treści w celu zachowania zgodności ze strategią zarządzania informacjami – utwórz etykietę w celu zidentyfikowania treści poufnych lub danych, które wymagają specjalnego traktowania. Możesz na przykład utworzyć etykietę z plakietką (oznaczoną kolorami opcjami) o nazwie „Czułość” z wartościami „Tajny klucz”, „Poufny” i „Publiczny”.

• Stosowanie zasad do elementów na Dysku – możesz tworzyć etykiety do zarządzania treściami na Dysku przez cały cykl życia i zadbać o to, aby były one zgodne z zasadami przechowywania danych obowiązującymi w organizacji. Za pomocą etykiet możesz na przykład zarządzać zasadami utraty danych, gdy nie można pobierać na komputer plików z etykietą „Czułość” z ustawioną wartością „Tajny klucz”.

• Wybór i znajdowanie plików – utwórz etykiety, aby zwiększyć wyszukiwanie treści firmy, umożliwiając użytkownikom w organizacji znajdowanie elementów na podstawie etykiet i ich pól. Na przykład ktoś w Twojej organizacji może skorzystać z opcji wyszukiwania na Dysku, aby znaleźć wszystkie umowy, które oczekują na podpis przed określoną datą.

Oto lista popularnych terminów używanych w interfejsie Drive Labels API:

Etykieta

Metadane strukturalne umieszczone w pliku na Dysku. Użytkownicy Dysku mogą przypisywać etykiety i ustawiać wartości pól etykiet w przypadku plików. Etykiety składają się z:

Nazwa etykiety

Nazwa zasobu etykiety. Identyfikator etykiety stanowi część nazwy etykiety. W zależności od żądania nazwa może mieć postać: labels/{id} lub labels/{id}@{revisionId}. Więcej informacji znajdziesz poniżej w sekcji Wersja etykiety.

Identyfikator etykiety

Niepowtarzalny globalnie identyfikator etykiety. Identyfikator stanowi część nazwy etykiety, ale w przeciwieństwie do niej jest spójny między wersjami.

Istnieją 2 style etykiet:

Etykieta z plakietką

Etykieta z typem pola SelectionOptions zawierającym wybory, które mogą być oznaczone kolorami, aby określić ich ważność. Aby to zrobić, ustaw badgeConfig za pomocą Properties metody Choice.

Dysk wyświetla kolor wybrany w przypadku każdego pliku, aby użytkownicy wiedzieli, jaki jest stan pliku, jego klasyfikacja itd. Na przykład opcja „Tajny obiekt tajny” dla etykiety „Czułość” może być wyświetlana na czerwono. Możesz mieć tylko 1 etykietę z plakietką.

Etykieta standardowa

Etykieta zawierająca zero lub więcej typów pól. Etykieta standardowa może mieć etykietę, np. „Projekt księżyca” i wskazywać wszystkie pliki związane z projektem. Etykieta standardowa może też mieć kilka pól uporządkowanych. Na przykład etykieta „Umowa” może zawierać pola „Firma”, „Termin”, „Stan” i „Sygnatariusze”. Każde pole musi być konkretnego typu (tekst, data, wybór lub użytkownik).

Pole

Wpisany przez użytkownika komponent etykiety, który można ustawić. Z etykietą może być powiązane zero lub więcej pól.

Typ pola

Typ danych wartości powiązanych z polem. Konfigurowalny jako tekst, liczba całkowita, data, użytkownik lub wybór. Jeśli skonfigurujesz to pole za pomocą atrybutu ListOptions, możesz ustawić pola użytkownika i wyboru z wieloma wartościami. Wybrany typ wpływa zarówno na prawidłowe wartości elementów Dysku, jak i dostępne opcje zapytania.

Wybór

Jedna z kilku opcji do wyboru w polu SelectionOptions.

Typ etykiety

Wszystkie etykiety zawierają element LabelType. Istnieją 2 typy etykiet:

Administracja

Aby tworzyć i edytować etykiety należące do administratora, musisz być administratorem konta z uprawnieniami Zarządzanie etykietami.

Administratorzy mogą udostępniać etykiety administratorom dowolnemu użytkownikowi, aby umożliwić mu wyświetlanie i stosowanie ich do elementów na Dysku. Modyfikowanie lub odczytywanie wartości etykiet w elementach na Dysku wymaga tych uprawnień:

• Modyfikowanie – aby użytkownik mógł modyfikować metadane elementu na Dysku związane z daną etykietą, musi mieć odpowiednie poziomy uprawnień:

  • Element na Dysku: EDITOR
  • Etykieta: APPLIER

• Odczyt – aby użytkownik mógł odczytywać lub wyszukiwać metadane elementu na Dysku związane z daną etykietą, musi mieć odpowiednie poziomy uprawnień:

  • Element na Dysku: READER
  • Etykieta: READER

Udostępnione

Użytkownicy bez uprawnień administratora mogą tworzyć udostępnione etykiety, które inni mogą stosować do elementów na Dysku. Zespoły mogą tworzyć i porządkować własne etykiety do użytku w zespole bez konieczności zarządzania kontem.

Taksonomia etykiet

Obecnie skonfigurowane pola etykiet dostępne dla użytkowników na potrzeby plików na Dysku. Nazywany także schematem etykiety.

Przykładowe taksonomie etykiet:

• Czułość – czerwony, pomarańczowy, żółty, zielony
• Stan – Nie rozpoczęto, Wersja robocza, W trakcie sprawdzania, Końcowy
• Typ treści – Umowa, Dokument projektowy, Mockup
• Dział – dział marketingu, finansów, działu kadr, sprzedaży

Cykl życia etykiet

Etykiety przechodzą cykl życia, w którym są tworzone, publikowane, aktualizowane itd. Etykieta przechodzi przez cały cykl życia, więc jej weryfikacja jest powiększona. Więcej informacji znajdziesz poniżej w sekcji Cykl życia etykiet.

Zmiana etykiety

Instancja etykiety. Za każdym razem, gdy etykieta jest tworzona, aktualizowana, publikowana lub wycofywana, następuje wzrost jej liczby.

Wersja robocza

Numer wersji bieżącego wystąpienia wersji roboczej etykiety. Możesz wprowadzić kilka aktualizacji etykiety, z których każda zwiększa numer wersji roboczej bez wpływu na opublikowaną wersję. Możliwość tworzenia wersji roboczych etykiet pozwala testować ich aktualizacje przed opublikowaniem.

Opublikowana wersja

Numer wersji opublikowanej etykiety. Opublikowana etykieta to wystąpienie etykiety obecnie dostępne dla użytkowników.

Cykl życia etykiet

Etykiety, pola i wybory na każdym etapie życia przechodzą przez konkretny stan. Dodatkowo etykiety mogą mieć różne wersje. Ten diagram przedstawia cykl życia etykiet z uwzględnieniem zmian:

1. Utwórz etykietę (create()) – zostanie utworzona i zapisana w bazie danych jako revision_id=1. Etykieta ma stan UNPUBLISHED_DRAFT. W tym stanie:
   • Użytkownicy nie mogą wyświetlać etykiety
   • Użytkownicy nie mogą stosować tej etykiety do elementów na Dysku.
2. (Opcjonalnie) Zaktualizuj etykietę, pole lub wybór (delta()) – każda aktualizacja, nawet przed jej opublikowaniem, jest przechowywana w bazie danych, a jej wersja jest zwiększana.
3. Opublikuj etykietę (publish()) – stan etykiety to PUBLISHED, a użytkownicy mogą ją zastosować. Opublikowanie etykiety powoduje zmniejszenie jej wersji.
4. (Opcjonalnie) Zaktualizuj etykietę, pole lub wybór (delta()) – etykieta, pole lub wybór zostaną zaktualizowane i zapisane w bazie danych jako wersja robocza etykiety. Etykieta ma stan PUBLISHED z wartością hasUnpublishedChanges=true, co oznacza, że są zmiany w wersji roboczej, ale nie są one dostępne dla użytkowników. Każda aktualizacja zwiększa wersję etykiety.
5. (Opcjonalnie) Opublikuj etykietę (publish()) – jeśli jest dostępna najnowsza wersja robocza, zostanie opublikowana. Etykieta ma stan PUBLISHED, a użytkownicy mogą ją stosować. Opublikowanie etykiety powoduje zwiększenie wersji.
6. Wyłącz etykietę (disable()) – stan etykiety to DISABLED, ale użytkownicy mogą ją zastosować za pomocą interfejsu API. Jednak wyłączona etykieta nie będzie widoczna w interfejsie, jeśli nie zostanie skonfigurowana. Wycofanie etykiety zwiększa jej wersję.
7. Włącz etykietę (enable()) – etykieta zostanie zwrócona do stanu PUBLISHED, a użytkownicy mogą ją zastosować. Opublikowanie etykiety powoduje zmniejszenie jej wersji.
8. Usuń etykietę (delete()) – stan etykiety to DELETED i nie można jej zastosować. Usunięte etykiety zostaną trwale usunięte.

Ważne jest, aby podkreślić, że każda aktualizacja etykiety zwiększa wartość jej zmiany. Jeśli etykieta została już opublikowana, opublikowanie nastąpi po ponownym wydaniu n, a numer wersji to nowe wydanie + n + 1 kolejna aktualizacja.

Dalsze kroki

• Więcej informacji o programowaniu z użyciem interfejsów Google Workspace API, w tym dotyczących uwierzytelniania i autoryzacji, znajdziesz w artykule Pierwsze kroki jako programista Workspace.

• Aby dowiedzieć się, jak skonfigurować i uruchomić prostą aplikację do obsługi etykiet, przeczytaj wprowadzenie.