Genehmigungen verwalten

In diesem Dokument wird beschrieben, wie Sie Genehmigungen in der Google Drive API verwalten.

Nutzer können Dokumente in Google Drive durch ein formelles Genehmigungsverfahren laufen lassen. Dies eignet sich beispielsweise für die Genehmigung von Vertragsprüfungen oder offiziellen Dokumenten vor der Veröffentlichung. Eine Genehmigung gibt den Status der Überprüfung (z. B. „Wird verarbeitet“, „Genehmigt“ oder „Abgelehnt“) und die beteiligten Prüfer an. Genehmigungen sind eine hervorragende Möglichkeit, Inhalte zu validieren und eine Aufzeichnung von Prüfern zu führen.

Sie können Inhaltsgenehmigungen in Drive erstellen und verwalten. Die Google Drive API bietet die approvals-Ressource für die Arbeit mit Dateigenehmigungen. Die Methoden der approvals-Ressource funktionieren für Elemente in Drive, Google Docs und anderen Google Workspace-Editoren. Prüfer haben dabei die Möglichkeit, die Dokumente direkt zu genehmigen, abzulehnen oder Feedback dazu zu geben.

Hinweis

Ihre Datei sollte die Funktion canStartApproval enthalten . Rufen Sie zum Prüfen der Dateifunktionen die Methode get für die Ressource files mit dem Pfadparameter fileId auf und verwenden Sie das Feld canStartApproval im Parameter fields. Weitere Informationen finden Sie unter Dateifunktionen.

Die boolesche Funktion canStartApproval ist false, wenn:
- Der Zugriff auf die Funktion wird durch Administratoreinstellungen eingeschränkt.
- Ihre Google Workspace-Version ist nicht berechtigt.
- Die Datei gehört einem Nutzer außerhalb Ihrer Domain.
- Der Nutzer hat nicht die Berechtigung role=writer für die Datei.
Geben Sie die Zieldatei manuell für die Prüfer frei. In Google Drive geschieht das nicht automatisch. Wenn ein Prüfer keinen Dateizugriff hat, wird die Genehmigungsanfrage zwar gesendet, er erhält aber keine Benachrichtigungen und kann die Datei nicht ansehen.

Konzepte

Die folgenden Schlüsselkonzepte bilden die Grundlage für Genehmigungen.

Freigabestatus

Wenn Sie die Genehmigung eines Dokuments anfordern, wird durch den Genehmigungsprozess sichergestellt, dass jeder Prüfer dieselbe Version der Inhalte genehmigt. Wenn die Datei bearbeitet wird, nachdem ein Prüfer die Anfrage genehmigt hat, aber bevor die Anfrage abgeschlossen ist, werden die Genehmigungen des Prüfers zurückgesetzt und die Prüfer müssen die neue Version genehmigen. Wenn der Inhalt nach der endgültigen Genehmigung bearbeitet wird, wird im Dokument ein Banner angezeigt, das darauf hinweist, dass sich die aktuelle Version von der genehmigten Version unterscheidet.

Die approvals-Ressource enthält ein Status-Objekt, in dem der Status der Genehmigung angegeben ist, wenn die Ressource angefordert wird. Es enthält auch das ReviewerResponse-Objekt, in dem die Antworten auf eine Genehmigung durch bestimmte Prüfer aufgeführt sind. Die Antwort jedes Rezensenten wird durch das Response-Objekt dargestellt.

Bei jeder Aktion im Genehmigungsprozess werden E‑Mail-Benachrichtigungen an den Initiator (den Nutzer, der die Genehmigung anfordert) und alle Prüfer gesendet. Sie wird auch dem Genehmigungsaktivitätsprotokoll hinzugefügt.

Alle Prüfer müssen eine Genehmigung erteilen. Wenn ein Prüfer eine Genehmigung ablehnt, wird der Status „Abgeschlossen“ auf DECLINED gesetzt.

Nachdem eine Genehmigung abgeschlossen ist (der Status ist APPROVED, CANCELLED oder DECLINED), bleibt sie im abgeschlossenen Status und kann nicht mehr vom Initiator oder den Prüfern bearbeitet werden. Sie können einer abgeschlossenen Genehmigung Kommentare hinzufügen, sofern für eine Datei mit dem Status IN_PROGRESS keine Genehmigung vorhanden ist.

Lebenszyklus einer Genehmigung

