En esta página, se ofrece una breve descripción general de las carpetas y se explica cómo administrar documentos con ellas.
Motor de políticas y reglas
En Document Warehouse, Policy Engine permite a los usuarios definir y ejecutar operaciones comunes en documentos (por ejemplo, validar o actualizar) mientras crean o actualizan documentos.
Reglas y RuleSet
A un nivel general, una regla hace referencia a una configuración definida por el usuario que especifica lo siguiente:
- qué activa la verificación de reglas
- qué condición se evalúa
- qué acciones se ejecutan cuando se cumple la condición.
Junto con estas especificaciones, una regla incluye información de la descripción, la fuente, el destino y la condición de activación.
Una colección lógica de reglas se denomina RuleSet. Por ejemplo, las reglas que operan en el mismo esquema se pueden agrupar en un solo RuleSet. Los clientes pueden definir varios RuleSets.
Las reglas son útiles para activar automáticamente acciones predefinidas mientras se crean o actualizan documentos.
Una regla consta de tres elementos principales:
- TriggerType: Es el evento en el que se debe iniciar la verificación de la regla. Los tipos de activadores admitidos son Create y Update.
- Condición de la regla: Es la condición que se evalúa después de que se detecta un determinado tipo de activador. Las condiciones se pueden expresar con Common Expression Language (CEL). Cada condición debe evaluarse como un resultado booleano.
- Acciones: Es el conjunto de pasos que se ejecutan cuando se cumple la regla. Cuando una condición de regla se evalúa como verdadera, se ejecuta la acción correspondiente (configurada en la regla). A continuación, se indican los detalles generales sobre las acciones específicas implementadas en Document Warehouse:
- Acción de validación de datos: Acción que permite validar campos específicos en el documento durante la creación o actualización del documento.
- Acción de actualización de datos: Acción que permite actualizar campos específicos en el documento durante la creación o actualización del documento. Estas actualizaciones se ejecutan cuando se cumple la condición de la regla.
- Acción de borrado de documentos: Acción que permite borrar el documento durante la actualización cuando ciertos campos cumplen con los criterios de borrado definidos con las condiciones de la regla.
- Acción de inclusión de carpetas: Acción que agrega automáticamente un documento nuevo (o actualizado) en carpetas específicas. Estas carpetas se pueden especificar directamente con su nombre.
- Acción para quitar de la carpeta: Acción que quita automáticamente un documento nuevo de las carpetas especificadas cuando se cumple una condición a nivel de la regla.
- Access Control Action: Acción que permite actualizar las listas de control de acceso (vinculaciones de grupos y usuarios) durante la creación de documentos. Estas actualizaciones se ejecutan cuando se cumple la condición de la regla.
- Acción de publicación: Es la acción que publica mensajes específicos en el canal de Pub/Sub del usuario cuando se cumple una condición a nivel de la regla.
Administrar conjuntos de reglas
Document Warehouse proporciona APIs para administrar RuleSets (Create, Get, Update, Delete, List). En esta sección, se proporcionan muestras para configurar diferentes tipos de reglas.
Crea un RuleSet
Para crear un conjunto de reglas, haz lo siguiente:
REST
Solicitud:
# 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."
}'Respuesta
{
"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 obtener más información, consulta la documentación de referencia de la API de Document AI Warehouse Python.
Para autenticarte en Document AI Warehouse, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Java
Para obtener más información, consulta la documentación de referencia de la API de Document AI Warehouse Java.
Para autenticarte en Document AI Warehouse, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.
Enumera RuleSets
Para enumerar los conjuntos de reglas en un proyecto, haz lo siguiente:
REST
Solicitud:
# 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/ruleSetsRespuesta
{
"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"
}
]
}Obtén un RuleSet
Para obtener un conjunto de reglas con su nombre, haz lo siguiente:
REST
Solicitud:
# 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_SETRespuesta
{
"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"
}Borra un RuleSet
Para borrar un conjunto de reglas con su nombre, haz lo siguiente:
REST
Solicitud:
# 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_SETAcciones de reglas
En esta sección, se analizarán las expresiones de reglas y los ejemplos de acciones de cada regla.
Condiciones de ejemplo
Una condición hace referencia a la expresión especificada con Common Expression Language.
Ejemplos:
- Expresión de campo de cadena
STATE == \'CA\'. Comprueba si el valor del campoSTATEes igual aCA.NAME != \'\'. Comprueba que el valor del campoNAMEno esté vacío.
- Expresión de campo numérico
FILING_COST > 10.0. Comprueba si el valor del campoFILING_COST(definido como float) es mayor que10.0.
Cómo verificar si un documento pertenece a un esquema específico
Para hacer referencia a un tipo de esquema específico, usa el nombre de campo especial documentType (es una palabra reservada). Se evalúa en función del campo DisplayName en DocumentSchema.
Ejemplo:
documentType == \'W9\'
La condición anterior verifica si el esquema del documento (con la palabra clave documentType) tiene un nombre visible de W9.
Cómo hacer referencia a los valores de propiedades de documentos existentes o antiguos y a los valores de propiedades de documentos nuevos
Para admitir condiciones que incluyen propiedades existentes y propiedades recién proporcionadas, usa los siguientes dos prefijos con un operador DOT para acceder a la versión específica de la propiedad:
OLD_para hacer referencia a las propiedades de documentos existentesNEW_para hacer referencia a las nuevas propiedades del documento en la solicitud
Ejemplo:
OLD_.state == \'TX\' && NEW_.state == \'CA\'Comprueba que el valor existente de la propiedad de estado seaTXy que el valor nuevo proporcionado seaCA.
Administración de campos de fecha
Para el documento DriverLicense, si el EXPIRATION_DATE es anterior a una fecha determinada
- Actualiza (o agrega uno nuevo si no existe)
EXPIRATION_STATUS(campo de enumeración) con un valor igual aEXPIRING_BEFORE_CLOSING_DATE.
Para agregar valores de fecha, usa la función de marca de tiempo como se muestra en el siguiente ejemplo.
REST
Solicitud:
# 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"
}
}
}
}
]
}'Regla de validación de datos
Valida un documento W9 para el campo de texto STATE de California:
- Comprueba que
NAME(campo de texto) no esté vacío. Verifica que el
FILING_COST(campo de número de punto flotante) sea mayor que10.0.
REST
Solicitud:
# 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."
}'Regla de actualización de datos
En el caso de un documento W9, si el campo BUSINESS_NAME es Google, se cumple lo siguiente:
- Actualiza (o agrega uno nuevo si no existe) un campo
Addressigual a1600 Amphitheatre Pkwy. Actualiza (o agrega uno nuevo si no existe) un campo
EINigual a77666666.
REST
Solicitud:
# 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"
}
}
}
}
]
}'Regla de eliminación de documentos
Cuando se actualiza el documento W9, si el campo BUSINESS_NAME cambia a Google, se borra el documento.
REST
Solicitud:
# 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
}
}
}
]
}'Regla de control de acceso
Mientras se actualiza el documento W9, si el campo BUSINESS_NAME es Google, se actualizan las vinculaciones de políticas que controlan el acceso al documento.
Agregar una vinculación nueva
Cuando un documento satisface la condición de la regla, sucede lo siguiente:
- Agrega el rol de editor para
user:a@example.comygroup:xxx@example.com Se agrega el rol de visualizador para
user:b@example.comygroup:yyy@example.com
REST
Solicitud:
# 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"]
}
]
}
}
}
}
]
}'Reemplaza una vinculación existente
Cuando un documento satisface la condición de la regla, reemplaza la vinculación existente para incluir solo el rol de Editor para user:a@example.com y group:xxx@example.com.
REST
Solicitud:
# 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"]
}
]
}
}
}
}
]
}'Regla de agregar a carpeta
Cuando se crea o actualiza una carpeta, se puede agregar a carpetas estáticas predefinidas o a carpetas que coincidan con ciertos criterios de búsqueda.
Configura carpetas estáticas
Cuando se crea un nuevo DriverLicense, se agrega a la carpeta ya creada.
REST
Solicitud:
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 en Pub/Sub
Cuando se crea o actualiza un documento, o se crea o borra un vínculo, puedes enviar un mensaje de notificación al canal de Pub/Sub.
Pasos para usar la función
- Crea un tema de Pub/Sub en el proyecto del cliente.
- Crea una regla para activar la acción de publicación de Pub/Sub con la siguiente solicitud. (Consulta el siguiente ejemplo).
- Invoca las APIs de Document AI Warehouse.
- Verifica que los mensajes se publiquen en el canal de Pub/Sub.
Ejemplo de regla
Cuando se agrega un documento en una carpeta (se invoca la API de CreateLink), se puede usar la siguiente regla para enviar mensajes de notificación al tema de Pub/Sub.
REST
Solicitud:
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."
}
}
}
]
}'Detalles de la regla
Esta acción se admite para los siguientes tipos de activadores:
ON_CRATE: Cuando se crea un documento nuevo.ON_UPDATE: Cuando se actualiza el documentoON_CRATE_LINK: Cuando se crea un vínculo nuevoON_DELETE_LINK: Cuando se borra un vínculo
En el caso de los activadores Create y Update Document, la condición puede incluir atributos del documento que se está creando o actualizando.
En el caso de los activadores Create Link y Delete Link, la condición solo puede incluir atributos del documento Folder desde el que se agrega o quita el documento.
El campo
messagesse puede usar para enviar una lista de mensajes al canal de Pub/Sub. Ten en cuenta que, junto con estos mensajes, de forma predeterminada, también se publican los siguientes campos:- Nombre del esquema, nombre del documento, tipo de activador, nombre del conjunto de reglas, ID de regla, ID de acción
- En el caso de los activadores de vínculos de creación y eliminación, las notificaciones incluyen información relevante sobre el vínculo que se agrega o borra.