Esta página oferece uma breve visão geral das pastas e explica como gerenciar documentos usando pastas.
Policy Engine e regras
Na 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 e
- quais ações são executadas quando a condição é atendida.
Além dessas especificações, uma regra inclui informações da descrição, origem, destino e condição de acionamento.
Uma coleção lógica de regras é chamada de RuleSet. Por exemplo, as regras que operam no mesmo esquema podem ser agrupadas em um único RuleSet. Os clientes podem definir vários RuleSets.
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 de regras precisa ser iniciada. Os tipos de acionador compatíveis são "Criar" e "Atualizar".
- Condição de regra: a condição que é 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 na Document Warehouse:
- Ação de validação de dados: ação que permite validar campos específicos no documento durante a criação ou atualização do documento.
- Ação de atualização de dados: ação que permite atualizar campos específicos no documento durante a criação ou atualização do documento. Essas atualizações são executadas quando a condição da regra é atendida.
- Ação de exclusão de documento: ação que permite excluir o documento durante a atualização do documento 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 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 determinadas pastas 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 do documento. 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 RuleSets
A Document Warehouse oferece APIs para gerenciar RuleSets (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 Document AI Warehouse Python.
Para autenticar na Document AI Warehouse, configure o Application Default Credentials. Se quiser mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Java
Para mais informações, consulte a Document AI Warehouse Java API documentação de referência.
Para autenticar na Document AI Warehouse, configure o Application Default Credentials. Se quiser 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 abordará as expressões de regra e cada exemplo de ação de 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\'. Verifica se o valor do campoSTATEé igual aCANAME != \'\'. Verifica se o valor do campoNAMEnão está vazio.
- Expressão de campo numérico
FILING_COST > 10.0. Verifica se o valor do campoFILING_COST(definido como float) é 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 do 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 de W9.
Como se referir a valores de propriedade de documentos antigos/atuais 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 de documentos na solicitação.
Exemplo:
OLD_.state == \'TX\' && NEW_.state == \'CA\'Verifica se o valor atual da propriedade de estado éTXe o novo valor fornecido éCA.
Tratamento de campos de data
Para o documento DriverLicense, se a EXPIRATION_DATE for anterior a uma determinada data
- Atualize (ou adicione um novo, se ausente)
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 STATE (campo de texto) da Califórnia:
- Verifique se o
NAME(campo de texto) não está vazio. Verifique se o
FILING_COST(campo 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:
- Atualize (ou adicione um novo, se ausente) um campo
Addressigual a1600 Amphitheatre Pkwy. Atualize (ou adicione 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 o papel 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 atende à condição da regra, substitua a vinculação atual para incluir apenas o papel 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 em pastas estáticas predefinidas ou pastas que correspondam a determinados critérios de pesquisa.
Configurar pastas estáticas
Quando uma nova DriverLicense é criada, ela é adicionada à 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, é possível 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 solicitação a seguir. Consulte o exemplo a seguir.
- Invoque as APIs da Document AI Warehouse.
- Verifique se as mensagens são publicadas no canal do Pub/Sub.
Regra de exemplo
Quando um documento é adicionado a uma pasta (a API CreateLink é invocada), a regra a seguir 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 acionador:
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 acionadores de criação e atualização de documentos, a condição pode incluir atributos do documento que está sendo criado ou atualizado.
Para acionadores de criação e exclusão de links, a condição só pode incluir atributos do documento da pasta em que o documento está sendo adicionado ou removido.
O campo
messagespode ser usado para enviar uma lista de mensagens ao canal do Pub/Sub. Observe que, além dessas mensagens, os seguintes campos também são publicados por padrão:- Nome do esquema, nome do documento, tipo de acionador, nome do RuleSet, ID da regra, ID da ação.
- Para acionadores de criação e exclusão de links, as notificações incluem informações relevantes do link que está sendo adicionado ou excluído.