Eine Genehmigung durchläuft während ihres Lebenszyklus mehrere Status. Abbildung 1 zeigt die allgemeinen Schritte im Lebenszyklus einer Genehmigung:

Genehmigung starten Rufen Sie start auf, um die Genehmigungsanfrage zu starten. status wird dann auf IN_PROGRESS gesetzt.
Genehmigung ausstehend Während die Genehmigung aussteht (status ist auf IN_PROGRESS gesetzt), können sowohl der Initiator als auch die Prüfer damit interagieren. Sie können eine comment hinzufügen, der Initiator kann reassign Prüfer und ein oder mehrere Prüfer können den Antrag approve.
Die Genehmigung ist abgeschlossen. Eine Genehmigung wechselt in den Status „Abgeschlossen“ (status wird auf APPROVED, CANCELLED oder DECLINED gesetzt), wenn alle Prüfer die Anfrage genehmigen, der Initiator die Anfrage cancel oder ein Prüfer die Anfrage decline.

Parameter „fields“ verwenden

Wenn Sie die Felder angeben möchten, die in der Antwort zurückgegeben werden sollen, können Sie den fields-Systemparameter mit einer beliebigen Methode der approvals-Ressource festlegen. Wenn Sie den Parameter fields weglassen, gibt der Server eine Standardgruppe von Feldern zurück, die für die Methode spezifisch ist. Informationen zum Zurückgeben anderer Felder finden Sie unter Bestimmte Felder zurückgeben.

Genehmigungen starten und verwalten

Mit der approvals-Ressource können Genehmigungen über die Drive API gestartet und verwaltet werden. Diese Methoden funktionieren mit allen vorhandenen OAuth 2.0-Bereichen der Drive API, die das Schreiben von Dateimetadaten ermöglichen. Weitere Informationen finden Sie unter Google Drive API-Bereiche auswählen.

Genehmigung starten

Wenn Sie eine neue Genehmigung für eine Datei starten möchten, verwenden Sie die Methode start für die Ressource approvals und fügen Sie den Pfadparameter fileId ein.

Der Anfragetext besteht aus dem erforderlichen Feld reviewerEmails, das ein Array von Strings mit den E‑Mail-Adressen der Prüfer enthält, die die Datei prüfen sollen. Jede E-Mail-Adresse des Prüfers muss mit einem Google-Konto verknüpft sein, da die Anfrage sonst fehlschlägt. Außerdem gibt es drei optionale Felder:

dueTime: Die Frist für die Genehmigung im RFC 3339-Format.
lockFile: Ein boolescher Wert, der angibt, ob die Datei beim Starten der Genehmigung gesperrt werden soll. Dadurch wird verhindert, dass Nutzer die Datei während des Genehmigungsprozesses ändern können. Jeder Nutzer mit der Berechtigung role=writer kann diese Sperre entfernen.
message: Eine benutzerdefinierte Nachricht, die an Rezensenten gesendet wird.

Der Antworttext enthält eine Instanz der approvals-Ressource und das Feld initiator, das den Nutzer enthält, der die Genehmigung angefordert hat. Die Genehmigung Status ist auf IN_PROGRESS festgelegt.

Wenn eine vorhandene Genehmigung mit einem Status von IN_PROGRESS vorhanden ist, schlägt die Methode start fehl. Sie können eine Genehmigung nur starten, wenn für die Datei keine Genehmigung vorhanden ist oder die vorhandene Genehmigung abgeschlossen ist (Status APPROVED, CANCELLED oder 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."
 }'

Ersetzen Sie Folgendes:

FILE_ID: Die ID der Datei, für die die Genehmigung gilt.
ACCESS_TOKEN: Das OAuth 2.0-Token Ihrer App.

Kommentar zur Genehmigung

Wenn Sie einen Kommentar zu einer Genehmigung abgeben möchten, verwenden Sie die Methode comment für die Ressource approvals und fügen Sie die Pfadparameter fileId und approvalId ein.

Der Anfragetext besteht aus dem erforderlichen Feld message, das einen String mit dem Kommentar enthält, den Sie der Genehmigung hinzufügen möchten.

Der Antworttext enthält eine Instanz der approvals-Ressource. Die Nachricht wird als Benachrichtigung an den Initiator und die Prüfer der Genehmigung gesendet und ist auch im Aktivitätsprotokoll für die Genehmigung enthalten.

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."
 }'

