Nutzereinwilligungen erstellen und aktualisieren

Auf dieser Seite wird beschrieben, wie Sie die Nutzereinwilligung erstellen, aktualisieren und widerrufen.

In Ihrer Anwendung werden die Einwilligungsartefakte und Einwilligungen separat aufgezeichnet. Die Consent Management API speichert sensible Daten im Zusammenhang mit der Einwilligung eines Nutzers als ConsentArtifact. Ein ConsentArtifact kann Signaturzeitstempel und Bilder von Signaturen oder anderen Dokumenten enthalten, die als "nachweisliche Einwilligung" dienen.

Die Consent Management API speichert nicht vertrauliche Einwilligungsdaten als Consent-Objekte. Eine Consent enthält eine undurchsichtige Nutzer-ID, die vom Nutzer gewährten Einwilligungsrichtlinien und den Status der Einwilligungsrichtlinie.

Da für Einwilligungen und Einwilligungsartefakte unterschiedliche Ressourcenpfade verwendet werden, können die Berechtigungen unabhängig festgelegt werden, um den Zugriff auf vertrauliche Einwilligungsdaten in Consent-Artefakten zu minimieren.

Einwilligungen unterstützen eine Ablauffrist, mit der Sie festlegen können, wann die Einwilligung abläuft und nicht mehr gültig ist. Die Ablaufzeit kann auf ein bestimmtes Datum oder einen bestimmten Zeitraum, z. B. auf ein Jahr, festgelegt werden.

Während der Erstellung einer Einwilligungsspeicher können Sie eine Standardablaufzeit für den Consent-Speicher konfigurieren. Während der Erstellungseinwilligung können Sie eine Ablaufzeit konfigurieren. Der während der Erstellungseinwilligung festgelegte Ablauf überschreibt die Standarddauer, die für den Consent-Speicher festgelegt wurde.

Einwilligungen können im Status ACTIVE oder DRAFT erstellt werden. Die Einwilligungen im Status ACTIVE werden von der Consent Management API verwendet, um Zugriffsverweigerungen vorzunehmen. Einwilligungen mit dem Status DRAFT werden nur für die Zugriffsvergabe verwendet, wenn in einer Anfrage zur Zugriffsgenehmigung angegeben ist. Sie können den Status von DRAFT in ACTIVE oder REJECTED ändern, indem Sie die Einwilligung aktualisieren.

Erstellen Sie ein Nutzerartefakt, indem Sie mithilfe der Methodeprojects.locations.datasets.consentStores.consentArtifacts.create auf und verknüpfen Sie das Artefakt der Einwilligung mit einem Artefakt, das mit der Methode projects.locations.datasets.consentStores.consents.create erstellt wurde.

Bei den Beispielen auf dieser Seite wird davon ausgegangen, dass Sie einen Consent-Speicher und Zustimmungsrichtlinien erstellt haben.

Ein Consent-Artefakt speichert sensible Daten im Zusammenhang mit der Einwilligung eines Nutzers. Ein Consent-Artefakt kann die Kontaktdaten eines Nutzers, Signaturzeitstempel und Bilder von Signaturen oder anderen Dokumenten enthalten, die als "nachweisliche Einwilligung" dienen.

Verwenden Sie zum Erstellen eines Einwilligungsartefakts die Methode projects.locations.datasets.consentStores.consentArtifacts.create. Stellen Sie eine POST-Anfrage und geben Sie die folgenden Informationen in der Anfrage an:

  • Der Name des übergeordneten Einverständnisladens
  • Eine eindeutige und undurchsichtige Nutzer-ID, die den Nutzer darstellt, der die Einwilligung gegeben hat
  • Die Signatur des Nutzers, optional das Bild, der Zeitstempel und andere Metadaten Dieses Image kann als Speicherort für Bilder in Cloud Storage oder als String mit Rohbyte angegeben werden.
  • Eine optionale Unterschrift als Erziehungsberechtigter.
  • Optionale Bilder oder Dokumente, die als "nachweislicher" Einwilligung angezeigt werden, z. B. ein Signaturbild, Bilder, die den Bildschirm eines Mobile-Consent-Prozesses darstellen, oder ein signiertes PDF-Dokument Diese Bilder können als Speicherort in Cloud Storage oder als String mit Rohbyte angegeben werden.
  • Kennzeichnung der Informationen zur Nutzereinwilligung, die dem Nutzer angezeigt wurden.
  • Optionale Metadaten, die mit der Einwilligung des Nutzers zusammenhängen.
  • Ein Zugriffstoken

In einer Einwilligung werden nicht vertrauliche Daten gespeichert, einschließlich intransparenter Nutzer-IDs, von den Nutzern erteilte Einwilligungsrichtlinien und die Angabe, ob die Einwilligungsrichtlinien derzeit gültig sind.

