Configurar políticas

Esta página oferece uma breve visão geral das pastas e explica como gerenciar documentos usando pastas.

Mecanismo de políticas e regras

No Document Warehouse, o Policy Engine permite que os usuários definam e executem operações comuns em documentos (por exemplo, validar ou atualizar) ao criar ou atualizar documentos.

Regras e RuleSet

Uma regra em um nível alto se refere a uma configuração definida pelo usuário que especifica o seguinte:

  • o que aciona a verificação de regras,
  • qual condição é avaliada;
  • quais ações são executadas quando a condição é atendida.

Além dessas especificações, uma regra inclui informações sobre a descrição, a origem, o destino e a condição de acionamento.

Uma coleção lógica de regras é chamada de RuleSet. Por exemplo, regras que operam no mesmo esquema podem ser agrupadas em um único RuleSet. Os clientes podem definir vários conjuntos de regras.

As regras são úteis para acionar automaticamente ações predefinidas ao criar ou atualizar documentos.

Uma regra consiste em três elementos principais:

  • TriggerType: evento em que a verificação da regra precisa ser iniciada. "Criar" e "Atualizar" são os tipos de acionadores compatíveis.
  • Condição da regra: a condição avaliada depois que um determinado tipo de acionador é detectado. As condições podem ser expressas usando a Common Expression Language (CEL). Cada condição precisa ser avaliada como uma saída booleana.
  • Ações: conjunto de etapas executadas quando a regra é atendida. Quando uma condição de regra é avaliada como verdadeira, a ação correspondente (configurada na regra) é executada. Confira a seguir os detalhes gerais sobre ações específicas implementadas no Document Warehouse:
    • Ação de validação de dados: permite validar campos específicos no documento durante a criação ou atualização dele.
    • Ação de atualização de dados: permite atualizar campos específicos no documento durante a criação ou atualização dele. Essas atualizações são executadas quando a condição da regra é atendida.
    • Ação de exclusão de documento: permite excluir o documento durante a atualização quando determinados campos atendem aos critérios de exclusão definidos usando condições de regra.
    • Ação de inclusão de pasta: ação que adiciona automaticamente um novo documento (ou um documento atualizado) em pastas específicas. Essas pastas podem ser especificadas diretamente usando o nome delas.
    • Ação de remoção da pasta: ação que remove automaticamente um novo documento de pastas específicas quando uma condição no nível da regra é atendida.
    • Ação de controle de acesso: ação que permite atualizar as listas de controle de acesso (grupos e vinculações de usuários) durante a criação de documentos. Essas atualizações são executadas quando a condição da regra é atendida.
    • Ação de publicação: ação que publica mensagens específicas no canal do Pub/Sub do usuário quando uma condição no nível da regra é atendida.

Gerenciar conjuntos de regras

O Document Warehouse oferece APIs para gerenciar conjuntos de regras (criar, receber, atualizar, excluir, listar). Esta seção fornece exemplos para configurar diferentes tipos de regras.

Criar um RuleSet

Para criar um conjunto de regras, faça o seguinte:

REST

Solicitação:

# Create a RuleSet for data validation.
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/ruleSets \
-d '{
  "rules": [
    {
      "trigger_type": "ON_CREATE",
      "condition": "documentType == \'W9\' && STATE ==\'CA\'",
      "actions": {
        "data_validation": {
          "conditions": {
            "NAME": "NAME != \'\'",
            "FILING_COST": "FILING_COST > 10.0"
          }
        }
      },
      "enabled": true
    }
  ],
  "description": "W9: Basic validation check rules."
}'

Resposta

{
  "description": "W9: Basic validation check rules.",
  "name": "RULE_SET_NAME",
  "rules": [
    {
      "actions": [
        {
          "actionId": "de0e6b84-106b-44ba-b1c4-0b3ad6ddc719",
          "dataValidation": {
            "conditions": {
              "FILING_COST": "FILING_COST > 10.0",
              "NAME": "NAME != ''"
            }
          }
        }
      ],
      "condition": "documentType == 'W9' && STATE =='CA'",
      "enabled": true,
      "triggerType": "ON_CREATE"
    }
  ]
}

Python

Para mais informações, consulte a documentação de referência da API Python da Document AI Warehouse.

Para autenticar no Document AI Warehouse, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.


from google.cloud import contentwarehouse

# TODO(developer): Uncomment these variables before running the sample.
# project_number = "YOUR_PROJECT_NUMBER"
# location = "us" # Format is 'us' or 'eu'


