Como criar e atualizar o consentimento dos usuários

Esta página descreve como criar, atualizar e revogar consentimentos do usuário.

Seu aplicativo registra os artefatos de consentimento e consentimentos separadamente. A API Consent Management armazena dados confidenciais pertencentes ao consentimento do usuário como ConsentArtifact. Um ConsentArtifact pode incluir carimbos de data/hora de assinatura e imagens de assinaturas ou outros documentos que atuam como "prova" de consentimento.

A API Consent Management armazena dados de consentimento não confidenciais como objetos Consent. Um Consent inclui um ID de usuário opaco, as políticas de consentimento concedidas pelo usuário e o status das políticas de consentimento.

Como os consentimentos e os artefatos de consentimento têm caminhos de recursos distintos, as permissões deles podem ser definidas de maneira independente para minimizar o acesso a dados de consentimento confidenciais nesses artefatos.

Os consentimentos permitem um prazo de validade que possibilita configurar quando o consentimento expira e não é mais válido. A duração do vencimento pode ser definida como uma data ou um período específico, como um ano.

Durante a criação do repositório de consentimento, é possível configurar uma duração de vencimento padrão para o armazenamento desse tipo. Durante a criação do consentimento, é possível configurar uma duração de vencimento. A duração do vencimento definida durante a criação do consentimento modifica a duração padrão definida para o armazenamento de consentimento.

Os consentimentos podem ser criados nos estados ACTIVE ou DRAFT. Os consentimentos no estado ACTIVE são usados pela API Consent Management para determinar as concessões de acesso. Os consentimentos no estado DRAFT são usados apenas em terminações de acesso, se especificados em uma solicitação de determinação do acesso. É possível alterar o estado de DRAFT para ACTIVE ou REJECTED atualizando o consentimento.

Para registrar um consentimento do usuário, crie um artefato de consentimento usando o método projects.locations.datasets.consentStores.consentArtifacts.create e vincule o artefato de consentimento a um consentimento criado usando o método projects.locations.datasets.consentStores.consents.create.

Os exemplos nesta página partem do princípio de que você criou um armazenamento de consentimento e configurou políticas de consentimento.

Um artefato de consentimento armazena dados confidenciais pertencentes ao consentimento do usuário. Um artefato de consentimento pode incluir dados de contato de um usuário, carimbos de data/hora da assinatura e imagens de assinaturas ou outros documentos que atuam como "protetivos" do consentimento.

Para criar um artefato de consentimento, use o método projects.locations.datasets.consentStores.consentArtifacts.create. Faça uma solicitação POST e especifique as seguintes informações nela:

  • É o nome do repositório de consentimento dos responsáveis.
  • Um ID de usuário único e opaco que representa o usuário que forneceu o consentimento.
  • A assinatura do usuário, incluindo opcionalmente a imagem da assinatura, o carimbo de data/hora e outros metadados. Essa imagem pode ser especificada como um local de imagem no Cloud Storage ou como uma string de bytes brutos.
  • Assinatura opcional dos responsáveis ou da testemunha.
  • Imagens ou documentos opcionais que agem como "prova" de consentimento, como uma imagem de assinatura, imagens que capturam telas de um fluxo de consentimento de dispositivos móveis ou um documento PDF assinado. Essas imagens podem ser especificadas como um local no Cloud Storage ou como uma string de bytes brutos.
  • Um identificador das informações de consentimento que o usuário recebeu.
  • Metadados opcionais relacionados ao consentimento do usuário.
  • Um token de acesso.

Um consentimento armazena dados não confidenciais, incluindo IDs de usuário opacos, as políticas de consentimento concedidas pelos usuários e se as políticas de consentimento são válidas atualmente.