Ersetzen Sie Folgendes:

FILE_ID: Die ID der Datei, für die die Genehmigung gilt.
APPROVAL_ID: Die ID der Genehmigung.
ACCESS_TOKEN: Das OAuth 2.0-Token Ihrer App.

Prüfer bei Genehmigung neu zuweisen

Wenn Sie Prüfer für eine Genehmigung neu zuweisen möchten, verwenden Sie die Methode reassign für die Ressource approvals und fügen Sie die Pfadparameter fileId und approvalId ein.

Mit der Methode reassign kann der Initiator der Genehmigung (oder ein Nutzer mit der Berechtigung role=writer) Prüfer im ReviewerResponse-Objekt der approvals-Ressource hinzufügen oder ersetzen. Ein Nutzer mit der Berechtigung role=reader kann nur eine Genehmigung neu zuweisen, die ihm selbst zugewiesen ist. So kann der Nutzer eine Anfrage einer anderen Person zuweisen, die besser für die Überprüfung geeignet ist.

Prüfer können nur neu zugewiesen werden, wenn Status auf IN_PROGRESS gesetzt ist und das Feld response für den neu zugewiesenen Prüfer auf NO_RESPONSE gesetzt ist.

Hinweis: Sie können einen Prüfer nicht aus einer Genehmigung entfernen. Wenn Sie einen Prüfer entfernen möchten, müssen Sie die Genehmigung abbrechen und eine neue starten.

Der Anfragetext besteht aus den optionalen Feldern addReviewers und replaceReviewers. Jedes Feld hat ein wiederholtes Objekt für AddReviewer und ReplaceReviewer, das jeweils einen einzelnen hinzuzufügenden Prüfer oder ein Paar zu ersetzender Prüfer enthält. Sie können auch das optionale Feld message mit dem Kommentar hinzufügen, den Sie an die neuen Prüfer senden möchten.

Der Antworttext enthält eine Instanz der approvals-Ressource. Die Nachricht wird als Benachrichtigung an die neuen Prüfer gesendet und ist auch im Genehmigungsaktivitätslog enthalten.

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."
 }'

Ersetzen Sie Folgendes:

FILE_ID: Die ID der Datei, für die die Genehmigung gilt.
APPROVAL_ID: Die ID der Genehmigung.
ACCESS_TOKEN: Das OAuth 2.0-Token Ihrer App.

Genehmigung abbrechen

Wenn Sie eine Genehmigung zurückziehen möchten, verwenden Sie die Methode cancel für die Ressource approvals und fügen Sie die Pfadparameter fileId und approvalId ein.

Die Methode cancel kann nur vom Initiator der Genehmigung (oder einem Nutzer mit der Berechtigung role=writer) aufgerufen werden, während die Genehmigung Status den Status IN_PROGRESS hat.

Der Anfragetext besteht aus einem optionalen Feld message, das einen String mit der Nachricht enthält, die die Aufhebung der Genehmigung begleiten soll.

Der Antworttext enthält eine Instanz der approvals-Ressource. Die Nachricht wird als Benachrichtigung gesendet und ist auch im Genehmigungsaktivitätslog enthalten. Die Genehmigung Status ist auf CANCELLED festgelegt und hat den Status „Abgeschlossen“.

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."
 }'

Ersetzen Sie Folgendes:

FILE_ID: Die ID der Datei, für die die Genehmigung gilt.
APPROVAL_ID: Die ID der Genehmigung.
ACCESS_TOKEN: Das OAuth 2.0-Token Ihrer App.

Genehmigung ablehnen

Wenn Sie eine Genehmigung ablehnen möchten, verwenden Sie die Methode decline für die Ressource approvals und fügen Sie die Pfadparameter fileId und approvalId ein.

Die Methode decline kann nur aufgerufen werden, wenn die Genehmigung Status den Status IN_PROGRESS hat.

Der Anfragetext besteht aus dem optionalen Feld message, das einen String mit der Nachricht enthält, die mit der Ablehnung der Genehmigung gesendet werden soll.

Der Antworttext enthält eine Instanz der approvals-Ressource. Die Nachricht wird als Benachrichtigung gesendet und ist auch im Genehmigungsaktivitätslog enthalten. Das Feld response des ReviewerResponse-Objekts des anfragenden Nutzers ist auf DECLINED festgelegt. Außerdem wird die Genehmigung Status auf DECLINED gesetzt und der Status ist „Abgeschlossen“.

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."
 }'