def create_rule_set(project_number: str, location: str) -> None:
    # Create a client
    client = contentwarehouse.RuleSetServiceClient()

    # The full resource name of the location, e.g.:
    # projects/{project_number}/locations/{location}
    parent = client.common_location_path(project=project_number, location=location)

    actions = contentwarehouse.Action(
        delete_document_action=contentwarehouse.DeleteDocumentAction(
            enable_hard_delete=True
        )
    )

    rules = contentwarehouse.Rule(
        trigger_type="ON_CREATE",
        condition="documentType == 'W9' && STATE =='CA'",
        actions=[actions],
    )

    rule_set = contentwarehouse.RuleSet(
        description="W9: Basic validation check rules.",
        source="My Organization",
        rules=[rules],
    )

    # Initialize request argument(s)
    request = contentwarehouse.CreateRuleSetRequest(parent=parent, rule_set=rule_set)

    # Make the request
    response = client.create_rule_set(request=request)

    # Handle the response
    print(f"Rule Set Created: {response}")

    # Initialize request argument(s)
    request = contentwarehouse.ListRuleSetsRequest(
        parent=parent,
    )

    # Make the request
    page_result = client.list_rule_sets(request=request)

    # Handle the response
    for response in page_result:
        print(f"Rule Sets: {response}")

Java

Para mais informações, consulte a documentação de referência da API Java da Document AI Warehouse.

Para autenticar no Document AI Warehouse, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

import com.google.cloud.contentwarehouse.v1.Action;
import com.google.cloud.contentwarehouse.v1.ActionOrBuilder;
import com.google.cloud.contentwarehouse.v1.CreateRuleSetRequest;
import com.google.cloud.contentwarehouse.v1.CreateRuleSetRequestOrBuilder;
import com.google.cloud.contentwarehouse.v1.DeleteDocumentAction;
import com.google.cloud.contentwarehouse.v1.DeleteDocumentActionOrBuilder;
import com.google.cloud.contentwarehouse.v1.ListRuleSetsRequest;
import com.google.cloud.contentwarehouse.v1.ListRuleSetsRequestOrBuilder;
import com.google.cloud.contentwarehouse.v1.LocationName;
import com.google.cloud.contentwarehouse.v1.Rule;
import com.google.cloud.contentwarehouse.v1.Rule.TriggerType;
import com.google.cloud.contentwarehouse.v1.RuleOrBuilder;
import com.google.cloud.contentwarehouse.v1.RuleSet;
import com.google.cloud.contentwarehouse.v1.RuleSetOrBuilder;
import com.google.cloud.contentwarehouse.v1.RuleSetServiceClient;
import com.google.cloud.contentwarehouse.v1.RuleSetServiceClient.ListRuleSetsPagedResponse;
import com.google.cloud.contentwarehouse.v1.RuleSetServiceSettings;
import com.google.cloud.resourcemanager.v3.Project;
import com.google.cloud.resourcemanager.v3.ProjectName;
import com.google.cloud.resourcemanager.v3.ProjectsClient;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeoutException;


public class CreateRuleSet {

  public static void createRuleSet() throws IOException, 
        InterruptedException, ExecutionException, TimeoutException { 
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String location = "your-region"; // Format is "us" or "eu".
    createRuleSet(projectId, location);
  }

