Google używa technologii AI do tłumaczenia treści na Twój preferowany język. Tłumaczenia wygenerowane przez AI mogą zawierać błędy.

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 uzyskać zatwierdzenie umowy lub oficjalnego dokumentu przed publikacją. Zatwierdzenie śledzi stan zarówno procesu sprawdzania (np. W toku, Zatwierdzono lub Odrzucono), jak i zaangażowanych weryfikatorów. Zatwierdzenia to doskonały sposób na weryfikację treści i prowadzenie rejestru weryfikatorów.

Możesz tworzyć zatwierdzenia treści i nimi zarządzać na Dysku. Interfejs Google Drive API udostępnia zasób approvals do pracy z zatwierdzeniami 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.

Zanim zaczniesz

Twój plik powinien zawierać możliwość 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 o możliwościach plików.

Możliwość logiczna canStartApproval ma wartość false, gdy:
- ustawienia administratora ograniczają dostęp do tej funkcji.
- Twoja wersja Google Workspace jest niekwalifikująca się.
- plik należy do użytkownika spoza Twojej domeny.
- użytkownik nie ma uprawnienia role=writer do pliku.
Upewnij się, że ręcznie udostępniasz plik docelowy recenzentom. Dysk nie robi tego automatycznie. Jeśli recenzent nie ma dostępu do pliku, prośba o zatwierdzenie zostanie zrealizowana, ale nie otrzyma on powiadomień ani nie będzie mógł wyświetlić pliku.

Pojęcia

Zatwierdzenia opierają się na tych kluczowych pojęciach.

Stan zatwierdzenia

Gdy poprosisz o zatwierdzenie dokumentu, proces zatwierdzania zapewni, że każdy recenzent będzie mógł wyrazić swoją opinię na temat dokumentu.

Zasób approvals zawiera obiekt Status, który szczegółowo opisuje stan zatwierdzenia w momencie wysłania żądania zasobu. Zawiera też obiekt ReviewerResponse, który szczegółowo opisuje odpowiedzi na zatwierdzenie udzielone przez konkretnych recenzentów. Odpowiedź każdego recenzenta jest reprezentowana przez obiekt Response.

Zachowanie zatwierdzenia, gdy treść pliku zostanie zmieniona, a stan zatwierdzenia Status to IN_PROGRESS, jest określone przez pole fileContentChangeBehavior zasobu approvals. Można zastosować te zachowania:

RESET_APPROVAL: proces zatwierdzania zapewnia, że każdy recenzent zatwierdzi tę samą wersję treści. Jeśli plik zostanie edytowany po zatwierdzeniu prośby przez recenzenta i 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 blokowany, aby uniemożliwić dalsze modyfikacje. Dodatkowe zmiany 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: zmiany w treści pliku nie powodują zresetowania decyzji recenzenta, gdy zatwierdzenie jest w toku. Ponadto plik nie jest blokowany po ostatecznym zatwierdzeniu. Recenzenci mogą też w dowolnym momencie przed zakończeniem zatwierdzenia zresetować swoją decyzję APPROVED do stanu oczekiwania (odpowiedź zostanie przywrócona do stanu NO_RESPONSE).

Po zakończeniu zatwierdzenia to zachowanie nie ma już zastosowania.

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

Wszyscy recenzenci muszą zatwierdzić zatwierdzenie. Każdy recenzent, który odrzuci zatwierdzenie, ustawi stan ukończenia na DECLINED.

Po zakończeniu zatwierdzenia (stan to APPROVED, CANCELLED lub DECLINED) pozostaje ono w stanie ukończonym i nie może być używane przez inicjatora ani recenzentów. Możesz dodawać komentarze do ukończonego zatwierdzenia, o ile nie ma zatwierdzenia pliku w stanie IN_PROGRESS.

Cykl życia zatwierdzenia

Podczas swojego cyklu życia zatwierdzenie przechodzi przez kilka stanów. Rysunek 1 przedstawia ogólne etapy cyklu życia zatwierdzenia:

Rozpoczęcie zatwierdzania. Aby rozpocząć prośbę o zatwierdzenie, wywołaj metodę start. Stan status zostanie ustawiony na IN_PROGRESS.
Zatwierdzenie oczekuje. Gdy zatwierdzenie oczekuje (status ma wartość IN_PROGRESS), zarówno inicjator, jak i recenzenci mogą z nim wchodzić w interakcję. Mogą dodawać comment, inicjator może reassign recenzentów, a co najmniej 1 recenzent może approve prośbę.
Zatwierdzenie jest w stanie ukończonym. Zatwierdzenie przechodzi w stan ukończony (status ma wartość APPROVED, CANCELLED lub DECLINED), gdy wszyscy recenzenci zatwierdzą prośbę, inicjator zdecyduje się cancel prośbę lub gdy którykolwiek recenzent zdecyduje się na decline prośby.

Używanie parametru fields

Aby pobrać szczegóły zatwierdzenia, musisz wyraźnie określić pola, które chcesz pobrać, używając fields systemowego parametru z dowolną metodą zasobu approvals. W przeciwieństwie do innych zasobów metody zasobu approvals nie zwracają domyślnego zestawu pól, gdy parametr fields jest pominięty. Więcej informacji znajdziesz w artykule Zwracanie określonych pól.

Rozpoczynanie zatwierdzania i zarządzanie nim

Zasób approvals może służyć do rozpoczynania zatwierdzania i zarządzania nim za pomocą interfejsu Drive API. Te metody działają z dowolnym z istniejących zakresów OAuth 2.0 interfejsu Drive API, które umożliwiają zapisywanie metadanych pliku. Więcej informacji znajdziesz w artykule Wybieranie zakresów interfejsu Google Drive API.

Rozpoczęcie zatwierdzania

Aby rozpocząć nowe zatwierdzenie pliku, użyj metody start w zasobie approvals i dodaj 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. Dostępne są też 4 pola opcjonalne:

dueTime: termin zatwierdzenia w formacie RFC 3339.
lockFile: wartość logiczna wskazująca, czy plik ma być zablokowany podczas rozpoczynania zatwierdzania. Uniemożliwia to użytkownikom modyfikowanie pliku podczas procesu zatwierdzania. Każdy użytkownik z uprawnieniem role=writer może usunąć tę blokadę.
message: niestandardowa wiadomość wysłana do recenzentów.
fileContentChangeBehavior: zachowanie zatwierdzenia, gdy treść pliku ulegnie zmianie. Obsługiwane wartości:
- RESET_APPROVAL: (domyślnie) resetuje każdą odpowiedź recenzenta APPROVED do NO_RESPONSE, gdy treść ulegnie zmianie podczas zatwierdzania. Plik jest blokowany po zakończeniu zatwierdzenia ze stanem APPROVED.
- NO_APPROVAL_ACTION: nie resetuje odpowiedzi recenzenta, gdy treść ulegnie zmianie, i nie blokuje pliku po zakończeniu zatwierdzenia.

Treść odpowiedzi zawiera instancję zasobu approvals i zawiera initiator pole które jest użytkownikiem, który poprosił o zatwierdzenie. Stan zatwierdzenia Status jest ustawiony na IN_PROGRESS.

Jeśli istnieje zatwierdzenie ze Status IN_PROGRESS, start się nie powiedzie. Zatwierdzenie możesz rozpocząć tylko wtedy, gdy plik nie ma zatwierdzenia lub gdy istniejące zatwierdzenie jest w stanie ukończonym (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.",
    "fileContentChangeBehavior": "RESET_APPROVAL"
 }'

Zastąp te elementy:

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

Komentowanie zatwierdzenia

Aby skomentować zatwierdzenie, użyj metody comment w zasobie approvals i dodaj 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 inicjatora zatwierdzenia i recenzentów jako powiadomienie, a także jest uwzględniana w dzienniku aktywności zatwierdzania.

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 Twojej aplikacji.

Ponowne przypisywanie recenzentów do zatwierdzenia

