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.
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.
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/ruleSetsResposta
{
"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_SETResposta
{
"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_SETAçõ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 campoSTATEé igual aCA.NAME != \'\'. Verifique se o valor do campoNAMEnão está vazio.
- Expressão de campo numérico
FILING_COST > 10.0. Verifique se o valor do campoFILING_COST(definido como ponto flutuante) é maior que10.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 éTXe 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 aEXPIRING_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 que10.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
Addressigual a1600 Amphitheatre Pkwy. Atualiza (ou adiciona um novo, se ausente) um campo
EINigual a77666666.
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.comegroup:xxx@example.com. Adiciona a função de leitor para
user:b@example.comegroup: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 campo
messagespode 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.