  public static void createRuleSet(String projectId, String location)
      throws IOException, InterruptedException, ExecutionException, TimeoutException {
    String projectNumber = getProjectNumber(projectId);

    String endpoint = "contentwarehouse.googleapis.com:443";
    if (!"us".equals(location)) {
      endpoint = String.format("%s-%s", location, endpoint);
    }
    RuleSetServiceSettings ruleSetServiceSettings =
        RuleSetServiceSettings.newBuilder().setEndpoint(endpoint).build();

    // Create a Rule Set Service Client 
    try (RuleSetServiceClient ruleSetServiceClient = 
        RuleSetServiceClient.create(ruleSetServiceSettings)) {
      /*  The full resource name of the location, e.g.:
      projects/{project_number}/locations/{location} */
      String parent = LocationName.format(projectNumber, location); 

      // Create a Delete Document Action to be added to the Rule Set 
      DeleteDocumentActionOrBuilder deleteDocumentAction = 
          DeleteDocumentAction.newBuilder().setEnableHardDelete(true).build();

      // Add Delete Document Action to Action Object 
      ActionOrBuilder action = Action.newBuilder()
            .setDeleteDocumentAction((DeleteDocumentAction) deleteDocumentAction).build();

      // Create rule to add to rule set 
      RuleOrBuilder rule = Rule.newBuilder()
          .setTriggerType(TriggerType.ON_CREATE)
          .setCondition("documentType == 'W9' && STATE =='CA' ")
          .addActions(0, (Action) action).build();

      // Create rule set and add rule to it
      RuleSetOrBuilder ruleSetOrBuilder = RuleSet.newBuilder()
          .setDescription("W9: Basic validation check rules.")
          .setSource("My Organization")
          .addRules((Rule) rule).build();

      // Create and prepare rule set request to client
      CreateRuleSetRequestOrBuilder createRuleSetRequest = 
          CreateRuleSetRequest.newBuilder()
              .setParent(parent)
              .setRuleSet((RuleSet) ruleSetOrBuilder).build();

      RuleSet response = ruleSetServiceClient.createRuleSet(
          (CreateRuleSetRequest) createRuleSetRequest);

      System.out.println("Rule set created: " + response.toString());

      ListRuleSetsRequestOrBuilder listRuleSetsRequest = 
          ListRuleSetsRequest.newBuilder()
              .setParent(parent).build();

      ListRuleSetsPagedResponse listRuleSetsPagedResponse = 
          ruleSetServiceClient.listRuleSets((ListRuleSetsRequest) listRuleSetsRequest);

      listRuleSetsPagedResponse.iterateAll().forEach(
          (ruleSet -> System.out.print(ruleSet))
      );
    }
  }

  private static String getProjectNumber(String projectId) throws IOException { 
    try (ProjectsClient projectsClient = ProjectsClient.create()) { 
      ProjectName projectName = ProjectName.of(projectId); 
      Project project = projectsClient.getProject(projectName);
      String projectNumber = project.getName(); // Format returned is projects/xxxxxx
      return projectNumber.substring(projectNumber.lastIndexOf("/") + 1);
    } 
  }
}

Listar RuleSets

Para listar conjuntos de regras em um projeto, faça o seguinte:

REST

Solicitação:

# List all rule-sets for a project.
curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/ruleSets

Resposta

{
  "ruleSets": [
    {
      "description": "W9: Basic validation check rules.",
      "rules": [
        {
          "triggerType": "ON_CREATE",
          "condition": "documentType == 'W9' && STATE =='CA'",
          "actions": [
            {
              "actionId": "fcf79ae8-9a1f-4462-9262-eb2e7161350c",
              "dataValidation": {
                "conditions": {
                  "NAME": "NAME != ''",
                  "FILING_COST": "FILING_COST > 10.0"
                }
              }
            }
          ],
          "enabled": true
        }
      ],
      "name": "RULE_SET_NAME"
    }
  ]
}

Receber um RuleSet

Para receber um conjunto de regras usando o nome dele, faça o seguinte:

REST

Solicitação:

# Get a rule-set using rule-set ID.
curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/ruleSets/RULE_SET

Resposta

{
  "description": "W9: Basic validation check rules.",
  "rules": [
    {
      "triggerType": "ON_CREATE",
      "condition": "documentType == 'W9' && STATE =='CA'",
      "actions": [
        {
          "actionId": "7559346b-ec9f-4143-ab1c-1912f5588807",
          "dataValidation": {
            "conditions": {
              "NAME": "NAME != ''",
              "FILING_COST": "FILING_COST > 10.0"
            }
          }
        }
      ],
      "enabled": true
    }
  ],
  "name": "RULE_SET_NAME"
}

Excluir um RuleSet

Para excluir um conjunto de regras usando o nome dele, faça o seguinte:

REST

Solicitação:

# Get a rule-set using rule-set ID.
curl -X DELETE -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/ruleSets/RULE_SET

Ações de regras

Esta seção vai abordar as expressões de regra e exemplos de ações de cada regra.

Exemplos de condições

Uma condição se refere à expressão especificada usando a Common Expression Language.

Exemplos:

  • Expressão de campo de string
    • STATE == \'CA\'. Verifique se o valor do campo STATE é igual a CA.
    • NAME != \'\'. Verifique se o valor do campo NAME não está vazio.
  • Expressão de campo numérico
    • FILING_COST > 10.0. Verifique se o valor do campo FILING_COST (definido como ponto flutuante) é maior que 10.0.

Como verificar se um documento pertence a um esquema específico