Para criar um consentimento, use o método projects.locations.datasets.consentStores.consents.create. Faça uma solicitação POST e especifique as seguintes informações nela:

  • É o nome do repositório de consentimento dos responsáveis.
  • Um ID de usuário único e opaco que representa o usuário que forneceu o consentimento.
  • Até 10 políticas de consentimento, cada uma com um conjunto de valores de atributo RESOURCE e uma regra de autorização expressa em Common Expression Language (CEL) que descreve a intenção do usuário com definições de atributo criadas anteriormente. As seguintes restrições ao CEL se aplicam:
    • É possível definir no máximo 10 operadores lógicos por política.
    • Você só pode usar os operadores AND (&&), OR (|) e IN.
  • O caminho REST para o artefato de consentimento correspondente (retornado após a criação do artefato de consentimento).
  • Um estado de consentimento opcional, DRAFT ou ACTIVE. Se você não especificar o estado, o consentimento será criado no estado ACTIVE.
  • Uma duração de expiração opcional para o consentimento, definida como uma data ou período. Esse valor precisa ser fornecido em segundos e sufixado com a letra "s". Por exemplo, 86000s Esse valor substitui a duração do vencimento configurada para o armazenamento de consentimento. Se você não configurar uma validade, o recurso herdará a duração padrão do armazenamento de consentimento. Se uma duração de expiração não for especificada para o recurso ou o repositório, o recurso de consentimento não expirará.
  • Um token de acesso.

Os exemplos a seguir mostram como conseguir um consentimento. Para ver mais informações, consulte projects.locations.datasets.consentStores.consents.get.

Para conseguir um consentimento, faça uma solicitação GET e especifique as seguintes informações na solicitação:

  • O nome do conjunto de dados pai
  • O nome do repositório de consentimentos
  • O nome do consentimento
  • Um token de acesso

Os exemplos a seguir mostram como listar os consentimentos em um repositório de consentimentos.

Para listar os consentimentos em um armazenamento, use o método projects.locations.datasets.consentStores.consents.list.

Também é possível listar as revisões de um consentimento específico usando o método projects.locations.datasets.consentStores.consents.listRevisions.

Como atualizar consentimentos

Talvez seja necessário atualizar o estado de consentimentos ao longo do tempo. Para fazer isso, altere o estado de consentimento. Toda atualização e alteração de estado gera uma nova revisão do consentimento. As revisões anteriores podem ser acessadas anexando @{revision_id} ao nome do recurso do consentimento.

Como atualizar consentimentos

Para atualizar um consentimento ativo ou de rascunhouserId, policies, consentArtifact ou revokeConsentArtifact e use o método projects.locations.datasets.consentStores.consents.patch. Uma nova revisão é confirmada com as alterações e é definida como o estado atual.

Para atualizar um consentimento, faça uma solicitação PATCH e especifique as seguintes informações na solicitação:

  • Caminho REST do consentimento a ser atualizado
  • Campos a serem atualizados
  • Uma máscara de atualização
  • Um token de acesso

Como ativar consentimentos

Para alterar o estado de um consentimento de DRAFT para ACTIVE depois que o usuário aceitar o consentimento, use o método projects.locations.datasets.consentStores.consents.activateConsent. Uma nova revisão é confirmada com o estado ACTIVE. Quando o estado do consentimento é ACTIVE, o consentimento é incluído nas solicitações de determinação de acesso.

Para ativar um consentimento, faça uma solicitação POST e especifique as seguintes informações na solicitação:

  • Caminho REST do consentimento a ser ativado
  • O caminho REST para um artefato opcional para documentar o motivo da ativação do consentimento
  • Um token de acesso

Como revogar e rejeitar consentimentos

Para alterar o estado de um consentimento de DRAFT para REJECTED, por exemplo, se o usuário indicar que o consentimento não é aceitável, use o método projects.locations.datasets.consentStores.consents.reject. Quando o estado de um consentimento é REJECTED, ele não é incluído nas solicitações de determinação do acesso.

Para alterar o estado de um consentimento de ACTIVE para REVOKED, por exemplo, se um usuário solicitar a exceção de um consentimento concedido anteriormente, use o método projects.locations.datasets.consentStores.consents.revoke. Uma nova revisão é confirmada com o estado REVOKED. Os consentimentos com estado REVOKED não são incluídos nas solicitações de determinação do acesso. Você pode criar um artefato opcional associado ao consentimento para documentar o motivo da revogação do consentimento. A revogação de um consentimento não o exclui.

Para revogar um consentimento, faça uma solicitação POST e especifique as seguintes informações na solicitação:

  • O caminho REST do consentimento a ser revogado
  • O caminho REST para um artefato opcional para documentar o motivo da revogação do consentimento
  • Um token de acesso