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 procesu sprawdzania (np. w toku, zatwierdzono lub odrzucono), jak i osób sprawdzających. 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ą na elementach 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

1. 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 promocji.
   • Plik należy do użytkownika spoza Twojej domeny.
   • Użytkownik nie ma uprawnienia role=writer do pliku.

2. Udostępnij ręcznie 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

Podstawą procesu zatwierdzania są te kluczowe pojęcia.

Stan zatwierdzenia

Gdy poprosisz o zatwierdzenie dokumentu, proces zatwierdzania zapewni, że każdy recenzent będzie mógł przekazać swoje uwagi.

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.

Zachowanie zatwierdzenia, gdy zawartość pliku zostanie zmieniona w trakcie zatwierdzania, zależy od pola fileContentChangeBehavior zasobu approvals.StatusIN_PROGRESS Możesz zastosować te działania:

• RESET_APPROVAL: proces zatwierdzania zapewnia, że każda osoba zatwierdzająca zaakceptuje tę samą wersję treści. Jeśli plik zostanie zmodyfikowany po zatwierdzeniu prośby przez recenzenta, a przed jej zakończeniem, zatwierdzenia recenzenta zostaną zresetowane (odpowiedź zostanie przywrócona do stanu NO_RESPONSE), a recenzenci będą musieli zatwierdzić nową wersję. Gdy zatwierdzenie ma stan APPROVED, plik jest zablokowany, aby uniemożliwić dalsze modyfikacje. Dodatkowe zmiany w treści po ostatecznym zatwierdzeniu spowodują wyświetlenie w dokumencie banera informującego, że bieżąca wersja różni się od zatwierdzonej. Jest to zachowanie domyślne.

• NO_APPROVAL_ACTION: Edycje treści pliku nie resetują decyzji osób sprawdzających, gdy zatwierdzenie jest w toku. Dodatkowo plik nie jest blokowany po ostatecznym zatwierdzeniu. Recenzenci mogą też w każdej chwili przed zatwierdzeniem przywrócić własną APPROVED decyzję do stanu oczekującej (odpowiedź zostanie przywrócona do stanu NO_RESPONSE).

Po zatwierdzeniu to zachowanie przestanie obowiązywać.

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:

1. Rozpocznij proces zatwierdzania. Zadzwoń pod numer start, aby rozpocząć proces przesyłania prośby o zatwierdzenie. Wartość status zostanie ustawiona na IN_PROGRESS.

2. Oczekuje na zatwierdzenie. Gdy zatwierdzenie oczekuje na rozpatrzenie (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ę.

3. Zatwierdzenie 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 zatwierdzeniami

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 proces zatwierdzania

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 nie zostanie zrealizowane. Dodatkowo dostępne są 4 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.
• fileContentChangeBehavior: działanie zatwierdzenia, gdy zmieni się zawartość pliku. Obsługiwane wartości to:
  • RESET_APPROVAL: (Domyślnie) resetuje każdą odpowiedź osoby sprawdzającej APPROVED do NO_RESPONSE, gdy treść ulegnie zmianie w trakcie procesu zatwierdzania. Plik jest blokowany po zakończeniu procesu zatwierdzania ze stanem APPROVED.
  • NO_APPROVAL_ACTION: nie resetuje odpowiedzi sprawdzających, gdy treść ulegnie zmianie, i nie blokuje pliku po zakończeniu zatwierdzania.

Treść odpowiedzi zawiera instancję zasobu approvals i 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": [
     "[e-mail]",
     "[e-mail]"
    ],
    "dueTime": "2026-04-01T15:01:23Z",
    "lockFile": true,
    "message": "Please review this file for approval.",
    "fileContentChangeBehavior": "RESET_APPROVAL"
 }'

Zastąp te elementy:

• FILE_ID: identyfikator pliku, którego dotyczy 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 inicjującej zatwierdzanie i osób sprawdzających jako powiadomienie, a także jest 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 te elementy:

• FILE_ID: identyfikator pliku, którego dotyczy 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 poradzi sobie z jej rozpatrzeniem.

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ąć osobę sprawdzającą, 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": "[e-mail]"
    }
    ],
    "replaceReviewers": [
    {
        "addedReviewerEmail": "[e-mail]",
        "removedReviewerEmail": "[e-mail]"
    }
    ],
    "message": "Reassigning reviewers for this approval request."
 }'

Zastąp te elementy:

• FILE_ID: identyfikator pliku, którego dotyczy 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.

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. Zatwierdzenie Status ma stan CANCELLED i jest ukończone.

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 te elementy:

• FILE_ID: identyfikator pliku, którego dotyczy 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 prośby o zatwierdzenie.

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 jest ustawione na DECLINED i ma stan ukończony.

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 te elementy:

• FILE_ID: identyfikator pliku, którego dotyczy 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 operacji 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 te elementy:

• FILE_ID: identyfikator pliku, którego dotyczy 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 te elementy:

• FILE_ID: identyfikator pliku, którego dotyczy 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 formie approvals zasobu.

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. Należy ustawić 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 te elementy:

• FILE_ID: identyfikator pliku, którego dotyczy zatwierdzenie.
• ACCESS_TOKEN: token OAuth 2.0 aplikacji.

Powiązane artykuły

• Role i uprawnienia
• Zarządzanie zatwierdzeniami jako administrator
• Uzyskiwanie zatwierdzeń plików na Dysku Google