Aby ponownie przypisać recenzentów do zatwierdzenia, użyj metody reassign w zasobie approvals i dodaj parametry ścieżki fileId i approvalId.

Metoda reassign umożliwia inicjatorowi zatwierdzenia (lub użytkownikowi z uprawnieniem 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 jest bardziej kompetentnym recenzentem.

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

Pamiętaj, że nie możesz usunąć recenzenta z zatwierdzenia. Jeśli chcesz usunąć recenzenta, musisz anulować zatwierdzenie i rozpocząć nowe.

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

Treść odpowiedzi zawiera instancję zasobu approvals. Wiadomość jest wysyłana do nowych recenzentów jako powiadomienie, a także jest uwzględniana w dzienniku aktywności zatwierdzania.

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

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

Anulowanie zatwierdzenia

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

Metodę cancel może wywołać tylko inicjator zatwierdzenia (lub użytkownik z uprawnieniem role=writer), 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ą anulowaniu zatwierdzenia.

Treść odpowiedzi zawiera instancję zasobu approvals. Wiadomość jest wysyłana jako powiadomienie, a także jest uwzględniana w dzienniku aktywności zatwierdzania. Stan zatwierdzenia Status jest ustawiony na CANCELLED i jest w stanie ukończonym.

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 Twojej aplikacji.

Odrzucanie zatwierdzenia

Aby odrzucić zatwierdzenie, użyj metody decline w zasobie approvals i dodaj 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, a także jest uwzględniana w dzienniku aktywności zatwierdzania. Pole response obiektu ReviewerResponse użytkownika wysyłającego żądanie jest ustawione na DECLINED. Ponadto stan zatwierdzenia Status jest ustawiony na 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 te elementy:

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

Zatwierdzanie zatwierdzenia

Aby zatwierdzić zatwierdzenie, użyj metody approve w zasobie approvals i dodaj 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, a także jest uwzględniana w dzienniku aktywności zatwierdzania. Pole response obiektu ReviewerResponse użytkownika wysyłającego żądanie jest ustawione na APPROVED. Ponadto, jeśli jest to ostatnia wymagana odpowiedź recenzenta, stan zatwierdzenia Status jest ustawiony na APPROVED i jest w stanie ukończonym.

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 Twojej 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 pliku, musisz mieć uprawnienia do odczytu metadanych pliku. Więcej informacji znajdziesz w artykule Role i uprawnienia.

Pobieranie zatwierdzenia

Aby pobrać zatwierdzenie pliku, użyj metody get w zasobie approvals z parametrami ścieżki fileId i approvalId path. 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 Twojej aplikacji.

Wyświetlanie listy zatwierdzeń

Aby wyświetlić listę zatwierdzeń pliku, wywołaj metodę list w zasobie approvalsi dodaj parametr ścieżki fileId.

Treść odpowiedzi składa się z listy zatwierdzeń pliku. Pole items zawiera informacje o każdym zatwierdzeniu w postaci zasobu approvals.

Możesz też przekazać te parametry zapytania, aby dostosować stronicowanie lub filtrowanie zatwierdzeń:

pageSize: maksymalna liczba zatwierdzeń do zwrócenia na stronie. Jeśli nie ustawisz parametru 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 go ustawić na wartość nextPageToken z poprzedniej odpowiedzi.

curl

curl -X GET \
  'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals?pageSize=10&fields=nextPageToken,items(approvalId,status)' \
  -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 Twojej 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 zatwierdzenia

Używanie parametru fields

Rozpoczynanie zatwierdzania i zarządzanie nim

Rozpoczęcie zatwierdzania

curl

Komentowanie zatwierdzenia

curl

Ponowne przypisywanie recenzentów do zatwierdzenia

curl

Anulowanie zatwierdzenia

curl

Odrzucanie zatwierdzenia

curl

Zatwierdzanie zatwierdzenia

curl

Znajdowanie istniejących zatwierdzeń

Pobieranie zatwierdzenia

curl

Wyświetlanie listy zatwierdzeń

curl

Powiązane artykuły

Zarządzanie zatwierdzeniami