Verwenden Sie zum Erstellen einer Einwilligung die Methode projects.locations.datasets.consentStores.consents.create. Stellen Sie eine POST-Anfrage und geben Sie die folgenden Informationen in der Anfrage an:

  • Der Name des übergeordneten Einverständnisladens
  • Eine eindeutige und undurchsichtige Nutzer-ID, die den Nutzer darstellt, der die Einwilligung gegeben hat
  • Bis zu 10 Zustimmungsrichtlinien mit jeweils einer Reihe an RESOURCE-Attributwerten und einer Autorisierungsregel, die in der Common Expression Language (CEL) angegeben ist und die Absicht des Nutzers mit zuvor erstellten Attributdefinitionen beschreibt. Für CEL gelten die folgenden Einschränkungen:
    • Sie können maximal 10 Logikoperatoren pro Richtlinie definieren.
    • Die Operatoren AND (&&), OR (||) und IN können nur verwendet werden.
  • Der REST-Pfad zum entsprechenden Consent-Artefakt, das bei Erstellung des Consent-Artefakts zurückgegeben wird
  • Ein optionaler Einwilligungsstatus, entweder DRAFT oder ACTIVE Wenn Sie keinen Status angeben, wird die Einwilligung im Status ACTIVE erstellt.
  • Eine optionale Ablauffrist für die Einwilligung, definiert als Datum oder Zeitraum Dieser Wert muss in Sekunden angegeben und mit den Buchstaben "s" versehen werden. z. B. 86000s Dieser Wert überschreibt die für den Einwilligungsspeicher konfigurierte Ablaufzeit. Wenn Sie keine Ablaufzeit konfigurieren, übernimmt die Ressource die Standardablaufzeit aus dem Consent-Speicher. Wenn für die Ressource oder den Speicher keine Ablaufzeit festgelegt ist, läuft die Einwilligungsressource nicht ab.
  • Ein Zugriffstoken

Die folgenden Beispiele zeigen, wie eine Einwilligung eingeholt wird. Weitere Informationen finden Sie unter projects.locations.datasets.consentStores.consents.get.

Wenn Sie eine Einwilligung einholen möchten, senden Sie eine GET-Anfrage und geben Sie die folgenden Informationen in der Anfrage an:

  • Der Name des übergeordneten Datasets
  • Der Name des Einwilligungsspeichers
  • Der Name der Einwilligung
  • Ein Zugriffstoken

Die folgenden Beispiele zeigen, wie die Einwilligungen in einem Consent-Speicher aufgelistet werden.

Verwenden Sie die Methode projects.locations.datasets.consentStores.consents.list, um die Einwilligungen in einem Consent-Speicher aufzulisten.

Sie können die Überarbeitungen einer bestimmten Einwilligung auch mit der projects.locations.datasets.consentStores.consents.listRevisions-Methode auflisten.

Einwilligungen aktualisieren

Unter Umständen müssen Sie den Status von Einwilligungen im Laufe der Zeit aktualisieren. Dazu ändern Sie den Einwilligungsstatus. Bei jeder Aktualisierung und Änderung des Status wird eine neue Überarbeitung der Einwilligung generiert. Auf vorherige Überarbeitungen kann durch Anhängen von @{revision_id} an den Ressourcennamen der Einwilligung zugegriffen werden.

Einwilligungen aktualisieren

Wenn Sie die Felder userId, policies, consentArtifact oder revokeConsentArtifact einer aktiven Einwilligung oder eines Entwurfs aktualisieren möchten, verwenden Sie projects.locations.datasets.consentStores.consents.patch. Für eine neue Überarbeitung wird die Änderung übernommen und auf den aktuellen Status festgelegt.

Wenn Sie eine Einwilligung aktualisieren möchten, stellen Sie eine PATCH-Anfrage und geben Sie die folgenden Informationen in der Anfrage an:

  • Der REST-Pfad der zu aktualisierenden Einwilligung
  • Die zu aktualisierenden Felder
  • Eine Aktualisierungsmaske
  • Ein Zugriffstoken

Einwilligungen aktivieren

Mit der Methode projects.locations.datasets.consentStores.consents.activateConsent können Sie den Status einer Einwilligung von DRAFT in ACTIVE ändern, nachdem der Nutzer die Einwilligung akzeptiert hat. Eine neue Überarbeitung wird mit dem Status ACTIVE festgeschrieben. Wenn der Status der Einwilligung ACTIVE lautet, ist die Einwilligung in Anfragen zur Zugriffsgenehmigung enthalten.

Um eine Einwilligung zu aktivieren, stellen Sie eine POST-Anfrage und geben Sie die folgenden Informationen in der Anfrage an:

  • Der REST-Pfad der zu aktivierenden Einwilligung
  • Der REST-Pfad zu einem optionalen Artefakt, um zu dokumentieren, warum die Einwilligung aktiviert wurde
  • Ein Zugriffstoken

Einwilligung widerrufen und ablehnen

Wenn Sie den Status einer Einwilligung von DRAFT in REJECTED ändern möchten, z. B. wenn der Nutzer angibt, dass die Einwilligung nicht akzeptabel ist, verwenden Sie die Methode projects.locations.datasets.consentStores.consents.reject. Wenn der Status einer Einwilligung REJECTED lautet, ist die Einwilligung nicht in Anfragen zur Zugriffsanforderung enthalten.

Wenn Sie den Status einer Einwilligung von ACTIVE in REVOKED ändern möchten, z. B. wenn ein Nutzer eine zuvor gewährte Einwilligung anfordert, verwenden Sie die Methode projects.locations.datasets.consentStores.consents.revoke. Eine neue Überarbeitung wird mit dem Status REVOKED festgeschrieben. Einwilligungen mit dem Status REVOKED werden nicht in Anfragen zur Zugriffsgenehmigung einbezogen. Sie können ein optionales Artefakt erstellen, das mit der Einwilligung verknüpft ist, um zu dokumentieren, warum die Einwilligung widerrufen wurde. Wenn Sie eine Einwilligung widerrufen, wird Ihre Einwilligung dadurch nicht gelöscht.

Wenn Sie eine Einwilligung widerrufen möchten, stellen Sie eine POST-Anfrage und geben Sie die folgenden Informationen in der Anfrage an:

  • Der REST-Pfad der zu widerrufenden Einwilligung
  • Der REST-Pfad zu einem optionalen Artefakt, um zu dokumentieren, warum die Einwilligung widerrufen wurde
  • Ein Zugriffstoken