Para se referir a um tipo de esquema específico, use o nome de campo especial documentType (é uma palavra reservada). Ele é avaliado em relação ao campo DisplayName no DocumentSchema.

Exemplo:

  • documentType == \'W9\'

A condição anterior verifica se o esquema do documento (usando a palavra-chave documentType) tem um nome de exibição W9.

Como se referir a valores de propriedades de documentos antigos/existentes e novos

Para oferecer suporte a condições que incluem propriedades atuais e recém-fornecidas, use os dois prefixos a seguir com um operador DOT para acessar a versão específica da propriedade:

  • OLD_ para se referir às propriedades de documentos atuais.
  • NEW_ para se referir a novas propriedades do documento na solicitação.

Exemplo:

  • OLD_.state == \'TX\' && NEW_.state == \'CA\' Verifica se o valor atual da propriedade de estado é TX e se o novo valor fornecido é CA.

Tratamento de campos de data

Para o documento DriverLicense, se o EXPIRATION_DATE for anterior a uma determinada data

  • Atualize (ou adicione se não estiver presente) EXPIRATION_STATUS (campo de enumeração) com um valor igual a EXPIRING_BEFORE_CLOSING_DATE.

Para adicionar valores de data, use a função de carimbo de data/hora, conforme mostrado no exemplo a seguir.

REST

Solicitação:

# Check if document expires before a date and update the status field
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/ruleSets \
-d '{
  "rules":[
    {
      "trigger_type": "ON_CREATE",
      "description": "Expiration date check rule",
      "condition": "documentType==\'DriverLicense\' && EXPIRATION_DATE  < timestamp(\'2021-08-01T00:00:00Z\')",
      "actions": {
        "data_update": {
          "entries": {
            "EXPIRATION_STATUS": "EXPIRING_BEFORE_CLOSING_DATE"
          }
        }
      }
    }
  ]
}'

Regra de validação de dados

Valide um documento W9 para o campo de texto STATE da Califórnia:

  • Verifique se o NAME (campo de texto) não está vazio.
  • Confira se o FILING_COST (campo de ponto flutuante) é maior que 10.0.

REST

Solicitação:

# Rules for data validation.
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/ruleSets \
-d '{
  "rules": [
    {
      "trigger_type": "ON_CREATE",
      "condition": "documentType == \'W9\' && STATE ==\'CA\'",
      "actions": {
        "data_validation": {
          "conditions": {
            "NAME": "NAME != \'\'",
            "FILING_COST": "FILING_COST > 10.0"
          }
        }
      },
      "enabled": true
    }
  ],
  "description": "W9: Basic validation check rules."
}'

Regra de atualização de dados

Para um documento W9, se o campo BUSINESS_NAME for Google:

  • Atualiza (ou adiciona um novo, se ausente) um campo Address igual a 1600 Amphitheatre Pkwy.
  • Atualiza (ou adiciona um novo, se ausente) um campo EIN igual a 77666666.

REST

Solicitação:

# Rule for data update.
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/ruleSets \
-d '{
  "rules":[
    {
      "description": "W9: Rule to update address data and EIN.",
      "trigger_type": "ON_CREATE",
      "condition": "documentType==\'W9\' && BUSINESS_NAME == \'Google\'",
      "actions": {
        "data_update": {
          "entries": {
            "Address": "1600 Amphitheatre Pkwy",
            "EIN": "776666666"
          }
        }
      }
    }
  ]
}'

Regra de exclusão de documentos

Ao atualizar o documento W9, se o campo BUSINESS_NAME for alterado para Google, exclua o documento.

REST

Solicitação:

# Rule for deleting the document
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/ruleSets \
-d '{
  "rules": [
    {
      "description": "W9: Rule to delete the document during update.",
      "trigger_type": "ON_UPDATE",
      "condition": "documentType == \'W9\' && BUSINESS_NAME == \'Google\'",
      "actions": {
        "delete_document_action": {
          "enable_hard_delete": true
        }
      }
    }
  ]
}'

Regra de controle de acesso

Ao atualizar o documento W9, se o campo BUSINESS_NAME for Google, atualize as vinculações de política que controlam o acesso ao documento.

Adicionar nova vinculação

Quando um documento atende à condição da regra:

  • Adiciona o papel de editor para user:a@example.com e group:xxx@example.com.
  • Adiciona a função de leitor para user:b@example.com e group:yyy@example.com

REST

Solicitação:

# Rule for adding new policy binding while creating the document.
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/ruleSets \
-d '{
  "rules": [
    {
      "description": "W9: Rule to add new policy binding."
      "trigger_type": "ON_CREATE",
      "condition": "documentType == \'aca13aa9-6d0d-4b6b-a1eb-315dcb876bd1\' && BUSINESS_NAME == \'Google\'",
      "actions": {
        "access_control": {
          "operation_type": "ADD_POLICY_BINDING",
          "policy": {
            "bindings": [
              {
                "role": "roles/contentwarehouse.documentEditor",
                "members": ["user:a@example.com", "group:xxx@example.com"]
              },
              {
                "role": "roles/contentwarehouse.documentViewer",
                "members": ["user:b@example.com", "group:yyy@example.com"]
              }
            ]
          }
        }
      }
    }
  ]
}'

Substituir uma vinculação atual

Quando um documento atender à condição da regra, substitua a vinculação atual para incluir apenas a função de editor para user:a@example.com e group:xxx@example.com.

REST

Solicitação:

# Rule for replacing existing policy bindings with newly given bindings.
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/ruleSets \
-d '{
  "rules": [
    {
      "description": "W9: Rule to replace policy binding."
      "trigger_type": "ON_CREATE",
      "condition": "documentType == \'a9e37d07-9cfa-4b4d-b372-53162e3b8bd9\' && BUSINESS_NAME == \'Google\'",
      "actions": {
        "access_control": {
          "operation_type": "REPLACE_POLICY_BINDING",
          "policy": {
            "bindings": [
              {
                "role": "roles/contentwarehouse.documentEditor",
                "members": ["user:a@example.com", "group:xxx@example.com"]
              }
            ]
          }
        }
      }
    }
  ]
}'

Adicionar regra de pasta

Quando uma pasta é criada ou atualizada, ela pode ser adicionada a pastas estáticas predefinidas ou a pastas que correspondem a determinados critérios de pesquisa.

Configurar pastas estáticas

Quando um novo DriverLicense for criado, adicione-o à pasta já criada.

REST

Solicitação:

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/ruleSets \
-d '{
  "rules": [
    {
      "trigger_type": "ON_CREATE",
      "condition": "documentType == \'DriverLicense\'",
      "actions": {
        "add_to_folder": {
          "folders": ["projects/821411934445/locations/us/documents/445en119hqp70"]
        }
      }
    }
  ]
}'

Publicar no Pub/Sub

Quando um documento é criado ou atualizado, ou um link é criado ou excluído, você pode enviar uma mensagem de notificação para o canal do Pub/Sub.

Etapas para usar

  • Crie um tópico do Pub/Sub no projeto do cliente.
  • Crie uma regra para acionar a ação de publicação do Pub/Sub usando a seguinte solicitação. Confira o exemplo a seguir.
  • Invocar APIs do Document AI Warehouse.
  • Verifique se as mensagens foram publicadas no canal do Pub/Sub.

Exemplo de regra

Quando um documento é adicionado a uma pasta (a API CreateLink é invocada), a seguinte regra pode ser usada para enviar mensagens de notificação ao tópico do Pub/Sub.

REST

Solicitação:

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/ruleSets \
-d '{
  "rules": [
    {
      "trigger_type": "ON_CREATE_LINK",
      "condition": "documentType == \'DriverLicenseFolder\'",
      "actions": {
        "publish_to_pub_sub": {
          "topic_id": "<topic_name>"
          "messages": "Added document under a folder."
        }
      }
    }
  ]
}'

Detalhes da regra

  • Essa ação é compatível com os seguintes tipos de gatilho:

    • ON_CRATE: quando um novo documento é criado.
    • ON_UPDATE: quando o documento é atualizado.
    • ON_CRATE_LINK: quando um novo link é criado.
    • ON_DELETE_LINK: quando um link é excluído.
  • Para os gatilhos "Criar documento" e "Atualizar documento", a condição pode incluir atributos do documento que está sendo criado ou atualizado.

  • Para os gatilhos "Criar" e "Excluir link", a condição só pode incluir atributos do documento da pasta de onde o documento está sendo adicionado ou removido.

  • O campomessages pode ser usado para enviar uma lista de mensagens ao canal do Pub/Sub. Além dessas mensagens, por padrão, os seguintes campos também são publicados:

    • Nome do esquema, nome do documento, tipo de gatilho, nome do conjunto de regras, ID da regra, ID da ação.
    • Para gatilhos de criação e exclusão de links, as notificações incluem informações relevantes sobre o link que está sendo adicionado ou excluído.