Zarządzanie zatwierdzeniami

Z tego dokumentu dowiesz się, jak zarządzać zatwierdzeniami w interfejsie Google Drive API.

Użytkownicy mogą wysyłać dokumenty z Dysku Google do formalnego zatwierdzenia. Możesz skorzystać z tego procesu, aby na przykład uzyskać formalne zatwierdzenie umowy lub oficjalnego dokumentu przed opublikowaniem. Zatwierdzenie śledzi stan zarówno sprawdzania (np. w toku, zatwierdzone lub odrzucone), jak i zaangażowanych w nie osób. Zatwierdzenia to doskonały sposób na potwierdzenie treści i prowadzenie rejestru recenzentów.

Możesz tworzyć zatwierdzenia treści i nimi zarządzać na Dysku. Interfejs Google Drive API udostępnia zasób approvals do obsługi zatwierdzania plików. Metody zasobu approvals działają w przypadku elementów na Dysku, w Dokumentach Google i innych edytorach Google Workspace. Recenzenci mogą zatwierdzać i odrzucać dokumenty oraz wystawiać opinie na ich temat bezpośrednio w usłudze.

Zanim zaczniesz

Plik powinien zawierać funkcję canStartApproval . Aby sprawdzić możliwości pliku, wywołaj metodę get w zasobie files z parametrem ścieżki fileId i użyj pola możliwości canStartApproval w parametrze fields. Więcej informacji znajdziesz w artykule Omówienie funkcji plików.

Wartość logiczna canStartApproval ma wartość false, gdy:
- Ustawienia administratora ograniczają dostęp do tej funkcji.
- Twoja wersja Google Workspace nie kwalifikuje się do tej oferty.
- Plik należy do użytkownika spoza Twojej domeny.
- Użytkownik nie ma uprawnienia role=writer do pliku.
Pamiętaj, aby ręcznie udostępnić plik docelowy recenzentom. Dysk nie robi tego automatycznie. Jeśli recenzent nie ma dostępu do pliku, prośba o zatwierdzenie zostanie wysłana, ale recenzent nie otrzyma powiadomień ani nie będzie mógł wyświetlić pliku.

Pojęcia

U podstaw procesu zatwierdzania leżą te kluczowe pojęcia:

Stan zatwierdzenia

Gdy poprosisz o zatwierdzenie dokumentu, proces zatwierdzania zapewni, że każdy recenzent zatwierdzi tę samą wersję treści. Jeśli plik zostanie zmodyfikowany po zatwierdzeniu prośby przez recenzenta, a przed zakończeniem prośby, zatwierdzenia recenzenta zostaną zresetowane i recenzenci będą musieli zatwierdzić nową wersję. Jeśli treść zostanie zmieniona po ostatecznym zatwierdzeniu, w dokumencie pojawi się baner informujący, że bieżąca wersja różni się od zatwierdzonej.

Zasób approvals zawiera obiekt Status, który zawiera szczegółowe informacje o stanie zatwierdzenia w momencie wysłania żądania zasobu. Zawiera też obiekt ReviewerResponse, który zawiera szczegółowe informacje o odpowiedziach na zatwierdzenie dokonane przez konkretnych weryfikatorów. Odpowiedź każdego recenzenta jest reprezentowana przez obiekt Response.

Każda czynność w procesie zatwierdzania generuje powiadomienia e-mail, które są wysyłane do inicjatora (użytkownika, który prosi o zatwierdzenie) i wszystkich recenzentów. Jest on też dodawany do dziennika aktywności dotyczącej zatwierdzania.

Wszyscy recenzenci muszą zatwierdzić prośbę o zatwierdzenie. Jeśli weryfikator odrzuci zatwierdzenie, stan ukończenia zostanie ustawiony na DECLINED.

Po zakończeniu procesu zatwierdzania (stan to APPROVED, CANCELLED lub DECLINED) pozostaje on w stanie ukończenia i nie można go zmienić. Możesz dodawać komentarze do zakończonego zatwierdzenia, o ile w pliku nie ma zatwierdzenia o stanie IN_PROGRESS.

Cykl życia zgody

**Rysunek 1.** Cykl życia zatwierdzenia.

Podczas swojego cyklu życia zatwierdzenie przechodzi przez kilka stanów. Na rysunku 1 przedstawiono ogólne etapy cyklu życia zatwierdzania:

Rozpocznij zatwierdzanie. Zadzwoń pod numer start, aby rozpocząć proces przesyłania prośby o zatwierdzenie. Wartość status zostanie ustawiona na IN_PROGRESS.
Oczekuje na zatwierdzenie. Gdy zatwierdzenie oczekuje na decyzję (status ma wartość IN_PROGRESS), zarówno inicjator, jak i osoby sprawdzające mogą wchodzić z nim w interakcję. Mogą oni dodać comment, inicjator może reassign recenzentów, a co najmniej jeden recenzent może approve prośbę.
Zatwierdzanie zostało zakończone. Zatwierdzenie przechodzi w stan ukończony (status zmienia się na APPROVED, CANCELLED lub DECLINED), gdy wszyscy recenzenci zatwierdzą prośbę, inicjator zdecyduje się na cancel prośbę lub gdy którykolwiek z recenzentów zdecyduje się na decline prośbę.

Używanie parametru fields

Jeśli chcesz określić pola, które mają być zwracane w odpowiedzi, możesz ustawić fields parametr system w dowolnej metodzie zasobu approvals. Jeśli pominiesz parametr fields, serwer zwróci domyślny zestaw pól specyficznych dla danej metody. Aby zwrócić inne pola, zobacz Zwracanie określonych pól.

Rozpoczynanie i administrowanie zatwierdzaniem

Zasób approvals może służyć do rozpoczynania i zarządzania zatwierdzaniem przy użyciu interfejsu Drive API. Te metody działają z dowolnym z dotychczasowych zakresów interfejsu Drive API OAuth 2.0, które umożliwiają zapisywanie metadanych plików. Więcej informacji znajdziesz w artykule Wybieranie zakresów interfejsu Google Drive API.

Rozpocznij zatwierdzanie

Aby rozpocząć nową prośbę o zatwierdzenie pliku, użyj metody start w zasobie approvals i uwzględnij parametr ścieżki fileId.

Treść żądania składa się z wymaganego pola reviewerEmails, które jest tablicą ciągów znaków zawierającą adresy e-mail recenzentów przypisanych do sprawdzenia pliku. Każdy adres e-mail recenzenta musi być powiązany z kontem Google, w przeciwnym razie żądanie się nie powiedzie. Dodatkowo dostępne są 3 pola opcjonalne:

dueTime: termin zatwierdzenia w formacie RFC 3339.
lockFile: wartość logiczna wskazująca, czy plik ma być zablokowany po rozpoczęciu procesu zatwierdzania. Uniemożliwia to użytkownikom modyfikowanie pliku podczas procesu zatwierdzania. Każdy użytkownik z uprawnieniami role=writer może usunąć tę blokadę.
message: Wiadomość niestandardowa wysłana do recenzentów.

Treść odpowiedzi zawiera instancję zasobu approvals, w tym pole initiator, które wskazuje użytkownika, który poprosił o zatwierdzenie. Zatwierdzenie Status jest ustawione na IN_PROGRESS.

Jeśli istnieje zatwierdzenie z wartością Status równą IN_PROGRESS, metoda start zwróci błąd. Proces zatwierdzania możesz rozpocząć tylko wtedy, gdy plik nie oczekuje na zatwierdzenie lub gdy proces zatwierdzania został zakończony (stan to APPROVED, CANCELLED lub DECLINED).

curl

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals:start' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "reviewerEmails": [
     "reviewer1@example.com",
     "reviewer2@example.com"
    ],
    "dueTime": "2026-04-01T15:01:23Z",
    "lockFile": true,
    "message": "Please review this file for approval."
 }'

Zastąp następujące elementy:

FILE_ID: identyfikator pliku, w którym znajduje się zatwierdzenie.
ACCESS_TOKEN: token OAuth 2.0 aplikacji.

Komentarz do zatwierdzenia

Aby skomentować zatwierdzenie, użyj metody comment w zasobie approvals i dołącz parametry ścieżki fileId i approvalId.

Treść żądania składa się z wymaganego pola message, które jest ciągiem znaków zawierającym komentarz, który chcesz dodać do zatwierdzenia.

Treść odpowiedzi zawiera instancję zasobu approvals. Wiadomość jest wysyłana do osoby, która zainicjowała proces zatwierdzania, oraz do recenzentów jako powiadomienie. Jest ona również uwzględniana w dzienniku aktywności związanej z zatwierdzaniem.

curl

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID:comment' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "message": "The required comment on the approval."
 }'

Zastąp następujące elementy:

FILE_ID: identyfikator pliku, w którym znajduje się zatwierdzenie.
APPROVAL_ID: identyfikator zatwierdzenia.
ACCESS_TOKEN: token OAuth 2.0 aplikacji.

Ponowne przypisywanie recenzentów po zatwierdzeniu

Aby ponownie przypisać osoby sprawdzające do zatwierdzenia, użyj metody reassign w zasobie approvals i uwzględnij parametry ścieżki fileId i approvalId.

Metoda reassign umożliwia inicjatorowi zatwierdzenia (lub użytkownikowi z uprawnieniami role=writer) dodawanie lub zastępowanie recenzentów w obiekcie ReviewerResponse zasobu approvals. Użytkownik z uprawnieniem role=reader może ponownie przypisać tylko zatwierdzenie, które jest przypisane do niego. Umożliwia to użytkownikowi ponowne przypisanie prośby do innej osoby, która lepiej się do tego nadaje.

Weryfikatorów można przypisać ponownie tylko wtedy, gdy Status ma stan IN_PROGRESS, a pole response weryfikatora, który ma zostać przypisany ponownie, ma wartość NO_RESPONSE.

Pamiętaj, że nie możesz usunąć osoby sprawdzającej z zatwierdzenia. Jeśli chcesz usunąć recenzenta, musisz anulować zatwierdzenie i rozpocząć proces od nowa.

Treść żądania składa się z opcjonalnych pól addReviewers i replaceReviewers. Każde pole ma powtarzający się obiekt dla funkcji AddReviewer i ReplaceReviewer, z których każdy zawiera pojedynczego weryfikatora do dodania lub parę weryfikatorów do zastąpienia. Możesz też dodać opcjonalne pole message zawierające komentarz, który chcesz wysłać do nowych weryfikatorów.

Treść odpowiedzi zawiera instancję zasobu approvals. Wiadomość jest wysyłana do nowych weryfikatorów jako powiadomienie i jest też uwzględniana w dzienniku aktywności związanej z zatwierdzaniem.

curl

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID:reassign' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "addReviewers": [
    {
        "addedReviewerEmail": "new_reviewer@example.com"
    }
    ],
    "replaceReviewers": [
    {
        "addedReviewerEmail": "replacement_reviewer@example.com",
        "removedReviewerEmail": "old_reviewer@example.com"
    }
    ],
    "message": "Reassigning reviewers for this approval request."
 }'

Zastąp następujące elementy:

FILE_ID: identyfikator pliku, w którym znajduje się zatwierdzenie.
APPROVAL_ID: identyfikator zatwierdzenia.
ACCESS_TOKEN: token OAuth 2.0 aplikacji.

Anulowanie zatwierdzenia

Aby anulować zatwierdzenie, użyj metody cancel w zasobie approvals i uwzględnij parametry ścieżki fileId i approvalId.

Metodę cancel może wywołać tylko inicjator zatwierdzenia (lub użytkownik z uprawnieniem role=writer), gdy zatwierdzenie Status ma stan IN_PROGRESS.

Treść żądania składa się z opcjonalnego pola message, które jest ciągiem znaków zawierającym wiadomość towarzyszącą anulowaniu zatwierdzenia.

curl

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID:cancel' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "message": "The optional reason for cancelling this approval request."
 }'

Zastąp następujące elementy:

FILE_ID: identyfikator pliku, w którym znajduje się zatwierdzenie.
APPROVAL_ID: identyfikator zatwierdzenia.
ACCESS_TOKEN: token OAuth 2.0 aplikacji.

Odrzucanie zatwierdzenia

Aby odrzucić zatwierdzenie, użyj metody decline w zasobie approvals i dołącz parametry ścieżki fileId i approvalId.

Metodę decline można wywołać tylko wtedy, gdy stan zatwierdzenia Status to IN_PROGRESS.

Treść żądania składa się z opcjonalnego pola message, które jest ciągiem znaków zawierającym wiadomość towarzyszącą odrzuceniu zatwierdzenia.

Treść odpowiedzi zawiera instancję zasobu approvals. Wiadomość jest wysyłana jako powiadomienie i jest też uwzględniana w dzienniku aktywności związanej z zatwierdzaniem. Pole response obiektu ReviewerResponse użytkownika wysyłającego żądanie jest ustawione na DECLINED. Dodatkowo zatwierdzenie Status ma wartość DECLINED i jest w stanie ukończonym.

curl

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID:decline' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "message": "The optional reason for declining this approval request."
 }'

Zastąp następujące elementy:

FILE_ID: identyfikator pliku, w którym znajduje się zatwierdzenie.
APPROVAL_ID: identyfikator zatwierdzenia.
ACCESS_TOKEN: token OAuth 2.0 aplikacji.

Zatwierdzanie zatwierdzenia

Aby zatwierdzić prośbę o zatwierdzenie, użyj metody approve w zasobie approvals i uwzględnij parametry ścieżki fileId i approvalId.

Metodę approve można wywołać tylko wtedy, gdy stan zatwierdzenia Status to IN_PROGRESS.

Treść żądania składa się z opcjonalnego pola message, które jest ciągiem znaków zawierającym wiadomość towarzyszącą zatwierdzeniu.

Treść odpowiedzi zawiera instancję zasobu approvals. Wiadomość jest wysyłana jako powiadomienie i jest też uwzględniana w dzienniku aktywności związanej z zatwierdzaniem. Pole response obiektu ReviewerResponse użytkownika wysyłającego żądanie jest ustawione na APPROVED. Jeśli jest to ostatnia wymagana odpowiedź recenzenta, stan zatwierdzenia Status zostanie ustawiony na APPROVED, a stan żądania zostanie zmieniony na „ukończono”.

curl

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID:approve' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "message": "The optional reason for approving this approval request."
 }'

Zastąp następujące elementy:

FILE_ID: identyfikator pliku, w którym znajduje się zatwierdzenie.
APPROVAL_ID: identyfikator zatwierdzenia.
ACCESS_TOKEN: token OAuth 2.0 aplikacji.

Znajdowanie istniejących zatwierdzeń

Zasób approvals może też służyć do pobierania i wyświetlania stanu zatwierdzeń za pomocą interfejsu Drive API.

Aby wyświetlić zatwierdzenia w pliku, musisz mieć uprawnienia do odczytu jego metadanych. Więcej informacji znajdziesz w artykule Role i uprawnienia.

Uzyskiwanie zatwierdzenia

Aby uzyskać zatwierdzenie pliku, użyj metody get w zasobie approvals z parametrami ścieżki fileId i approvalId. Jeśli nie znasz identyfikatora zatwierdzenia, możesz wyświetlić listę zatwierdzeń za pomocą metody list.

Treść odpowiedzi zawiera instancję zasobu approvals.

curl

curl -X GET 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Accept: application/json'

Zastąp następujące elementy:

FILE_ID: identyfikator pliku, w którym znajduje się zatwierdzenie.
APPROVAL_ID: identyfikator zatwierdzenia.
ACCESS_TOKEN: token OAuth 2.0 aplikacji.

Wyświetlanie listy zatwierdzeń

Aby wyświetlić listę zatwierdzeń pliku, wywołaj metodę list w zasobie approvals i uwzględnij parametr ścieżki fileId.

Treść odpowiedzi zawiera listę zatwierdzeń pliku. Pole items zawiera informacje o każdym zatwierdzeniu w postaci zasobu approvals.

Możesz też przekazywać te parametry zapytania, aby dostosować paginację lub filtrowanie zatwierdzeń:

pageSize: maksymalna liczba zatwierdzeń do zwrócenia na stronie. Jeśli nie ustawisz wartości pageSize, serwer zwróci maksymalnie 100 zatwierdzeń.
pageToken: token strony otrzymany z poprzedniego wywołania listy. Ten token służy do pobierania kolejnej strony. Powinna być ustawiona na wartość nextPageToken z poprzedniej odpowiedzi.

curl

curl -X GET 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals?pageSize=10' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Accept: application/json'

Zastąp następujące elementy:

FILE_ID: identyfikator pliku, w którym znajduje się zatwierdzenie.
ACCESS_TOKEN: token OAuth 2.0 aplikacji.

Zarządzanie zatwierdzeniami Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Zanim zaczniesz

Pojęcia

Stan zatwierdzenia

Cykl życia zgody

Używanie parametru fields

Rozpoczynanie i administrowanie zatwierdzaniem

Rozpocznij zatwierdzanie

curl

Komentarz do zatwierdzenia

curl

Ponowne przypisywanie recenzentów po zatwierdzeniu

curl

Anulowanie zatwierdzenia

curl

Odrzucanie zatwierdzenia

curl

Zatwierdzanie zatwierdzenia

curl

Znajdowanie istniejących zatwierdzeń

Uzyskiwanie zatwierdzenia

curl

Wyświetlanie listy zatwierdzeń

curl

Powiązane artykuły

Zarządzanie zatwierdzeniami