Ersetzen Sie Folgendes:

FILE_ID: Die ID der Datei, für die die Genehmigung gilt.
APPROVAL_ID: Die ID der Genehmigung.
ACCESS_TOKEN: Das OAuth 2.0-Token Ihrer App.

Genehmigung genehmigen

Verwenden Sie die Methode approve für die Ressource approvals und fügen Sie die Pfadparameter fileId und approvalId ein, um eine Genehmigung zu erteilen.

Die Methode approve kann nur aufgerufen werden, wenn die Genehmigung Status den Status IN_PROGRESS hat.

Der Anfragetext besteht aus dem optionalen Feld message, das einen String mit der Nachricht enthält, die die Genehmigung begleiten soll.

Der Antworttext enthält eine Instanz der approvals-Ressource. Die Nachricht wird als Benachrichtigung gesendet und ist auch im Genehmigungsaktivitätslog enthalten. Das Feld response des ReviewerResponse-Objekts des anfragenden Nutzers ist auf APPROVED festgelegt. Wenn dies die letzte erforderliche Antwort des Prüfers ist, wird die Genehmigung Status auf APPROVED gesetzt und der Status ist „Abgeschlossen“.

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."
 }'

Ersetzen Sie Folgendes:

FILE_ID: Die ID der Datei, für die die Genehmigung gilt.
APPROVAL_ID: Die ID der Genehmigung.
ACCESS_TOKEN: Das OAuth 2.0-Token Ihrer App.

Vorhandene Genehmigungen finden

Mit der Ressource approvals können Sie auch den Status Ihrer Genehmigungen mit der Drive API abrufen und auflisten.

Wenn Sie Genehmigungen für eine Datei aufrufen möchten, benötigen Sie die Berechtigung zum Lesen der Metadaten der Datei. Weitere Informationen finden Sie unter Rollen und Berechtigungen.

Genehmigung einholen

Verwenden Sie die Methode get für die Ressource approvals mit den Pfadparametern fileId und approvalId, um eine Genehmigung für eine Datei zu erhalten. Wenn Sie die Genehmigungs-ID nicht kennen, können Sie Genehmigungen mit der Methode list auflisten.

Der Antworttext enthält eine Instanz der approvals-Ressource.

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'

Ersetzen Sie Folgendes:

FILE_ID: Die ID der Datei, für die die Genehmigung gilt.
APPROVAL_ID: Die ID der Genehmigung.
ACCESS_TOKEN: Das OAuth 2.0-Token Ihrer App.

Genehmigungen auflisten

Wenn Sie Genehmigungen für eine Datei auflisten möchten, rufen Sie die Methode list für die Ressource approvals auf und fügen Sie den Pfadparameter fileId ein.

Der Antworttext besteht aus einer Liste der Genehmigungen für die Datei. Das Feld items enthält Informationen zu jeder Genehmigung in Form einer approvals-Ressource.

Sie können auch die folgenden Abfrageparameter übergeben, um die Paginierung der Genehmigungen anzupassen oder sie zu filtern:

pageSize: Die maximale Anzahl der Genehmigungen, die pro Seite zurückgegeben werden sollen. Wenn Sie pageSize nicht festlegen, gibt der Server bis zu 100 Genehmigungen zurück.
pageToken: Ein Seitentoken, das von einem vorherigen Listenaufruf empfangen wurde. Mit diesem Token wird die nächste Seite abgerufen. Er sollte auf den Wert von nextPageToken aus einer vorherigen Antwort festgelegt werden.

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'

Ersetzen Sie Folgendes:

FILE_ID: Die ID der Datei, für die die Genehmigung gilt.
ACCESS_TOKEN: Das OAuth 2.0-Token Ihrer App.

Genehmigungen verwalten Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Hinweis

Konzepte

Freigabestatus

Lebenszyklus einer Genehmigung

Parameter „fields“ verwenden

Genehmigungen starten und verwalten

Genehmigung starten

curl

Kommentar zur Genehmigung

curl

Prüfer bei Genehmigung neu zuweisen

curl

Genehmigung abbrechen

curl

Genehmigung ablehnen

curl

Genehmigung genehmigen

curl

Vorhandene Genehmigungen finden

Genehmigung einholen

curl

Genehmigungen auflisten

curl

Weitere Informationen

Genehmigungen verwalten